inc/FUiCtrlKeypad.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0/
  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
 229          *                      - If the keypad style is set to password, the input mode category is ignored.
 230          *                      - The orientation mode of the keypad is decided based on the G-sensor value.
 231          *                      - The default owner will be the current Form (or Frame). It is possible that this control may not be visible
 232          * due to this ownership relationship. @n In this case, use the SetOwner() method to change the ownership to the top-most window.
 233          */
 234         result Construct(KeypadStyle keypadStyle, int limitLength);
 235
 236         /**
 237          * @if OSPDEPREC
 238          * Initializes this instance of %Keypad with input styles.
 239          *
 240          * @brief <i> [Deprecated]  </i>
 241          * @deprecated We no longer provide a method to specify the list of styles which the user can set the keypad to. @n
 242          *                         It is recommended to use the other Construct() method and the KeypadStyle enumeration instead.
 243          * @since               2.0
 244          *
 245          * @return              An error code
 246          * @param[in]   keypadStyle                 The style of %Keypad
 247          * @param[in]   category                    The initial category that the keypad would show first
 248          * @param[in]   limitLength                 The limit of the length of text in EditField
 249          * @exception   E_SUCCESS               The method is successful.
 250          * @exception   E_INVALID_ARG       A specified input parameter is invalid, or @n
 251          *                                                                      the specified @c limitLength is less than or equal to @c 0.
 252          * @exception   E_SYSTEM                A system error has occurred.
 253          * @remarks
 254          *                      - If the keypad style is set to password, the input mode category is ignored.
 255          *                      - The orientation mode of the keypad is decided based on the G-sensor value.
 256          * @endif
 257          */
 258         result Construct(KeypadStyle keypadStyle, KeypadInputModeCategory category, int limitLength = 100);
 259
 260         /**
 261         * Checks whether the text prediction is enabled.
 262         *
 263         * @since 2.0
 264         * @return                @c true if the text prediction is enabled, @n
 265         *                                 else @c false
 266         * @see                      SetTextPredictionEnabled()
 267         */
 268         bool IsTextPredictionEnabled(void) const;
 269
 270         /**
 271         * Enables or disables the text prediction.
 272         *
 273         * @since 2.0
 274         * @param[in]           enable                       Set to @c true to enable the text prediction, @n
 275         *                                                                    else @c false
 276         * @return                An error code
 277         * @exception           E_SUCCESS                The method is successful.
 278         * @exception            E_UNSUPPORTED_OPERATION     This operation is not supported.
 279         * @see                      IsTextPredictionEnabled()
 280         */
 281         result SetTextPredictionEnabled(bool enable);
 282
 283         /**
 284          * Enables single-line editing.
 285          *
 286          * @since          2.0
 287          *
 288          * @return         An error code
 289          * @param[in]      enabled                      Set to @c true to enable single-line editing, @n
 290          *                                                                                              else @c false
 291          * @exception      E_SUCCESS                    The method is successful.
 292          * @exception      E_INVALID_OPERATION          The current state of the instance prohibits the execution of the specified operation. @n
 293          *                                              The %Keypad control is currently visible.
 294          * @exception      E_UNSUPPORTED_OPERATION      The current state of the instance does not support the execution of the specified operation. @n
 295          *                                              The password style does not support multi-line editing.
 296          * @exception      E_SYSTEM                     A system error has occurred.
 297          * @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).
 298          */
 299         result SetSingleLineEnabled(bool enabled);
 300
 301         /**
 302          * Checks whether single-line editing is enabled.
 303          *
 304          * @since               2.0
 305          *
 306          * @return              @c true if single-line editing is enabled, @n
 307          *                              else @c false
 308          */
 309         bool IsSingleLineEnabled(void) const;
 310
 311         /**
 312          * Adds a ITextEventListener instance. @n
 313          * The added listener can listen to text changed events when they are fired.
 314          *
 315          * @since                       2.0
 316          *
 317          * @param[in]   listener    The listener to add
 318          */
 319         void AddTextEventListener(Tizen::Ui::ITextEventListener& listener);
 320
 321         /**
 322          * Removes a ITextEventListener instance. @n
 323          * The removed listener cannot listen to events when they are fired.
 324          *
 325          * @since                       2.0
 326          *
 327          * @param[in]   listener    The listener to remove
 328          */
 329         void RemoveTextEventListener(Tizen::Ui::ITextEventListener& listener);
 330
 331         /**
 332          * Gets the text of the %Keypad control.
 333          *
 334          * @since               2.0
 335          *
 336          * @return              The string value
 337          */
 338         Tizen::Base::String GetText(void) const;
 339
 340         /**
 341          * Sets the text of the %Keypad control.
 342          *
 343          * @since               2.0
 344          *
 345          * @param[in]   text    The text to set
 346          */
 347         void SetText(Tizen::Base::String text);
 348
 349         /**
 350          * Sets the text filter.
 351          *
 352          * @since               2.1
 353          *
 354          * @param[in]           pFilter The filter
 355          * @remarks     The %Keypad control checks with the registered filter to decide whether the user-entered text should be replaced.
 356          */
 357         void  SetEditTextFilter(IEditTextFilter* pFilter);
 358
 359         /**
 360         * Sends opaque command to the input method.
 361         *
 362         * @since     2.1
 363         *
 364         * @param[in] command            The opaque command
 365         * @remarks
 366         *                       - This method can be used to provide domain-specific features that are only known between certain input methods and their clients.
 367         *                       - This method may not work, depending on the active Input Method.
 368         */
 369         void SendOpaqueCommand (const Tizen::Base::String& command);
 370
 371 protected:
 372         friend class _KeypadImpl;
 373
 374 private:
 375         Keypad(const Keypad&);
 376         Keypad& operator =(const Keypad&);
 377
 378 }; // Keypad
 379
 380 }}} // Tizen::Ui::Controls
 381
 382 #endif  // _FUI_CTRL_KEYPAD_H_