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