src/FUiImeInputMethod.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 FUiImeInputMethod.h
  20  * @brief This is the header file for the %InputMethod class.
  21  *
  22  * This header file contains the declarations of the %InputMethod class.
  23  */
  24
  25 #ifndef _FUI_IME_INPUT_METHOD_H_
  26 #define _FUI_IME_INPUT_METHOD_H_
  27
  28 #include <FBaseDataType.h>
  29 #include <FBaseObject.h>
  30 #include <FBaseString.h>
  31 #include <FOspConfig.h>
  32 #include <FUiIKeyEventListener.h>
  33 #include <FUiImeIInputMethodListener.h>
  34 #include <FUiImeIInputMethodProvider.h>
  35
  36 namespace Tizen { namespace Ui { namespace Ime {
  37
  38 class _InputMethodImpl;
  39
  40 /**
  41  * @if VISPARTNER
  42  * @class InputMethod
  43  * @brief This class provides a standard implementation of the %InputMethod.
  44  * @since       2.0
  45  *
  46  * @final This class is not intended for extension.
  47  * @remarks     IME application developers can use the %InputMethod to communicate with the associated text input UI control. First, set the provider which
  48  * provides attributes of the soft input panel. Next, set the listener which lets the IME application receive asynchronous callbacks from the input service. These
  49  * allow the IME application to interact with the associated text input UI control properly. After that, request the %InputMethod to send a text or a key event
  50  * which is to be displayed in the associated text input UI control.
  51  *
  52  * @visibility partner
  53  * @privilege http://tizen.org/privilege/ime
  54  *
  55  * The %InputMethod provides a standard implementation of the %InputMethod.
  56  *
  57  * The following example demonstrates how to use the %InputMethod class.
  58  * @code
  59  * #include <new>
  60  * #include <FUi.h>
  61  *
  62  * using namespace Tizen::Ui::Ime;
  63  *
  64  * class MyProvider
  65  *      : public IInputMethodProvider
  66  * {
  67  *      ...
  68  * };
  69  *
  70  * class MyListener
  71  *      : public IInputMethodListener
  72  * {
  73  *      ...
  74  * };
  75  *
  76  * class MyImeApp
  77  * {
  78  * public:
  79  *      ...
  80  *      void Construct();
  81  * };
  82  *
  83  * void
  84  * MyImeApp::Construct()
  85  * {
  86  *      // Gets an instance of InputMethod
  87  *      InputMethod* pInputMethod = InputMethod::GetInstance();
  88  *
  89  *      // Creates an instance of MyProvider and sets it as a provider
  90  *      MyProvider* pMyProvider = new(std::nothrow) MyProvider();
  91  *      pInputMethod->SetInputMethodProvider(pMyProvider);
  92  *
  93  *      // Creates an instance of MyListener and adds it to the input method
  94  *      MyListener* pMyListener = new(std::nothrow) MyListener();
  95  *      pInputMethod->SetInputMethodListener(pMyListener);
  96  * }
  97  * @endcode
  98  *
  99  * @endif
 100  */
 101
 102 class _OSP_EXPORT_ InputMethod
 103         : public Tizen::Base::Object
 104 {
 105 public:
 106         /**
 107         * @if VISPARTNER
 108         * Gets an instance of the %InputMethod.
 109         *
 110         * @since 2.0
 111         * @visibility partner
 112         * @privilege http://tizen.org/privilege/ime
 113         *
 114         * @return An instance of the %InputMethod
 115         * @exception E_SUCCESS The method is successful.
 116         * @exception E_CONNECTION_FAILED The connection to the input service fails.
 117         * @exception E_SYSTEM A failure occurs from the underlying system.
 118         * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
 119         * @remarks The specific error code can be accessed using the GetLastResult() method and OOM might be thrown by this method.
 120         * @endif
 121         */
 122         static InputMethod* GetInstance(void);
 123
 124         /**
 125         * @if VISPARTNER
 126         * Sets an instance of the IInputMethodProvider.
 127         *
 128         * @since 2.0
 129         * @visibility partner
 130         * @privilege http://tizen.org/privilege/ime
 131         *
 132         * @param[in] pProvider An instance of the IInputMethodProvider
 133         * @exception E_SUCCESS The method is successful.
 134         * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
 135         * @remarks The %InputMethod accepts only one provider. So users should unregister the provider by setting @c pProvider as @c null before
 136         * deallocating an instance of the provider.
 137         * @remarks The specific error code can be accessed using the GetLastResult() method.
 138         * @endif
 139         */
 140         void SetInputMethodProvider(IInputMethodProvider* pProvider);
 141
 142         /**
 143         * @if VISPARTNER
 144         * Sets an instance of the IInputMethodListener.
 145         *
 146         * @since 2.0
 147         * @visibility partner
 148         * @privilege http://tizen.org/privilege/ime
 149         *
 150         * @param[in] pListener An instance of the IInputMethodListener
 151         * @exception E_SUCCESS The method is successful.
 152         * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
 153         * @remarks The %InputMethod accepts only one listener. So users should unregister the listener by setting @c pListener as @c null before
 154         * deallocating an instance of the listener.
 155         * @remarks The specific error code can be accessed using the GetLastResult() method.
 156         * @endif
 157         */
 158         void SetInputMethodListener(IInputMethodListener* pListener);
 159
 160         /**
 161         * @if VISPARTNER
 162         * Deletes text at the position of the cursor.
 163         *
 164         * @since 2.0
 165         * @visibility partner
 166         * @privilege http://tizen.org/privilege/ime
 167         *
 168         * @return An error code
 169         * @param[in] cursorOffset The offset value from the cursor position
 170         * @param[in] length The length of the text to delete
 171         * @exception E_SUCCESS The method is successful.
 172         * @exception E_INVALID_ARG The @c length is less than or equal to @c 0.
 173         * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
 174         * @endif
 175         */
 176         result DeleteText(int cursorOffset, int length);
 177
 178         /**
 179         * @if VISPARTNER
 180         * Notifies the state of the input panel to the associated text input UI control when the state of an input panel changes.
 181         *
 182         * @since 2.0
 183         * @visibility partner
 184         * @privilege http://tizen.org/privilege/ime
 185         *
 186         * @return An error code
 187         * @param[in] state The state of the input panel
 188         * @exception E_SUCCESS The method is successful.
 189         * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
 190         * @endif
 191         */
 192         result NotifyInputPanelState(Tizen::Ui::InputPanelShowState state);
 193
 194         /**
 195          * @if VISPARTNER
 196          * Requests the surrounding text from the position of the cursor.
 197          *
 198          * @since 2.0
 199          * @visibility partner
 200          * @privilege http://tizen.org/privilege/ime
 201          *
 202          * @return An error code
 203          * @param[in] lengthBeforeCursor The length of the surrounding text before the cursor
 204          * @param[in] lengthAfterCursor The length of the surrounding text after the cursor
 205          * @exception E_SUCCESS The method is successful.
 206          * @exception E_INVALID_ARG The arguments are less than @c 0.
 207          * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
 208          * @remarks The requested surrounding text can be received using the Tizen::Ui::Ime::IInputMethodListener::OnSurroundingTextReceived() method.
 209          * @endif
 210          */
 211         result RequestSurroundingText(int lengthBeforeCursor, int lengthAfterCursor);
 212
 213         /**
 214         * @if VISPARTNER
 215         * Sends a composite text to the associated text input UI control.
 216         *
 217         * @since 2.0
 218         * @visibility partner
 219         * @privilege http://tizen.org/privilege/ime
 220         *
 221         * @return An error code
 222         * @param[in] text The composite text to send
 223         * @exception E_SUCCESS The method is successful.
 224         * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
 225         * @remarks The composite text means a text which is being modified.
 226         * @endif
 227         */
 228         result SendCompositeText(const Tizen::Base::String& text);
 229
 230         /**
 231         * @if VISPARTNER
 232         * Sends a key event directly to the associated text input UI control.
 233         *
 234         * @since 2.0
 235         * @visibility partner
 236         * @privilege http://tizen.org/privilege/ime
 237         *
 238         * @return An error code
 239         * @param[in] code The key code
 240         * @param[in] state The key state
 241         * @exception E_SUCCESS The method is successful.
 242         * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
 243         * @endif
 244         */
 245         result SendKeyEvent(Tizen::Ui::KeyCode code, Tizen::Ui::KeyState state);
 246
 247         /**
 248         * @if VISPARTNER
 249         * Sends text to the associated text input UI control.
 250         *
 251         * @since 2.0
 252         * @visibility partner
 253         * @privilege http://tizen.org/privilege/ime
 254         *
 255         * @return An error code
 256         * @param[in] text The text to send
 257         * @exception E_SUCCESS The method is successful.
 258         * @exception E_PRIVILEGE_DENIED The application does not have the privilege to call this method.
 259         * @endif
 260         */
 261         result SendText(const Tizen::Base::String& text);
 262
 263 private:
 264         //
 265         // This Construct() is intentionally declared as private so that only the platform can create an instance.
 266         //
 267         // @since 2.0
 268         //
 269         // @return An error code
 270         // @exception E_SUCCESS The method is successful.
 271         // @exception E_CONNECTION_FAILED The connection to the input service fails.
 272         // @exception E_SYSTEM A failure occurs from the underlying system.
 273         // @remarks OOM might be thrown by this method.
 274         //
 275         result Construct(void);
 276
 277         //
 278         // This default constructor is intentionally declared as private to implement the Singleton semantic.
 279         //
 280         // @since 2.0
 281         //
 282         InputMethod(void);
 283
 284         //
 285         // This destructor is intentionally declared as private to implement the Singleton semantic.
 286         //
 287         // @since 2.0
 288         //
 289         virtual ~InputMethod(void);
 290
 291         //
 292         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 293         //
 294         // @since 2.0
 295         //
 296         InputMethod(const InputMethod& rhs);
 297
 298         //
 299         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 300         //
 301         // @since 2.0
 302         //
 303         InputMethod& operator=(const InputMethod& rhs);
 304
 305 private:
 306         _InputMethodImpl* __pInputMethodImpl;
 307 };
 308
 309 }}} // Tizen::Ui::Ime
 310
 311 #endif // _FUI_IME_INPUT_METHOD_H_