inc/FUiCtrlKeypad.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://floralicense.org/license/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an AS IS BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17 /**
  18  * @file                FUiCtrlKeypad.h
  19  * @brief       This is the header file for the %Keypad class.
  20  *
  21  * This header file contains the declarations of the %Keypad class.
  22  */
  23
  24 #ifndef _FUI_CTRL_KEYPAD_H_
  25 #define _FUI_CTRL_KEYPAD_H_
  26
  27 #include <FUiCtrlInputTypes.h>
  28 #include <FUiCtrlEditTypes.h>
  29 #include <FUiITextEventListener.h>
  30 #include <FUiWindow.h>
  31
  32 namespace Tizen { namespace  Ui { namespace Controls
  33 {
  34
  35 /**
  36  * @if OSPDEPREC
  37  * @enum     KeypadInputModeCategory
  38  *
  39  * Defines the keypad input mode.
  40  *
  41  * @brief       <i> [Deprecated] </i>
  42  * @deprecated We no longer provide a method to specify the list of styles which the user can set the keypad to, @n
  43  *                        or the current mode to initially set the keypad to, from this list. It is recommended to use the styles offered KeypadStyle enumeration instead.
  44  * @since               2.0
  45  * @endif
  46  */
  47 enum KeypadInputModeCategory
  48 {
  49         KEYPAD_MODE_ALPHA = 0x0001,                             /**< @if OSPDEPREC The alphabetic input mode @endif */
  50         KEYPAD_MODE_PREDICTIVE = 0x0002,                        /**< @if OSPDEPREC The predictive input mode @endif*/
  51         KEYPAD_MODE_NUMERIC = 0x0004,                           /**< @if OSPDEPREC The numeric input mode @endif */
  52         KEYPAD_MODE_SYMBOL = 0x0008                             /**< @if OSPDEPREC The symbolic input mode @endif */
  53 };
  54
  55 /**
  56  * @class       Keypad
  57  * @brief       This class displays a keypad on top of the screen.
  58  *
  59  * @since       2.0
  60  *
  61  * The %Keypad class displays the full screen keypad without using an EditField or EditArea.
  62  *
  63  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_keypad.htm">Keypad</a>.
  64  *
  65  * The following example demonstrates how to use the %Keypad class.
  66  *
  67  * @code
  68 // Sample code for KeypadSample.h
  69 #include <FUi.h>
  70
  71 class KeypadSample
  72         : public Tizen::Ui::Controls::Form
  73         , public Tizen::Ui::IActionEventListener
  74         , public Tizen::Ui::ITextEventListener
  75 {
  76 public:
  77         KeypadSample(void)
  78         : __pKeypad(null){}
  79
  80         bool Initialize(void);
  81         void ShowKeypad(bool show);
  82         virtual result OnInitializing(void);
  83         virtual result OnTerminating(void);
  84
  85         // IActionEventListener
  86         virtual void OnActionPerformed(const Tizen::Ui::Control& source, int actionId);
  87
  88         // ITextEventListener
  89         virtual void OnTextValueChanged(const Tizen::Ui::Control& source);
  90         virtual void OnTextValueChangeCanceled(const Tizen::Ui::Control& source);
  91
  92
  93 private:
  94         static const int ID_BUTTON  = 101;
  95
  96         Tizen::Ui::Controls::Keypad *__pKeypad;
  97 };
  98
  99 // Sample code for KeypadSample.cpp
 100 #include "KeypadSample.h"
 101
 102 using namespace Tizen::Graphics;
 103 using namespace Tizen::Ui::Controls;
 104
 105 bool
 106 KeypadSample::Initialize(void)
 107 {
 108         Construct(FORM_STYLE_NORMAL);
 109         return true;
 110 }
 111
 112 result
 113 KeypadSample::OnInitializing(void)
 114 {
 115         result r = E_SUCCESS;
 116
 117         // Creates an instance of Button and adds it to the form
 118         Button* pButton = new Button();
 119         pButton->Construct(Rectangle(50, 50, 150, 150), L"Show Keypad");
 120         pButton->SetActionId(ID_BUTTON);
 121         pButton->AddActionEventListener(*this);
 122         AddControl(*pButton);
 123
 124         // Creates an instance of Keypad
 125         __pKeypad = new Keypad();
 126         __pKeypad->Construct(KEYPAD_STYLE_NORMAL, KEYPAD_MODE_ALPHA);
 127
 128         // Adds an instance of ITextEventListener
 129         __pKeypad->AddTextEventListener(*this);
 130
 131         return r;
 132 }
 133
 134 void
 135 KeypadSample::ShowKeypad(bool show)
 136 {
 137         // Changes to desired show state
 138         __pKeypad->SetShowState(show);
 139
 140         //Calls Show() of the control
 141         if (show)
 142         {
 143                 __pKeypad->Show();
 144         }
 145         // Calls Invalidate() of the container
 146         else
 147         {
 148                 Invalidate(true);
 149         }
 150 }
 151
 152 result
 153 KeypadSample::OnTerminating(void)
 154 {
 155         result r = E_SUCCESS;
 156
 157         // Deallocates the keypad
 158         delete __pKeypad;
 159
 160         return r;
 161 }
 162
 163 // IActionEventListener implementation
 164 void
 165 KeypadSample::OnActionPerformed(const Tizen::Ui::Control& source, int actionId)
 166 {
 167         switch (actionId)
 168         {
 169         case ID_BUTTON:
 170                 {
 171                         ShowKeypad(true);
 172                 }
 173                 break;
 174
 175         default:
 176                 break;
 177         }
 178 }
 179
 180 // ITextEventListener implementation
 181 void
 182 KeypadSample::OnTextValueChanged(const Tizen::Ui::Control& source)
 183 {
 184         // ....
 185 }
 186
 187 void
 188 KeypadSample::OnTextValueChangeCanceled(const Tizen::Ui::Control& source)
 189 {
 190         // ....
 191 }
 192  * @endcode
 193  */
 194
 195 class _OSP_EXPORT_ Keypad
 196         : public Tizen::Ui::Window
 197 {
 198 //Lifecycle
 199 public:
 200         /**
 201          *      This is the default constructor for this class.
 202          *
 203          * @since               2.0
 204          */
 205         Keypad(void);
 206
 207         /**
 208          * This is the destructor for this class.
 209          *
 210          * @since               2.0
 211          */
 212         virtual ~Keypad(void);
 213
 214         /**
 215          * Initializes this instance of %Keypad with the specified parameters.
 216          *
 217          * @since       2.0
 218          *
 219          * @return      An error code
 220          * @param[in]   keypadStyle             The style of %Keypad
 221          * @param[in]   limitLength         The limit of the length of text in EditField
 222          * @exception   E_SUCCESS               The method is successful.
 223          * @exception   E_INVALID_ARG       A specified input parameter is invalid, or @n
 224          *                                                                      the specified @c limitLength is less than or equal to @c 0.
 225          * @exception   E_SYSTEM            A system error has occurred.
 226          * @remarks     If the keypad style is set to password, the input mode category is ignored.
 227          * @remarks     The orientation mode of the keypad is decided based on the G-sensor value.
 228          */
 229         result Construct(KeypadStyle keypadStyle, int limitLength);
 230
 231         /**
 232          * @if OSPDEPREC
 233          * Initializes this instance of %Keypad with input styles.
 234          *
 235          * @brief <i> [Deprecated]  </i>
 236          * @deprecated We no longer provide a method to specify the list of styles which the user can set the keypad to. @n
 237          *                         It is recommended to use the other Construct() method and the KeypadStyle enumeration instead.
 238          * @since               2.0
 239          *
 240          * @return              An error code
 241          * @param[in]   keypadStyle                 The style of %Keypad
 242          * @param[in]   category                    The initial category that the keypad would show first
 243          * @param[in]   limitLength                 The limit of the length of text in EditField
 244          * @exception   E_SUCCESS               The method is successful.
 245          * @exception   E_INVALID_ARG       A specified input parameter is invalid, or @n
 246          *                                                                      the specified @c limitLength is less than or equal to @c 0.
 247          * @exception   E_SYSTEM                A system error has occurred.
 248          * @remarks             If the keypad style is set to password, the input mode category is ignored.
 249          * @remarks             The orientation mode of the keypad is decided based on the G-sensor value.
 250          * @endif
 251          */
 252         result Construct(KeypadStyle keypadStyle, KeypadInputModeCategory category, int limitLength = 100);
 253
 254         /**
 255          * Checks whether the text prediction is enabled.
 256          *
 257          * @since 2.0
 258          * @return                @c true if the text prediction is enabled, @n
 259          *                                 else @c false
 260          * @see                      SetTextPredictionEnabled()
 261          */
 262         bool IsTextPredictionEnabled(void) const;
 263
 264         /**
 265          * Enables or disables the text prediction.
 266          *
 267          * @since 2.0
 268          * @param[in]           enable                       Set to @c true to enable the text prediction, @n
 269          *                                                                    else @c false
 270          * @return                An error code
 271          * @exception           E_SUCCESS                The method is successful.
 272          * @exception           E_UNSUPPORTED_OPERATION     This operation is not supported.
 273          * @see                      IsTextPredictionEnabled()
 274          */
 275         result SetTextPredictionEnabled(bool enable);
 276
 277         /**
 278          * Enables single-line editing.
 279          *
 280          * @since          2.0
 281          *
 282          * @return         An error code
 283          * @param[in]      enabled                      Set to @c true to enable single-line editing, @n
 284          *                                                                                              else @c false
 285          * @exception      E_SUCCESS                    The method is successful.
 286          * @exception      E_INVALID_OPERATION          The current state of the instance prohibits the execution of the specified operation. @n
 287          *                                              The %Keypad control is currently visible.
 288          * @exception      E_UNSUPPORTED_OPERATION      The current state of the instance does not support the execution of the specified operation. @n
 289          *                                              The password style does not support multi-line editing.
 290          * @exception      E_SYSTEM                     A system error has occurred.
 291          * @remarks        By default, the single-line editing is disabled and the %Keypad control supports multi-lines (except the password style that only supports single-line editing).
 292          */
 293         result SetSingleLineEnabled(bool enabled);
 294
 295         /**
 296          * Checks whether single-line editing is enabled.
 297          *
 298          * @since               2.0
 299          *
 300          * @return              @c true if single-line editing is enabled, @n
 301          *                              else @c false
 302          */
 303         bool IsSingleLineEnabled(void) const;
 304
 305         /**
 306          * Adds a ITextEventListener instance. @n
 307          * The added listener can listen to text changed events when they are fired.
 308          *
 309          * @since                       2.0
 310          *
 311          * @param[in]   listener    The listener to be added
 312          */
 313         void AddTextEventListener(Tizen::Ui::ITextEventListener& listener);
 314
 315         /**
 316          * Removes a ITextEventListener instance. @n
 317          * The removed listener cannot listen to events when they are fired.
 318          *
 319          * @since                       2.0
 320          *
 321          * @param[in]   listener    The listener to be removed
 322          */
 323         void RemoveTextEventListener(Tizen::Ui::ITextEventListener& listener);
 324
 325         /**
 326          * Gets the text of the %Keypad control.
 327          *
 328          * @since               2.0
 329          *
 330          * @return              The string value
 331          */
 332         Tizen::Base::String GetText(void) const;
 333
 334         /**
 335          * Sets the text of the %Keypad control.
 336          *
 337          * @since               2.0
 338          *
 339          * @param[in]   text    The text to be set
 340          */
 341         void SetText(Tizen::Base::String text);
 342
 343 protected:
 344         friend class _KeypadImpl;
 345
 346 private:
 347         Keypad(const Keypad&);
 348         Keypad& operator =(const Keypad&);
 349
 350 }; // Keypad
 351
 352 }}} // Tizen::Ui::Controls
 353
 354 #endif  // _FUI_CTRL_KEYPAD_H_