xbmc/interfaces/legacy/Window.h

   1 /*
   2  *  Copyright (C) 2005-2018 Team Kodi
   3  *  This file is part of Kodi - https://kodi.tv
   4  *
   5  *  SPDX-License-Identifier: GPL-2.0-or-later
   6  *  See LICENSES/README.md for more information.
   7  */
   8
   9 #pragma once
  10
  11 #include "AddonCallback.h"
  12 #include "AddonString.h"
  13 #include "Control.h"
  14 #include "swighelper.h"
  15
  16 #include <limits.h>
  17 #include <mutex>
  18 #include <vector>
  19
  20 namespace XBMCAddon
  21 {
  22   namespace xbmcgui
  23   {
  24     // Forward declare the interceptor as the AddonWindowInterceptor.h
  25     // file needs to include the Window class because of the template
  26     class InterceptorBase;
  27
  28     //
  29     /// \defgroup python_xbmcgui_action Action
  30     /// \ingroup python_xbmcgui
  31     ///@{
  32     /// @brief **Action class.**
  33     ///
  34     /// \python_class{ xbmcgui.Action(): }
  35     ///
  36     /// This class serves in addition to identify carried out
  37     /// \ref kodi_key_action_ids of Kodi and to be able to carry out thereby own
  38     /// necessary steps.
  39     ///
  40     /// The data of this class are always transmitted by callback
  41     /// Window::onAction at a window.
  42     ///
  43     class Action : public AddonClass
  44     {
  45     public:
  46       Action() = default;
  47
  48 #ifndef SWIG
  49       explicit Action(const CAction& caction) { setFromCAction(caction); }
  50
  51       void setFromCAction(const CAction& caction);
  52
  53       long id = -1;
  54       float fAmount1 = 0.0f;
  55       float fAmount2 = 0.0f;
  56       float fRepeat = 0.0f;
  57       unsigned long buttonCode = 0;
  58       std::string strAction;
  59
  60       // Not sure if this is correct but it's here for now.
  61       AddonClass::Ref<Control> control; // previously pObject
  62 #endif
  63
  64 #ifdef DOXYGEN_SHOULD_USE_THIS
  65       ///
  66       /// \ingroup python_xbmcgui_action
  67       /// @brief \python_func{ getId() }
  68       /// To get \ref kodi_key_action_ids
  69       ///
  70       /// This function returns the identification code used by the explained
  71       /// order, it is necessary to determine the type of command from
  72       /// \ref kodi_key_action_ids.
  73       ///
  74       /// @return                      The action's current id as a long or 0 if
  75       ///                              no action is mapped in the xml's.
  76       ///
  77       ///
  78       ///-----------------------------------------------------------------------
  79       ///
  80       /// **Example:**
  81       /// ~~~~~~~~~~~~~{.py}
  82       /// ..
  83       /// def onAction(self, action):
  84       ///   if action.getId() == ACTION_PREVIOUS_MENU:
  85       ///     print('action received: previous')
  86       /// ..
  87       /// ~~~~~~~~~~~~~
  88       ///
  89       getId();
  90 #else
  91       long getId() { XBMC_TRACE; return id; }
  92 #endif
  93
  94 #ifdef DOXYGEN_SHOULD_USE_THIS
  95       ///
  96       /// \ingroup python_xbmcgui_action
  97       /// @brief \python_func{ getButtonCode() }
  98       /// Returns the button code for this action.
  99       ///
 100       /// @return                        [integer] button code
 101       ///
 102       getButtonCode();
 103 #else
 104       long getButtonCode() { XBMC_TRACE; return buttonCode; }
 105 #endif
 106
 107 #ifdef DOXYGEN_SHOULD_USE_THIS
 108       ///
 109       /// \ingroup python_xbmcgui_action
 110       /// @brief \python_func{ getAmount1() }
 111       /// Returns the first amount of force applied to the thumbstick.
 112       ///
 113       /// @return                        [float] first amount
 114       ///
 115       getAmount1();
 116 #else
 117       float getAmount1() { XBMC_TRACE; return fAmount1; }
 118 #endif
 119
 120 #ifdef DOXYGEN_SHOULD_USE_THIS
 121       ///
 122       /// \ingroup python_xbmcgui_action
 123       /// @brief \python_func{ getAmount2() }
 124       /// Returns the second amount of force applied to the thumbstick.
 125       ///
 126       /// @return                        [float] second amount
 127       ///
 128       getAmount2();
 129 #else
 130       float getAmount2() { XBMC_TRACE; return fAmount2; }
 131 #endif
 132     };
 133     ///@}
 134
 135     //==========================================================================
 136     // This is the main class for the xbmcgui.Window functionality. It is tied
 137     //  into the main Kodi windowing system via the Interceptor
 138     //==========================================================================
 139     //
 140     /// \defgroup python_xbmcgui_window Window
 141     /// \ingroup python_xbmcgui
 142     /// @{
 143     /// @brief __GUI window class for Add-Ons.__
 144     ///
 145     /// This class allows over their functions to create and edit windows that
 146     /// can be accessed from an Add-On.
 147     ///
 148     /// Likewise, all functions from here as well in the other window classes
 149     /// \ref python_xbmcgui_window_dialog "WindowDialog",
 150     /// \ref python_xbmcgui_window_xml "WindowXML" and
 151     /// \ref python_xbmcgui_window_dialog_xml "WindowXMLDialog"
 152     /// with inserted and available.
 153     ///
 154     ///
 155     ///--------------------------------------------------------------------------
 156     /// Constructor for window
 157     /// ----------------------------
 158     ///
 159     /// \python_class{ xbmcgui.Window([existingWindowId]): }
 160     ///
 161     /// Creates a new from Add-On usable window class. This is to create
 162     /// window for related controls by system calls.
 163     ///
 164     /// @param existingWindowId       [opt] Specify an id to use an existing
 165     ///                               window.
 166     /// @throws ValueError            if supplied window Id does not exist.
 167     /// @throws Exception             if more then 200 windows are created.
 168     ///
 169     /// Deleting this window will activate the old window that was active
 170     /// and resets (not delete) all controls that are associated with this
 171     /// window.
 172     ///
 173     ///
 174     ///--------------------------------------------------------------------------
 175     ///
 176     /// **Example:**
 177     /// ~~~~~~~~~~~~~{.py}
 178     /// ..
 179     /// win = xbmcgui.Window()
 180     /// width = win.getWidth()
 181     /// ..
 182     /// ~~~~~~~~~~~~~
 183     ///
 184     ///
 185     //
 186     class Window : public AddonCallback
 187     {
 188       friend class WindowDialogMixin;
 189       bool isDisposed = false;
 190
 191       void doAddControl(Control* pControl, CCriticalSection* gcontext, bool wait);
 192       void doRemoveControl(Control* pControl, CCriticalSection* gcontext, bool wait);
 193
 194     protected:
 195 #ifndef SWIG
 196       InterceptorBase* window;
 197       int iWindowId = -1;
 198
 199       std::vector<AddonClass::Ref<Control> > vecControls;
 200       int iOldWindowId = 0;
 201       int iCurrentControlId = 3000;
 202       bool bModal = false;
 203       CEvent m_actionEvent;
 204
 205       bool canPulse = false;
 206
 207       // I REALLY hate this ... but it's the simplest fix right now.
 208       bool existingWindow = true;
 209       bool destroyAfterDeInit = false;
 210
 211       /**
 212        * This only takes a boolean to allow subclasses to explicitly use it. A
 213        * default constructor can be used as a concrete class and we need to tell
 214        * the difference.
 215        * subclasses should use this constructor and not the other.
 216        */
 217       explicit Window(bool discrim);
 218
 219       void deallocating() override;
 220
 221       /**
 222        * This helper retrieves the next available id. It is assumed that the
 223        * global lock is already being held.
 224        */
 225       static int getNextAvailableWindowId();
 226
 227       /**
 228        * Child classes MUST call this in their constructors. It should be an
 229        * instance of Interceptor<P extends CGUIWindow>. Control of memory
 230        * management for this class is then given to the Window.
 231        */
 232       void setWindow(InterceptorBase* _window);
 233
 234       /**
 235        * This is a helper method since popping the previous window id is a common
 236        * function.
 237        */
 238       void popActiveWindowId();
 239
 240       /**
 241        * This is a helper method since getting a control by it's id is a common
 242        * function.
 243        */
 244       Control* GetControlById(int iControlId, CCriticalSection* gc);
 245
 246       SWIGHIDDENVIRTUAL void PulseActionEvent();
 247       SWIGHIDDENVIRTUAL bool WaitForActionEvent(unsigned int milliseconds);
 248 #endif
 249
 250     public:
 251       explicit Window(int existingWindowId = -1);
 252
 253       ~Window() override;
 254
 255 #ifndef SWIG
 256       SWIGHIDDENVIRTUAL bool    OnMessage(CGUIMessage& message);
 257       SWIGHIDDENVIRTUAL bool    OnAction(const CAction &action);
 258       SWIGHIDDENVIRTUAL bool    OnBack(int actionId);
 259       SWIGHIDDENVIRTUAL void    OnDeinitWindow(int nextWindowID);
 260
 261       SWIGHIDDENVIRTUAL bool IsDialogRunning() const
 262       {
 263         XBMC_TRACE;
 264         return false;
 265       }
 266       SWIGHIDDENVIRTUAL bool IsDialog() const
 267       {
 268         XBMC_TRACE;
 269         return false;
 270       }
 271       SWIGHIDDENVIRTUAL bool IsModalDialog() const
 272       {
 273         XBMC_TRACE;
 274         return false;
 275       }
 276       SWIGHIDDENVIRTUAL bool IsMediaWindow() const
 277       {
 278         XBMC_TRACE;
 279         return false;
 280       }
 281       SWIGHIDDENVIRTUAL void    dispose();
 282
 283       /**
 284        * This is called from the InterceptorBase destructor to prevent further
 285        * use of the interceptor from the window.
 286        */
 287       inline void interceptorClear()
 288       {
 289         std::unique_lock<CCriticalSection> lock(*this);
 290         window = NULL;
 291       }
 292 #endif
 293
 294       //
 295       /// @defgroup python_xbmcgui_window_cb Callback functions from Kodi to add-on
 296       /// \ingroup python_xbmcgui_window
 297       /// @{
 298       /// @brief __GUI window callback functions.__
 299       ///
 300       /// Functions to handle control callbacks from Kodi.
 301       ///
 302       /// Likewise, all functions from here as well in the all window classes
 303       /// (\ref python_xbmcgui_window "Window",
 304       /// \ref python_xbmcgui_window_dialog "WindowDialog",
 305       /// \ref python_xbmcgui_window_xml "WindowXML" and
 306       /// \ref python_xbmcgui_window_dialog_xml "WindowXMLDialog") with inserted
 307       /// and available.
 308       ///
 309       /// ------------------------------------------------------------------------
 310       ///
 311       /// @link python_xbmcgui_window Go back to normal functions from window@endlink
 312       //
 313
 314       // callback takes a parameter
 315 #ifdef DOXYGEN_SHOULD_USE_THIS
 316       ///
 317       /// \ingroup python_xbmcgui_window_cb
 318       /// @brief \python_func{ onAction(self, Action action) }
 319       /// **onAction method.**
 320       ///
 321       /// This method will receive all actions that the main program will send
 322       /// to this window.
 323       ///
 324       /// @param self                Own base class pointer
 325       /// @param action              The action id to perform, see
 326       ///                            \ref python_xbmcgui_action to get use
 327       ///                            of them
 328       ///
 329       /// @note
 330       /// - By default, only the `PREVIOUS_MENU` and `NAV_BACK actions` are
 331       ///   handled.
 332       /// - Overwrite this method to let your script handle all actions.
 333       /// - Don't forget to capture `ACTION_PREVIOUS_MENU` or `ACTION_NAV_BACK`,
 334       ///   else the user can't close this window.
 335       ///
 336       ///
 337       ///-----------------------------------------------------------------------
 338       ///
 339       /// **Example:**
 340       /// ~~~~~~~~~~~~~{.py}
 341       /// ..
 342       /// # Define own function where becomes called from Kodi
 343       /// def onAction(self, action):
 344       ///   if action.getId() == ACTION_PREVIOUS_MENU:
 345       ///     print('action received: previous')
 346       ///     self.close()
 347       ///   if action.getId() == ACTION_SHOW_INFO:
 348       ///     print('action received: show info')
 349       ///   if action.getId() == ACTION_STOP:
 350       ///     print('action received: stop')
 351       ///   if action.getId() == ACTION_PAUSE:
 352       ///     print('action received: pause')
 353       /// ..
 354       /// ~~~~~~~~~~~~~
 355       ///
 356       onAction(...);
 357 #else
 358       virtual void onAction(Action* action);
 359 #endif
 360
 361       // on control is not actually on Window in the api but is called into Python anyway.
 362 #ifdef DOXYGEN_SHOULD_USE_THIS
 363       ///
 364       /// \ingroup python_xbmcgui_window_cb
 365       /// @brief \python_func{ onControl(self, Control) }
 366       /// **onControl method.**
 367       ///
 368       /// This method will receive all click events on owned and selected
 369       /// controls when the control itself doesn't handle the message.
 370       ///
 371       /// @param self                Own base class pointer
 372       /// @param control             The \ref python_xbmcgui_control "Control" class
 373       ///
 374       ///
 375       ///-----------------------------------------------------------------------
 376       ///
 377       /// **Example:**
 378       /// ~~~~~~~~~~~~~{.py}
 379       /// ..
 380       /// # Define own function where becomes called from Kodi
 381       /// def onControl(self, control):
 382       ///   print("Window.onControl(control=[%s])"%control)
 383       /// ..
 384       /// ~~~~~~~~~~~~~
 385       ///
 386       void onControl(...);
 387 #else
 388       virtual void onControl(Control* control);
 389 #endif
 390
 391 #ifdef DOXYGEN_SHOULD_USE_THIS
 392       ///
 393       /// \ingroup python_xbmcgui_window_cb
 394       /// @brief \python_func{ onClick(self, int controlId) }
 395       /// **onClick method.**
 396       ///
 397       /// This method will receive all click events that the main program will
 398       /// send to this window.
 399       ///
 400       /// @param self                Own base class pointer
 401       /// @param controlId           The one time clicked GUI control
 402       ///                            identifier
 403       ///
 404       ///
 405       ///-----------------------------------------------------------------------
 406       ///
 407       /// **Example:**
 408       /// ~~~~~~~~~~~~~{.py}
 409       /// ..
 410       /// # Define own function where becomes called from Kodi
 411       /// def onClick(self,controlId):
 412       ///   if controlId == 10:
 413       ///     print("The control with Id 10 is clicked")
 414       /// ..
 415       /// ~~~~~~~~~~~~~
 416       ///
 417       onClick(...);
 418 #else
 419       virtual void onClick(int controlId);
 420 #endif
 421
 422 #ifdef DOXYGEN_SHOULD_USE_THIS
 423       ///
 424       /// \ingroup python_xbmcgui_window_cb
 425       /// @brief \python_func{ onDoubleClick(self, int controlId) }
 426       /// __onDoubleClick method.__
 427       ///
 428       /// This method will receive all double click events that the main program
 429       /// will send to this window.
 430       ///
 431       /// @param self                Own base class pointer
 432       /// @param controlId           The double clicked GUI control
 433       ///                            identifier
 434       ///
 435       ///
 436       ///-----------------------------------------------------------------------
 437       ///
 438       /// **Example:**
 439       /// ~~~~~~~~~~~~~{.py}
 440       /// ..
 441       /// # Define own function where becomes called from Kodi
 442       /// def onDoubleClick(self,controlId):
 443       ///   if controlId == 10:
 444       ///     print("The control with Id 10 is double clicked")
 445       /// ..
 446       /// ~~~~~~~~~~~~~
 447       ///
 448       onDoubleClick(...);
 449 #else
 450       virtual void onDoubleClick(int controlId);
 451 #endif
 452
 453 #ifdef DOXYGEN_SHOULD_USE_THIS
 454       ///
 455       /// \ingroup python_xbmcgui_window_cb
 456       /// @brief \python_func{ onFocus(self, int controlId) }
 457       /// __onFocus method.__
 458       ///
 459       /// This method will receive all focus events that the main program will
 460       /// send to this window.
 461       ///
 462       /// @param self                Own base class pointer
 463       /// @param controlId           The focused GUI control identifier
 464       ///
 465       ///
 466       ///-----------------------------------------------------------------------
 467       ///
 468       /// **Example:**
 469       /// ~~~~~~~~~~~~~{.py}
 470       /// ..
 471       /// # Define own function where becomes called from Kodi
 472       ///  def onDoubleClick(self,controlId):
 473       ///    if controlId == 10:
 474       ///      print("The control with Id 10 is focused")
 475       /// ..
 476       /// ~~~~~~~~~~~~~
 477       ///
 478       onFocus(...);
 479 #else
 480       virtual void onFocus(int controlId);
 481 #endif
 482
 483 #ifdef DOXYGEN_SHOULD_USE_THIS
 484       ///
 485       /// \ingroup python_xbmcgui_window_cb
 486       /// @brief \python_func{ onInit(self) }
 487       /// __onInit method.__
 488       ///
 489       /// This method will be called to initialize the window
 490       ///
 491       /// @param self                Own base class pointer
 492       ///
 493       ///
 494       ///-----------------------------------------------------------------------
 495       ///
 496       /// **Example:**
 497       /// ~~~~~~~~~~~~~{.py}
 498       /// ..
 499       /// # Define own function where becomes called from Kodi
 500       /// def onInit(self):
 501       ///   print("Window.onInit method called from Kodi")
 502       /// ..
 503       /// ~~~~~~~~~~~~~
 504       ///
 505       onInit(...);
 506 #else
 507       virtual void onInit();
 508 #endif
 509       //@}
 510
 511 #ifdef DOXYGEN_SHOULD_USE_THIS
 512       ///
 513       /// \ingroup python_xbmcgui_window
 514       /// @brief \python_func{ show() }
 515       /// Show this window.
 516       ///
 517       /// Shows this window by activating it, calling close() after it wil
 518       /// activate the current window again.
 519       ///
 520       /// @note If your script ends this window will be closed to. To show it
 521       /// forever, make a loop at the end of your script or use doModal()
 522       /// instead.
 523       ///
 524       show();
 525 #else
 526       SWIGHIDDENVIRTUAL void show();
 527 #endif
 528
 529 #ifdef DOXYGEN_SHOULD_USE_THIS
 530       ///
 531       /// \ingroup python_xbmcgui_window
 532       /// @brief \python_func{ setFocus(Control) }
 533       /// Give the supplied control focus.
 534       ///
 535       /// @param Control             \ref python_xbmcgui_control "Control" class to focus
 536       /// @throws TypeError          If supplied argument is not a \ref python_xbmcgui_control "Control"
 537       ///                            type
 538       /// @throws SystemError        On Internal error
 539       /// @throws RuntimeError       If control is not added to a window
 540       ///
 541       setFocus(...);
 542 #else
 543       SWIGHIDDENVIRTUAL void setFocus(Control* pControl);
 544 #endif
 545
 546 #ifdef DOXYGEN_SHOULD_USE_THIS
 547       ///
 548       /// \ingroup python_xbmcgui_window
 549       /// @brief \python_func{ setFocusId(ControlId) }
 550       /// Gives the control with the supplied focus.
 551       ///
 552       /// @param ControlId           [integer] On skin defined id of control
 553       /// @throws SystemError        On Internal error
 554       /// @throws RuntimeError       If control is not added to a window
 555       ///
 556       setFocusId(...);
 557 #else
 558       SWIGHIDDENVIRTUAL void setFocusId(int iControlId);
 559 #endif
 560
 561 #ifdef DOXYGEN_SHOULD_USE_THIS
 562       ///
 563       /// \ingroup python_xbmcgui_window
 564       /// @brief \python_func{ getFocus(Control) }
 565       /// Returns the control which is focused.
 566       ///
 567       /// @return                        Focused control class
 568       /// @throws SystemError            On Internal error
 569       /// @throws RuntimeError           If no control has focus
 570       ///
 571       getFocus();
 572 #else
 573       SWIGHIDDENVIRTUAL Control* getFocus();
 574 #endif
 575
 576 #ifdef DOXYGEN_SHOULD_USE_THIS
 577       ///
 578       /// \ingroup python_xbmcgui_window
 579       /// @brief \python_func{ getFocusId(int) }
 580       /// Returns the id of the control which is focused.
 581       ///
 582       /// @return                        Focused control id
 583       /// @throws SystemError            On Internal error
 584       /// @throws RuntimeError           If no control has focus
 585       ///
 586       getFocusId();
 587 #else
 588       SWIGHIDDENVIRTUAL long getFocusId();
 589 #endif
 590
 591 #ifdef DOXYGEN_SHOULD_USE_THIS
 592       ///
 593       /// \ingroup python_xbmcgui_window
 594       /// @brief \python_func{ removeControl(Control) }
 595       /// Removes the control from this window.
 596       ///
 597       /// @param Control             \ref python_xbmcgui_control "Control" class to remove
 598       /// @throws TypeError          If supplied argument is not a \ref python_xbmcgui_control
 599       ///                            type
 600       /// @throws RuntimeError       If control is not added to this window
 601       ///
 602       /// This will not delete the control. It is only removed from the window.
 603       ///
 604       removeControl(...);
 605 #else
 606       SWIGHIDDENVIRTUAL void removeControl(Control* pControl);
 607 #endif
 608
 609 #ifdef DOXYGEN_SHOULD_USE_THIS
 610       ///
 611       /// \ingroup python_xbmcgui_window
 612       /// @brief \python_func{ removeControls(List) }
 613       /// Removes a list of controls from this window.
 614       ///
 615       /// @param List               List with controls to remove
 616       /// @throws TypeError         If supplied argument is not a \ref python_xbmcgui_control
 617       ///                           type
 618       /// @throws RuntimeError      If control is not added to this window
 619       ///
 620       /// This will not delete the controls. They are only removed from the
 621       /// window.
 622       ///
 623       removeControls(...);
 624 #else
 625       SWIGHIDDENVIRTUAL void removeControls(std::vector<Control*> pControls);
 626 #endif
 627
 628 #ifdef DOXYGEN_SHOULD_USE_THIS
 629       ///
 630       /// \ingroup python_xbmcgui_window
 631       /// @brief \python_func{ getHeight() }
 632       /// Returns the height of this Window instance.
 633       ///
 634       /// @return                       Window height in pixels
 635       ///
 636       ///-----------------------------------------------------------------------
 637       /// @python_v18 Function changed
 638       ///
 639       getHeight();
 640 #else
 641       SWIGHIDDENVIRTUAL long getHeight();
 642 #endif
 643
 644 #ifdef DOXYGEN_SHOULD_USE_THIS
 645       ///
 646       /// \ingroup python_xbmcgui_window
 647       /// @brief \python_func{ getWidth() }
 648       /// Returns the width of this Window instance.
 649       ///
 650       /// @return                       Window width in pixels
 651       ///
 652       ///-----------------------------------------------------------------------
 653       /// @python_v18 Function changed
 654       ///
 655       getWidth();
 656 #else
 657       SWIGHIDDENVIRTUAL long getWidth();
 658 #endif
 659
 660 #ifdef DOXYGEN_SHOULD_USE_THIS
 661       ///
 662       /// \ingroup python_xbmcgui_window
 663       /// @brief \python_func{ setProperty(key, value) }
 664       /// Sets a window property, similar to an infolabel.
 665       ///
 666       /// @param key                 string - property name.
 667       /// @param value               string or unicode - value of property.
 668       ///
 669       /// @note  Key is NOT case sensitive. Setting value to an empty string is
 670       ///        equivalent to clearProperty(key).\n
 671       ///        You can use the above as keywords for arguments and skip
 672       ///        certain optional arguments.\n
 673       ///        Once you use a keyword, all following arguments require the
 674       ///        keyword.
 675       ///
 676       ///
 677       ///-----------------------------------------------------------------------
 678       ///
 679       /// **Example:**
 680       /// ~~~~~~~~~~~~~{.py}
 681       /// ..
 682       /// win = xbmcgui.Window(xbmcgui.getCurrentWindowId())
 683       /// win.setProperty('Category', 'Newest')
 684       /// ..
 685       /// ~~~~~~~~~~~~~
 686       ///
 687       setProperty(...);
 688 #else
 689       SWIGHIDDENVIRTUAL void setProperty(const char* key, const String& value);
 690 #endif
 691
 692 #ifdef DOXYGEN_SHOULD_USE_THIS
 693       ///
 694       /// \ingroup python_xbmcgui_window
 695       /// @brief \python_func{ getProperty(key) }
 696       /// Returns a window property as a string, similar to an infolabel.
 697       ///
 698       /// @param key                string - property name.
 699       ///
 700       /// @note  Key is NOT case sensitive.\n
 701       ///        You can use the above as keywords for arguments and skip
 702       ///        certain optional arguments.
 703       ///        Once you use a keyword, all following arguments require the
 704       ///        keyword.
 705       ///
 706       ///
 707       ///-----------------------------------------------------------------------
 708       ///
 709       /// **Example:**
 710       /// ~~~~~~~~~~~~~{.py}
 711       /// ..
 712       /// win = xbmcgui.Window(xbmcgui.getCurrentWindowId())
 713       /// category = win.getProperty('Category')
 714       /// ..
 715       /// ~~~~~~~~~~~~~
 716       ///
 717       getProperty(...);
 718 #else
 719       SWIGHIDDENVIRTUAL String getProperty(const char* key);
 720 #endif
 721
 722 #ifdef DOXYGEN_SHOULD_USE_THIS
 723       ///
 724       /// \ingroup python_xbmcgui_window
 725       /// @brief \python_func{ clearProperty(key) }
 726       /// Clears the specific window property.
 727       ///
 728       /// @param key                string - property name.
 729       ///
 730       /// @note Key is NOT case sensitive. Equivalent to setProperty(key,'')
 731       ///       You can use the above as keywords for arguments and skip certain
 732       ///       optional arguments.
 733       ///       Once you use a keyword, all following arguments require the
 734       ///       keyword.
 735       ///
 736       ///
 737       ///-----------------------------------------------------------------------
 738       ///
 739       /// **Example:**
 740       /// ~~~~~~~~~~~~~{.py}
 741       /// ..
 742       /// win = xbmcgui.Window(xbmcgui.getCurrentWindowId())
 743       /// win.clearProperty('Category')
 744       /// ..
 745       /// ~~~~~~~~~~~~~
 746       ///
 747       clearProperty(...);
 748 #else
 749       SWIGHIDDENVIRTUAL void clearProperty(const char* key);
 750 #endif
 751
 752 #ifdef DOXYGEN_SHOULD_USE_THIS
 753       ///
 754       /// \ingroup python_xbmcgui_window
 755       /// @brief \python_func{ clearProperties() }
 756       /// Clears all window properties.
 757       ///
 758       ///
 759       ///-----------------------------------------------------------------------
 760       ///
 761       /// **Example:**
 762       /// ~~~~~~~~~~~~~{.py}
 763       /// ..
 764       /// win = xbmcgui.Window(xbmcgui.getCurrentWindowId())
 765       /// win.clearProperties()
 766       /// ..
 767       /// ~~~~~~~~~~~~~
 768       ///
 769       clearProperties();
 770 #else
 771       SWIGHIDDENVIRTUAL void clearProperties();
 772 #endif
 773
 774 #ifdef DOXYGEN_SHOULD_USE_THIS
 775       ///
 776       /// \ingroup python_xbmcgui_window
 777       /// @brief \python_func{ close() }
 778       /// Closes this window.
 779       ///
 780       /// Closes this window by activating the old window.
 781       ///
 782       /// @note The window is not deleted with this method.
 783       ///
 784       close();
 785 #else
 786       SWIGHIDDENVIRTUAL void close();
 787 #endif
 788
 789 #ifdef DOXYGEN_SHOULD_USE_THIS
 790       ///
 791       /// \ingroup python_xbmcgui_window
 792       /// @brief \python_func{ doModal() }
 793       /// Display this window until close() is called.
 794       ///
 795       doModal();
 796 #else
 797
 798       SWIGHIDDENVIRTUAL void doModal();
 799 #endif
 800
 801 #ifdef DOXYGEN_SHOULD_USE_THIS
 802       ///
 803       /// \ingroup python_xbmcgui_window
 804       /// @brief \python_func{ addControl(Control) }
 805       /// Add a \ref python_xbmcgui_control "Control" to this window.
 806       ///
 807       /// @param Control                \ref python_xbmcgui_control "Control" to add
 808       /// @throws TypeError             If supplied argument is not a \ref python_xbmcgui_control
 809       ///                               type
 810       /// @throws ReferenceError        If control is already used in another
 811       ///                               window
 812       /// @throws RuntimeError          Should not happen :-)
 813       ///
 814       /// The next controls can be added to a window atm
 815       ///   | Control-class       | Description                                                |
 816       ///   |---------------------|------------------------------------------------------------|
 817       ///   | \ref python_xbmcgui_control_label       "ControlLabel"        | Label control to show text
 818       ///   | \ref python_xbmcgui_control_fadelabel   "ControlFadeLabel"    | The fadelabel has multiple labels which it cycles through
 819       ///   | \ref python_xbmcgui_control_textbox     "ControlTextBox"      | To show bigger text field
 820       ///   | \ref python_xbmcgui_control_button      "ControlButton"       | Brings a button to do some actions
 821       ///   | \ref python_xbmcgui_control_edit        "ControlEdit"         | The edit control allows a user to input text in Kodi
 822       ///   | \ref python_xbmcgui_control_fadelabel   "ControlFadeLabel"    | The fade label control is used for displaying multiple pieces of text in the same space in Kodi
 823       ///   | \ref python_xbmcgui_control_list        "ControlList"         | Add a list for something like files
 824       ///   | \ref python_xbmcgui_control_group       "ControlGroup"        | Is for a group which brings the others together
 825       ///   | \ref python_xbmcgui_control_image       "ControlImage"        | Controls a image on skin
 826       ///   | \ref python_xbmcgui_control_radiobutton "ControlRadioButton"  | For a radio button which handle boolean values
 827       ///   | \ref python_xbmcgui_control_progress    "ControlProgress"     | Progress bar for a performed work or something else
 828       ///   | \ref python_xbmcgui_control_slider      "ControlSlider"       | The slider control is used for things where a sliding bar best represents the operation at hand
 829       ///   | \ref python_xbmcgui_control_spin        "ControlSpin"         | The spin control is used for when a list of options can be chosen
 830       ///   | \ref python_xbmcgui_control_textbox     "ControlTextBox"      | The text box is used for showing a large multipage piece of text in Kodi
 831       ///
 832       addControl(...);
 833 #else
 834       SWIGHIDDENVIRTUAL void addControl(Control* pControl);
 835 #endif
 836
 837 #ifdef DOXYGEN_SHOULD_USE_THIS
 838       ///
 839       /// \ingroup python_xbmcgui_window
 840       /// @brief \python_func{ addControls(List) }
 841       /// Add a list of Controls to this window.
 842       ///
 843       /// @param List                   List with controls to add
 844       /// @throws TypeError             If supplied argument is not of List
 845       ///                               type, or a control is not of \ref python_xbmcgui_control
 846       ///                               type
 847       /// @throws ReferenceError        If control is already used in another
 848       ///                               window
 849       /// @throws RuntimeError          Should not happen :-)
 850       ///
 851       addControls(...);
 852 #else
 853       SWIGHIDDENVIRTUAL void addControls(std::vector<Control*> pControls);
 854 #endif
 855
 856 #ifdef DOXYGEN_SHOULD_USE_THIS
 857       ///
 858       /// \ingroup python_xbmcgui_window
 859       /// @brief \python_func{ getControl(controlId) }
 860       /// Gets the control from this window.
 861       ///
 862       /// @param controlId              \ref python_xbmcgui_control id to get
 863       /// @throws Exception             If \ref python_xbmcgui_control doesn't exist
 864       ///
 865       /// @remark controlId doesn't have to be a python control, it can be a
 866       /// control id from a Kodi window too (you can find id's in the xml files.
 867       ///
 868       /// @note Not python controls are not completely usable yet
 869       /// You can only use the \ref python_xbmcgui_control functions
 870       ///
 871       getControl(...);
 872 #else
 873       SWIGHIDDENVIRTUAL Control* getControl(int iControlId);
 874 #endif
 875     };
 876     ///@}
 877   }
 878 }