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