inc/FUiInputConnection.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                FUiInputConnection.h
  20  * @brief       This is the header file for the %InputConnection class.
  21  *
  22  * This header file contains the declarations of the %InputConnection class.
  23  */
  24
  25 #ifndef _FUI_INPUT_CONNECTION_H_
  26 #define _FUI_INPUT_CONNECTION_H_
  27
  28 #include <FGrpFloatRectangle.h>
  29 #include <FGrpRectangle.h>
  30 #include <FUiIInputConnectionEventListener.h>
  31 #include <FUiIInputConnectionEventListenerF.h>
  32 #include <FUiIInputConnectionProvider.h>
  33 #include <FUiInputConnectionTypes.h>
  34
  35 namespace Tizen { namespace Ui {
  36
  37 class _InputConnectionImpl;
  38 class Control;
  39
  40
  41 /**
  42  * @class       InputConnection
  43  * @brief       This is the header file for the %InputConnection class.
  44  * This header file contains the declarations of the %InputConnection class.
  45  * @since 2.0
  46  *
  47  * @final This class is not intended for extension.
  48  *
  49  * The following examples demonstrate how to use the %InputConnection class.
  50  *
  51  * This is a simple editor that uses an %InputConnection.
  52  *
  53  *
  54  * @code
  55 // Sample code for EditorSample.h
  56 #include <FUi.h>
  57 #include <FUiInputConnection.h>
  58 #include <FUiIInputConnectionEventListener.h>
  59
  60 namespace Tizen { namespace Ui {
  61
  62 class EditorSample :
  63 public Tizen::Ui::Controls::Form,
  64 public Tizen::Ui::ITouchEventListener,
  65 public Tizen::Ui::IInputConnectionEventListener,
  66 public Tizen::Ui::IInputConnectionProvider,
  67 public Tizen::Ui::IFocusEventListener,
  68 public Tizen::Ui::IPropagatedKeyEventListener
  69 {
  70 protected:
  71
  72 public:
  73
  74         bool Initialize(void);
  75     virtual result OnInitializing();
  76
  77     result  ShowKeypad();
  78     result  HideKeypad();
  79     virtual void OnInputConnectionPanelShowStateChanged(Tizen::Ui::InputConnection& source, Tizen::Ui::InputPanelShowState showState){};
  80     virtual void OnInputConnectionPanelLanguageChanged(Tizen::Ui::InputConnection& source, Tizen::Locales::LanguageCode language){};
  81     virtual void OnInputConnectionPanelBoundsChanged(Tizen::Ui::InputConnection& source, const Tizen::Graphics::Rectangle& bounds){};
  82     virtual void OnInputConnectionTextPredictionShowStateChanged(Tizen::Ui::InputConnection& source, bool isShown){};
  83     virtual void OnInputConnectionTextPredictionBoundsChanged(Tizen::Ui::InputConnection& source, const Tizen::Graphics::Rectangle& bounds){};
  84     virtual void OnInputConnectionTextCommitted(Tizen::Ui::InputConnection& source, const Tizen::Base::String& committedText);
  85     virtual void OnInputConnectionComposingTextChanged(Tizen::Ui::InputConnection& source, const Tizen::Base::String& preEditText, int cursorPosition){};
  86     virtual void DeleteSurroundingText(Tizen::Ui::InputConnection& source, int offset, int chars){};
  87     virtual void GetPreviousText(Tizen::Ui::InputConnection& source, Tizen::Base::String& text, int& cursorPosition){};
  88
  89     virtual void OnTouchPressed(const Tizen::Ui::Control& source, const Tizen::Graphics::Point& currentPosition, const Tizen::Ui::TouchEventInfo & touchInfo){};
  90     virtual void OnTouchReleased(const Tizen::Ui::Control& source, const Tizen::Graphics::Point& currentPosition, const Tizen::Ui::TouchEventInfo& touchInfo);
  91     virtual void OnTouchMoved(const Tizen::Ui::Control& source, const Tizen::Graphics::Point& currentPosition, const Tizen::Ui::TouchEventInfo& touchInfo){};
  92     virtual void OnTouchFocusIn(const Tizen::Ui::Control& source, const Tizen::Graphics::Point& currentPosition, const Tizen::Ui::TouchEventInfo& touchInfo){};
  93     virtual void OnTouchFocusOut(const Tizen::Ui::Control& source, const Tizen::Graphics::Point& currentPosition, const Tizen::Ui::TouchEventInfo& touchInfo){};
  94
  95     virtual void OnFocusGained(const Tizen::Ui::Control& source);
  96         virtual void OnFocusLost(const Tizen::Ui::Control& source);
  97
  98         virtual bool OnKeyPressed(Control& source, const KeyEventInfo& keyEventInfo) {return false;};
  99         virtual bool OnKeyReleased(Control& source, const KeyEventInfo& keyEventInfo) {return false;};
 100         virtual bool OnPreviewKeyPressed(Control& source, const KeyEventInfo& keyEventInfo) {return false;};
 101         virtual bool OnPreviewKeyReleased(Control& source, const KeyEventInfo& keyEventInfo) {return false;};
 102 private:
 103     InputConnection* __pImf;
 104     bool __bindStatus;
 105     Tizen::Ui::Controls::Button* __pButton;
 106 };
 107
 108 }}
 109
 110  * @endcode
 111  *
 112  * @code
 113 // Sample code for EditorSample.cpp
 114 #include "EditorSample.h"
 115
 116 using namespace Tizen::Graphics;
 117 using namespace Tizen::Ui;
 118 using namespace Tizen::Ui::Controls;
 119
 120 bool
 121 EditorSample::Initialize(void)
 122 {
 123         Construct(FORM_STYLE_NORMAL);
 124     return true;
 125 }
 126
 127 void
 128 EditorSample::OnInputConnectionTextCommitted(InputConnection& source, const Tizen::Base::String& committedText)
 129 {
 130         __pButton->SetText(committedText);
 131         __pButton->Invalidate(true);
 132 }
 133
 134 result
 135 EditorSample::OnInitializing()
 136 {
 137     result r = E_SUCCESS;
 138
 139     //create Button
 140         __pButton = new (std::nothrow) Button();
 141         __pButton->Construct(FloatRectangle(180.0f, 200.0f, 360.0f, 200.0f), L"Text Display");
 142         __pButton->SetFocusable(true);
 143         __pButton->AddFocusEventListener(*this);
 144         __pButton->AddTouchEventListener(*this);
 145         __pButton->SetPropagatedKeyEventListener(this);
 146         AddControl(__pButton);
 147
 148     __bindStatus = false;
 149
 150     // Creates an instance of InputConnection
 151     __pImf = new (std::nothrow) InputConnection();
 152     __pImf->Construct(__pButton, *this, *this);
 153
 154     return r;
 155 }
 156
 157 result
 158 EditorSample::ShowKeypad()
 159 {
 160     result r = E_SUCCESS;
 161
 162     if(!__bindStatus)
 163     {
 164         __pImf->BindInputMethod();
 165         __bindStatus = true;
 166         __pImf->ShowInputPanel();
 167     }
 168
 169     return r;
 170 }
 171
 172 result
 173 EditorSample::HideKeypad()
 174 {
 175     result r = E_SUCCESS;
 176
 177     if (__bindStatus != false)
 178     {
 179         __pImf->HideInputPanel();
 180         __pImf->UnbindInputMethod();
 181         __bindStatus = false;
 182     }
 183
 184     return r;
 185 }
 186
 187 void
 188 EditorSample::OnTouchReleased(const Control& source, const Point& currentPosition, const TouchEventInfo& touchInfo)
 189 {
 190
 191     if(!__bindStatus)
 192     {
 193         __pButton->SetFocus();
 194     }
 195     else
 196     {
 197         SetFocus();
 198     }
 199 }
 200
 201 void
 202 EditorSample::OnFocusGained(const Tizen::Ui::Control& source)
 203 {
 204         ShowKeypad();
 205 }
 206
 207 void
 208 EditorSample::OnFocusLost(const Tizen::Ui::Control& source)
 209 {
 210         HideKeypad();
 211 }
 212  * @endcode
 213  *
 214  */
 215
 216 class _OSP_EXPORT_ InputConnection
 217         : public Tizen::Base::Object
 218 {
 219 public:
 220         /**
 221          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 222          *
 223          * @since 2.0
 224          */
 225         InputConnection(void);
 226
 227         /**
 228          * This destructor overrides Tizen::Base::Object::~Object().
 229          *
 230          * @since 2.0
 231          */
 232         virtual ~InputConnection(void);
 233
 234         /**
 235          * Initializes this instance of %InputConnection with the specified parameter.
 236          *
 237          * @since 2.0
 238          * @return              An error code
 239          * @param[in]           pControl                                The source object for connecting the Input Method.
 240          * @param[in]           listener                        An instance of the %IInputConnectionEventListener for processing the event
 241          * @param[in]           provider                        The %InputConnection provider
 242          * @exception           E_SUCCESS                       The method is successful.
 243          * @exception           E_INVALID_ARG           A specified input parameter is invalid.
 244          * @exception           E_SYSTEM                        The method cannot proceed due to a severe system error.
 245          */
 246         result Construct(const Control* pControl, IInputConnectionEventListener& listener, IInputConnectionProvider& provider);
 247
 248         /**
 249          * Initializes this instance of %InputConnection with a specified parameter.
 250          *
 251          * @since 2.1
 252          *
 253          * @return              An error code
 254          * @param[in]           pControl                                The source object for connecting the Input Method
 255          * @param[in]           listener                        An instance of %IInputConnectionEventListenerF for processing the event
 256          * @param[in]           provider                        The %InputConnection provider
 257          * @exception           E_SUCCESS                       The method is successful.
 258          * @exception           E_INVALID_ARG           A specified input parameter is invalid.
 259          * @exception           E_SYSTEM                        The method cannot proceed due to a severe system error.
 260          */
 261         result Construct(const Control* pControl, IInputConnectionEventListenerF& listener, IInputConnectionProvider& provider);
 262
 263         /**
 264          * Binds the %InputConnection to the current active Input Method
 265          *
 266          * @since 2.0
 267          * @return              An error code
 268          * @exception           E_SUCCESS                       The method is successful.
 269          * @exception           E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
 270          * @see                 UnbindInputMethod()
 271          * @remarks             This method should be called when the %Control object has the input focus.
 272          */
 273         result BindInputMethod(void);
 274
 275         /**
 276          * Unbinds the %InputConnection from the current active Input Method. It will no longer be valid for the Input Method.
 277          *
 278          * @since 2.0
 279          * @see                 BindInputMethod()
 280          */
 281         void UnbindInputMethod(void);
 282
 283         /**
 284          * Asks the current active Input Method to show the Input Panel which contains the keyboard.
 285          *
 286          * @since 2.0
 287          * @return              An error code
 288          * @exception           E_SUCCESS                       The method is successful.
 289          * @exception           E_INVALID_STATE         This exception is thrown when BindInputMethod() is not called before calling this method.
 290          * @see                 HideInputPanel()
 291          */
 292         result ShowInputPanel(void);
 293
 294         /**
 295          * Asks the current active Input Method to hide the active Input Panel which contains the keyboard.
 296          *
 297          * @since 2.0
 298          * @return              An error code
 299          * @exception           E_SUCCESS                       The method is successful.
 300          * @exception           E_INVALID_STATE         This exception is thrown when BindInputMethod() is not called before calling this method.
 301          * @see                 ShowInputPanel()
 302          */
 303         result HideInputPanel(void);
 304
 305         /**
 306          * Sets the style of the current active Input Panel.
 307          *
 308          * @since 2.0
 309          * @param[in]           style                           The style of the Input Panel.
 310          * @remarks             This method may not work, depending on the current active Input Method.
 311          */
 312         void SetInputPanelStyle(InputPanelStyle style);
 313
 314         /**
 315          * Sets the auto-capitalization mode.
 316          *
 317          * @since 2.0
 318          * @param[in]           autoCapitalizationMode          The auto-capitalization mode.
 319          * @remarks             This method may not work, depending on the current active Input Method.
 320          */
 321         void SetAutoCapitalizationMode(AutoCapitalizationMode autoCapitalizationMode);
 322
 323         /**
 324          * Finishes text composition.
 325          * This will typically cause the Input Method to exit the composing state.
 326          *
 327          * @since 2.0
 328          * @return              An error code
 329          * @exception           E_SUCCESS                       The method is successful.
 330          * @exception           E_INVALID_STATE         This exception is thrown when BindInputMethod() is not called before calling this method.
 331          */
 332         result FinishTextComposition(void);
 333
 334         /**
 335          * Sets the type of ActionKey.
 336          *
 337          * @since 2.0
 338          * @param[in]           inputPanelAction                        The InputPanel action
 339          * @remarks             This method may not work, depending on the current active Input Method.
 340          */
 341         void SetInputPanelAction(InputPanelAction inputPanelAction);
 342
 343         /**
 344          * Enables or disables the ActionKey.
 345          *
 346          * @since 2.0
 347          * @param[in]           enable                          Set to @c true to enable the ActionKey, @n
 348          *                                                                              else @c false
 349          * @remarks             This method may not work, depending on the current active Input Method.
 350          */
 351         void SetInputPanelActionEnabled(bool enable);
 352
 353         /**
 354         * Sets the language of the current active Input Panel.
 355         *
 356         * @since 2.0
 357         * @param[in]              languageCode                         The language to set
 358         * @exception             E_SUCCESS                            The method is successful.
 359         * @exception             E_OUT_OF_MEMORY                    The memory is insufficient.
 360         * @remarks                This method may not work, depending on the current active Input Method.
 361         */
 362         result SetInputPanelLanguage(Tizen::Locales::LanguageCode languageCode);
 363
 364         /**
 365          * Sets the cursor at the specified position.
 366          *
 367          * @since 2.0
 368          *
 369          * @return              An error code
 370          * @param[in]           position                        The cursor position that is to set
 371          * @exception           E_SUCCESS                       The method is successful.
 372          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 373          * @exception           E_INVALID_STATE         This exception is thrown when BindInputMethod() is not called before calling this method.
 374          */
 375         result SetCursorPosition(int position);
 376
 377         /**
 378          * Sets the bounds of the cursor.
 379          *
 380          * @since 2.0
 381          *
 382          * @return              An error code
 383          * @param[in]           rect                            The rectangle to set
 384          * @exception           E_SUCCESS                       The method is successful.
 385          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 386          * @exception           E_INVALID_STATE         This exception is thrown when BindInputMethod() is not called before calling this method.
 387          */
 388         result SetCursorBounds(const Tizen::Graphics::Rectangle& rect);
 389
 390         /**
 391          * Sets the bounds of the cursor.
 392          *
 393          * @since 2.1
 394          *
 395          * @return              An error code
 396          * @param[in]           rect                            The rectangle to set
 397          * @exception           E_SUCCESS                       The method is successful.
 398          * @exception           E_INVALID_ARG           The specified input parameter is invalid.
 399          * @exception           E_INVALID_STATE         This exception is thrown when BindInputMethod() is not called before calling this method.
 400          */
 401         result SetCursorBounds(const Tizen::Graphics::FloatRectangle& rect);
 402
 403         /**
 404          * Gets the bounds of the current active Input Panel.
 405          *
 406          * @since 2.0
 407          * @return              An instance of the rectangle that represents the position of the top-left corner,
 408          *                      the width, and the height of the Input Panel.
 409          * @exception           E_SUCCESS                       The method is successful.
 410          * @exception           E_INVALID_STATE         This exception is thrown when BindInputMethod() is not called before calling this method.
 411          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 412          */
 413         Tizen::Graphics::Rectangle GetInputPanelBounds(void) const;
 414
 415         /**
 416          * Gets the bounds of the current active Input Panel.
 417          *
 418          * @since 2.1
 419          *
 420          * @return              An instance of the rectangle that represents the position of the top-left corner,
 421          *                      the width, and the height of the Input Panel
 422          * @exception           E_SUCCESS                       The method is successful.
 423          * @exception           E_INVALID_STATE         This exception is thrown when BindInputMethod() is not called before calling this method.
 424          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 425          */
 426         Tizen::Graphics::FloatRectangle GetInputPanelBoundsF(void) const;
 427
 428         /**
 429          * Enables or disables text prediction.
 430          *
 431          * @since 2.0
 432          * @param[in]           enable                          Set to @c true to enable text prediction, @n
 433          *                                                                              else @c false
 434          * @remarks             This method may not work, depending on the current active Input Method.
 435          */
 436         void SetTextPredictionEnabled(bool enable);
 437
 438         /**
 439         * Sends opaque command to the input method.
 440         *
 441         * @since     2.1
 442         *
 443         * @param[in] command            The opaque command
 444         * @remarks   This method can be used to provide domain-specific features that are only known between certain input methods and their clients.
 445         *                   This method may not work, depending on the active Input Method.
 446         */
 447         void SendOpaqueCommand (const Tizen::Base::String& command);
 448
 449 private:
 450         //
 451         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 452         //
 453         // @since 2.0
 454         //
 455         InputConnection(const InputConnection& rhs);
 456
 457         //
 458         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 459         //
 460         // @since 2.0
 461         //
 462         InputConnection& operator=(const InputConnection& rhs);
 463
 464 private:
 465         friend class _InputConnectionImpl;
 466         _InputConnectionImpl* __pInputConnectionImpl;
 467
 468 }; // InputConnection
 469
 470 }} // Tizen::Ui
 471
 472 #endif // _FUI_INPUT_CONNECTION_H_