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 <FGrpFloatRectangle.h>
32 #include <FOspConfig.h>
33 #include <FUiIKeyEventListener.h>
34 #include <FUiImeIInputMethodListener.h>
35 #include <FUiImeIInputMethodProvider.h>
36 #include <FUiImeIInputMethodProviderF.h>
38 namespace Tizen { namespace Ui { namespace Ime {
40 class _InputMethodImpl;
44 * @brief This class provides a standard implementation of the %InputMethod class.
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.
53 * The %InputMethod class provides a standard implementation of the %InputMethod class.
55 * The following example demonstrates how to use the %InputMethod class.
60 * using namespace Tizen::Ui::Ime;
63 * : public IInputMethodProvider
69 * : public IInputMethodListener
82 * MyImeApp::Construct()
84 * // Gets an instance of InputMethod
85 * InputMethod* pInputMethod = InputMethod::GetInstance();
87 * // Creates an instance of MyProvider and sets it as a provider
88 * MyProvider* pMyProvider = new(std::nothrow) MyProvider();
89 * pInputMethod->SetInputMethodProvider(pMyProvider);
91 * // Creates an instance of MyListener and adds it to the input method
92 * MyListener* pMyListener = new(std::nothrow) MyListener();
93 * pInputMethod->SetInputMethodListener(pMyListener);
99 class _OSP_EXPORT_ InputMethod
100 : public Tizen::Base::Object
104 * Gets an instance of %InputMethod.
108 * @privilege %http://tizen.org/privilege/ime
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.
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>.
119 static InputMethod* GetInstance(void);
122 * Sets an instance of IInputMethodProvider. @n
123 * The %InputMethod instance accepts only one provider. So users must unregister the provider by setting @c pProvider as @c null before deallocating
124 * an instance of the provider.
128 * @privilege %http://tizen.org/privilege/ime
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.
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.
137 void SetInputMethodProvider(IInputMethodProvider* pProvider);
140 * Sets an instance of IInputMethodProviderF. @n
141 * The %InputMethod instance accepts only one provider. So users must unregister the provider by setting @c pProvider as @c null before deallocating
142 * an instance of the provider.
146 * @privilege %http://tizen.org/privilege/ime
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.
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.
155 void SetInputMethodProviderF(IInputMethodProviderF* pProvider);
158 * Sets an instance of IInputMethodListener. @n
159 * The %InputMethod instance accepts only one listener. So users must unregister the listener by setting @c pListener as @c null before deallocating an
160 * instance of the listener.
164 * @privilege %http://tizen.org/privilege/ime
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.
171 void SetInputMethodListener(IInputMethodListener* pListener);
174 * Deletes a text at the position of the cursor.
178 * @privilege %http://tizen.org/privilege/ime
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 @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.
187 result DeleteText(int cursorOffset, int length);
190 * Notifies the position and the size of the input panel at both the portrait and the landscape orientation.
194 * @privilege %http://tizen.org/privilege/ime
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.
202 result NotifyInputPanelBounds(const Tizen::Graphics::FloatRectangle& portraitBounds, const Tizen::Graphics::FloatRectangle& landscapeBounds);
205 * Notifies the state of the input panel to the associated text input UI control when the state of an input panel changes.
209 * @privilege %http://tizen.org/privilege/ime
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.
216 result NotifyInputPanelState(Tizen::Ui::InputPanelShowState state);
219 * Notifies a point of time when the language of the input method changes.
223 * @privilege %http://tizen.org/privilege/ime
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.
229 result NotifyLanguageChanged(void);
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.
237 * @privilege %http://tizen.org/privilege/ime
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.
246 result RequestSurroundingText(int lengthBeforeCursor, int lengthAfterCursor);
249 * Sends a composite text that is being modified to the associated text input UI control.
253 * @privilege %http://tizen.org/privilege/ime
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.
260 result SendCompositeText(const Tizen::Base::String& text);
263 * Sends a key event directly to the associated text input UI control.
267 * @privilege %http://tizen.org/privilege/ime
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.
275 result SendKeyEvent(Tizen::Ui::KeyCode code, Tizen::Ui::KeyState state);
278 * Sends a text to the associated text input UI control.
282 * @privilege %http://tizen.org/privilege/ime
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.
289 result SendText(const Tizen::Base::String& text);
293 // This Construct() is intentionally declared as private so that only the platform can create an instance.
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.
303 result Construct(void);
306 // This default constructor is intentionally declared as private to implement the Singleton semantic.
313 // This destructor is intentionally declared as private to implement the Singleton semantic.
317 virtual ~InputMethod(void);
320 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
324 InputMethod(const InputMethod& rhs);
327 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
331 InputMethod& operator=(const InputMethod& rhs);
334 friend class _InputMethodImpl;
336 _InputMethodImpl* __pInputMethodImpl;
339 }}} // Tizen::Ui::Ime
341 #endif // _FUI_IME_INPUT_METHOD_H_