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