xbmc/interfaces/legacy/Keyboard.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 "AddonClass.h"
  12 #include "AddonString.h"
  13 #include "Exception.h"
  14
  15 class CGUIDialogKeyboardGeneric;
  16
  17 namespace XBMCAddon
  18 {
  19   namespace xbmc
  20   {
  21     XBMCCOMMONS_STANDARD_EXCEPTION(KeyboardException);
  22
  23     ///
  24     /// \defgroup python_keyboard Keyboard
  25     /// \ingroup python_xbmc
  26     /// @{
  27     /// @brief **Kodi's keyboard class.**
  28     ///
  29     /// \python_class{ xbmc.Keyboard([default, heading, hidden]) }
  30     ///
  31     /// Creates a new Keyboard object with default text
  32     /// heading and hidden input flag if supplied.
  33     ///
  34     /// @param default    : [opt] string - default text entry.
  35     /// @param heading    : [opt] string - keyboard heading.
  36     /// @param hidden     : [opt] boolean - True for hidden text entry.
  37     ///
  38     ///
  39     ///-------------------------------------------------------------------------
  40     ///
  41     /// **Example:**
  42     /// ~~~~~~~~~~~~~{.py}
  43     /// ..
  44     /// kb = xbmc.Keyboard('default', 'heading', True)
  45     /// kb.setDefault('password') # optional
  46     /// kb.setHeading('Enter password') # optional
  47     /// kb.setHiddenInput(True) # optional
  48     /// kb.doModal()
  49     /// if (kb.isConfirmed()):
  50     ///   text = kb.getText()
  51     /// ..
  52     /// ~~~~~~~~~~~~~
  53     ///
  54     class Keyboard : public AddonClass
  55     {
  56     public:
  57 #ifndef SWIG
  58       String strDefault;
  59       String strHeading;
  60       bool bHidden;
  61       String strText;
  62       bool bConfirmed = false;
  63 #endif
  64
  65       Keyboard(const String& line = emptyString, const String& heading = emptyString, bool hidden = false);
  66       ~Keyboard() override;
  67
  68 #ifdef DOXYGEN_SHOULD_USE_THIS
  69       ///
  70       /// \ingroup python_keyboard
  71       /// @brief \python_func{ doModal([autoclose]) }
  72       /// Show keyboard and wait for user action.
  73       ///
  74       /// @param autoclose      [opt] integer - milliseconds to autoclose
  75       ///                       dialog. (default=do not autoclose)
  76       ///
  77       ///
  78       ///-----------------------------------------------------------------------
  79       ///
  80       /// **Example:**
  81       /// ~~~~~~~~~~~~~{.py}
  82       /// ..
  83       /// kb.doModal(30000)
  84       /// ..
  85       /// ~~~~~~~~~~~~~
  86       ///
  87       doModal(...);
  88 #else
  89       void doModal(int autoclose = 0);
  90 #endif
  91
  92 #ifdef DOXYGEN_SHOULD_USE_THIS
  93       // setDefault() Method
  94       ///
  95       /// \ingroup python_keyboard
  96       /// @brief \python_func{ setDefault(line) }
  97       /// Set the default text entry.
  98       ///
  99       /// @param line        string - default text entry.
 100       ///
 101       ///
 102       ///-----------------------------------------------------------------------
 103       ///
 104       /// **Example:**
 105       /// ~~~~~~~~~~~~~{.py}
 106       /// ..
 107       /// kb.setDefault('password')
 108       /// ..
 109       /// ~~~~~~~~~~~~~
 110       ///
 111       setDefault(...);
 112 #else
 113       void setDefault(const String& line = emptyString);
 114 #endif
 115
 116 #ifdef DOXYGEN_SHOULD_USE_THIS
 117       ///
 118       /// \ingroup python_keyboard
 119       /// @brief \python_func{ setHiddenInput(hidden) }
 120       /// Allows hidden text entry.
 121       ///
 122       /// @param hidden        boolean - True for hidden text entry.
 123       ///
 124       ///
 125       ///-----------------------------------------------------------------------
 126       ///
 127       /// **Example:**
 128       /// ~~~~~~~~~~~~~{.py}
 129       /// ..
 130       /// kb.setHiddenInput(True)
 131       /// ..
 132       /// ~~~~~~~~~~~~~
 133       ///
 134       setHiddenInput(...);
 135 #else
 136       void setHiddenInput(bool hidden = false);
 137 #endif
 138
 139       // setHeading() Method
 140 #ifdef DOXYGEN_SHOULD_USE_THIS
 141       ///
 142       /// \ingroup python_keyboard
 143       /// @brief \python_func{ setHeading(heading) }
 144       /// Set the keyboard heading.
 145       ///
 146       /// @param heading        string - keyboard heading.
 147       ///
 148       ///
 149       ///-----------------------------------------------------------------------
 150       ///
 151       /// **Example:**
 152       /// ~~~~~~~~~~~~~{.py}
 153       /// ..
 154       /// kb.setHeading('Enter password')
 155       /// ..
 156       /// ~~~~~~~~~~~~~
 157       ///
 158       setHeading(...);
 159 #else
 160       void setHeading(const String& heading);
 161 #endif
 162
 163       // getText() Method
 164 #ifdef DOXYGEN_SHOULD_USE_THIS
 165       ///
 166       /// \ingroup python_keyboard
 167       /// @brief \python_func{ getText() }
 168       /// Returns the user input as a string.
 169       ///
 170       /// @note This will always return the text entry even if you cancel the keyboard.
 171       ///       Use the isConfirmed() method to check if user cancelled the keyboard.
 172       ///
 173       /// @return     get the in keyboard entered text
 174       ///
 175       ///
 176       ///-----------------------------------------------------------------------
 177       ///
 178       /// **Example:**
 179       /// ~~~~~~~~~~~~~{.py}
 180       /// ..
 181       /// text = kb.getText()
 182       /// ..
 183       /// ~~~~~~~~~~~~~
 184       ///
 185       getText();
 186 #else
 187       String getText();
 188 #endif
 189
 190       // isConfirmed() Method
 191 #ifdef DOXYGEN_SHOULD_USE_THIS
 192       ///
 193       /// \ingroup python_keyboard
 194       /// @brief \python_func{ isConfirmed() }
 195       /// Returns False if the user cancelled the input.
 196       ///
 197       /// @return     true if confirmed, if cancelled false
 198       ///
 199       ///-----------------------------------------------------------------------
 200       ///
 201       /// **Example:**
 202       /// ~~~~~~~~~~~~~{.py}
 203       /// ..
 204       /// if (kb.isConfirmed()):
 205       ///   ..
 206       /// ~~~~~~~~~~~~~
 207       ///
 208       isConfirmed();
 209 #else
 210       bool isConfirmed();
 211 #endif
 212     };
 213     //@}
 214   }
 215 }