2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://www.apache.org/licenses/LICENSE-2.0
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.
19 * @file FUiImeInputMethod.h
20 * @brief This is the header file for the %InputMethod class.
22 * This header file contains the declarations of the %InputMethod class.
25 #ifndef _FUI_IME_INPUT_METHOD_H_
26 #define _FUI_IME_INPUT_METHOD_H_
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>
36 namespace Tizen { namespace Ui { namespace Ime {
38 class _InputMethodImpl;
42 * @brief This class provides a standard implementation of the %InputMethod.
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.
52 * @privilege http://tizen.org/privilege/ime
54 * The %InputMethod provides a standard implementation of the %InputMethod.
56 * The following example demonstrates how to use the %InputMethod class.
61 * using namespace Tizen::Ui::Ime;
64 * : public IInputMethodProvider
70 * : public IInputMethodListener
83 * MyImeApp::Construct()
85 * // Gets an instance of InputMethod
86 * InputMethod* pInputMethod = InputMethod::GetInstance();
88 * // Creates an instance of MyProvider and sets it as a provider
89 * MyProvider* pMyProvider = new(std::nothrow) MyProvider();
90 * pInputMethod->SetInputMethodProvider(pMyProvider);
92 * // Creates an instance of MyListener and adds it to the input method
93 * MyListener* pMyListener = new(std::nothrow) MyListener();
94 * pInputMethod->SetInputMethodListener(pMyListener);
100 class _OSP_EXPORT_ InputMethod
101 : public Tizen::Base::Object
105 * Gets an instance of the %InputMethod.
109 * @privilege http://tizen.org/privilege/ime
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.
118 static InputMethod* GetInstance(void);
121 * Sets an instance of the IInputMethodProvider.
125 * @privilege http://tizen.org/privilege/ime
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.
134 void SetInputMethodProvider(IInputMethodProvider* pProvider);
137 * Sets an instance of the IInputMethodListener.
141 * @privilege http://tizen.org/privilege/ime
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.
150 void SetInputMethodListener(IInputMethodListener* pListener);
153 * Deletes text at the position of the cursor.
157 * @privilege http://tizen.org/privilege/ime
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.
166 result DeleteText(int cursorOffset, int length);
169 * Notifies the state of the input panel to the associated text input UI control when the state of an input panel changes.
173 * @privilege http://tizen.org/privilege/ime
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.
180 result NotifyInputPanelState(Tizen::Ui::InputPanelShowState state);
183 * Notifies a point of time when the language of the input method changes.
187 * @privilege http://tizen.org/privilege/ime
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.
193 result NotifyLanguageChanged(void);
196 * Requests the surrounding text from the position of the cursor.
200 * @privilege http://tizen.org/privilege/ime
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.
210 result RequestSurroundingText(int lengthBeforeCursor, int lengthAfterCursor);
213 * Sends a composite text to the associated text input UI control.
217 * @privilege http://tizen.org/privilege/ime
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.
225 result SendCompositeText(const Tizen::Base::String& text);
228 * Sends a key event directly to the associated text input UI control.
232 * @privilege http://tizen.org/privilege/ime
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.
240 result SendKeyEvent(Tizen::Ui::KeyCode code, Tizen::Ui::KeyState state);
243 * Sends text to the associated text input UI control.
247 * @privilege http://tizen.org/privilege/ime
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.
254 result SendText(const Tizen::Base::String& text);
258 // This Construct() is intentionally declared as private so that only the platform can create an instance.
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.
268 result Construct(void);
271 // This default constructor is intentionally declared as private to implement the Singleton semantic.
278 // This destructor is intentionally declared as private to implement the Singleton semantic.
282 virtual ~InputMethod(void);
285 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
289 InputMethod(const InputMethod& rhs);
292 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
296 InputMethod& operator=(const InputMethod& rhs);
299 friend class _InputMethodImpl;
301 _InputMethodImpl* __pInputMethodImpl;
304 }}} // Tizen::Ui::Ime
306 #endif // _FUI_IME_INPUT_METHOD_H_