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