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