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 FUiCtrlEditArea.h
20 * @brief This is the header file for the %EditArea class.
22 * This header file contains the declarations of the %EditArea class and its helper classes.
25 #ifndef _FUI_CTRL_EDIT_AREA_H_
26 #define _FUI_CTRL_EDIT_AREA_H_
28 #include <FBaseString.h>
29 #include <FBaseCharacter.h>
30 #include <FGrpBitmap.h>
31 #include <FGrpColor.h>
32 #include <FGrpPoint.h>
33 #include <FGrpRectangle.h>
34 #include <FUiContainer.h>
35 #include <FUiControl.h>
36 #include <FUiCtrlControlsTypes.h>
37 #include <FUiCtrlEditTypes.h>
38 #include <FUiCtrlIEditTextFilter.h>
39 #include <FUiCtrlInputTypes.h>
40 #include <FUiIActionEventListener.h>
41 #include <FUiIKeypadEventListener.h>
42 #include <FUiILanguageEventListener.h>
43 #include <FUiIScrollPanelEventListener.h>
44 #include <FUiITextBlockEventListener.h>
45 #include <FUiITextEventListener.h>
46 #include <FUiIUiLinkEventListener.h>
48 namespace Tizen { namespace Locales
53 namespace Tizen { namespace Ui { namespace Controls
58 * @brief This class defines the common behavior for the %EditArea control.
62 * The %EditArea class displays a multi-line text editor.
64 * For more information on the class features,
65 * see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_editfield_editarea.htm">EditArea and EditField</a>.
67 * The following example demonstrates how to use the %EditArea class.
70 // Sample code for EditAreaSample.h
74 : public Tizen::Ui::Controls::Form
75 , public Tizen::Ui::ITextEventListener
81 bool Initialize(void);
82 virtual result OnInitializing(void);
85 virtual void OnTextValueChanged(const Tizen::Ui::Control& source);
86 virtual void OnTextValueChangeCanceled(const Tizen::Ui::Control& source);
89 Tizen::Ui::Controls::EditArea* __pEditArea;
94 // Sample code for EditAreaSample.cpp
95 #include <FGraphics.h>
97 #include "EditAreaSample.h"
99 using namespace Tizen::Graphics;
100 using namespace Tizen::Ui::Controls;
103 EditAreaSample::Initialize(void)
105 Construct(FORM_STYLE_NORMAL);
110 EditAreaSample::OnInitializing(void)
112 result r = E_SUCCESS;
114 // Creates an instance of EditArea
115 __pEditArea = new EditArea();
116 __pEditArea->Construct(Rectangle(50, 100, 400, 150));
117 __pEditArea->AddTextEventListener(*this);
119 // Adds the edit area to the form
120 AddControl(__pEditArea);
125 // ITextEventListener implementation
127 EditAreaSample::OnTextValueChanged(const Tizen::Ui::Control& source)
133 EditAreaSample::OnTextValueChangeCanceled(const Tizen::Ui::Control& source)
140 class _OSP_EXPORT_ EditArea
141 : public Tizen::Ui::Control
146 * The object is not fully constructed after this constructor is called. @n
147 * For full construction, the %Construct() method must be called right after calling this constructor.
154 * This polymorphic destructor should be overridden if required.@n
155 * This way, the destructors of the derived classes are called when the destructor of this interface is called.
159 virtual ~EditArea(void);
162 * Initializes this instance of the %EditArea control with the specified parameters.
166 * @return An error code
167 * @param[in] rect An instance of the Graphics::Rectangle class @n
168 * This instance represents the x and y coordinates of the top-left corner of the created window along with
169 * the width and height of the control.@n
170 * The optimal size of the control is defined in
171 * <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
172 * @param[in] inputStyle Determines whether the fullscreen keypad or overlay keypad is displayed
173 * @param[in] limitLength The maximum limit of the length of the text that can be displayed by %EditArea
174 * @exception E_SUCCESS The method is successful.
175 * @exception E_INVALID_ARG A specified input parameter is invalid.@n
176 * The specified @c limitLength is less than or equal to @c 0. @n
177 * The @c rect.width or the @c rect.height is less than 0.
178 * @exception E_SYSTEM A system error has occurred.
180 * - Some methods of the control will only work as expected when it becomes 'displayable'.
181 * For more information, see Control::IsDisplayable().
182 * - The orientation of the full-screen style keypad is determined by the current device orientation.
184 result Construct(const Tizen::Graphics::Rectangle& rect, InputStyle inputStyle = INPUT_STYLE_FULLSCREEN, int limitLength = 1000);
187 * Initializes this instance of the %EditArea control with the specified parameters.
191 * @return An error code
192 * @param[in] rect An instance of the Tizen::Graphics::FloatRectangle class @n
193 * This instance represents the x and y coordinates of the top-left corner of the created window along with
194 * the width and height of the control.@n
195 * The optimal size of the control is defined in
196 * <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
197 * @param[in] inputStyle Determines whether the fullscreen keypad or overlay keypad is displayed
198 * @param[in] limitLength The maximum limit of the length of the text that can be displayed by %EditArea
199 * @exception E_SUCCESS The method is successful.
200 * @exception E_INVALID_ARG A specified input parameter is invalid.@n
201 * The specified @c limitLength is less than or equal to @c 0. @n
202 * The @c rect.width or the @c rect.height is less than 0.
203 * @exception E_SYSTEM A system error has occurred.
205 * - Some methods of the control will only work as expected when it becomes 'displayable'.
206 * For more information, see Control::IsDisplayable().
207 * - The orientation of the full-screen style keypad is determined by the current device orientation.
209 result Construct(const Tizen::Graphics::FloatRectangle& rect, InputStyle inputStyle = INPUT_STYLE_FULLSCREEN, int limitLength = 1000);
213 * Gets the horizontal text alignment.
217 * @return The horizontal text alignment
218 * @exception E_SUCCESS The method is successful.
219 * @exception E_SYSTEM A system error has occurred.
220 * @remarks The specific error code can be accessed using the GetLastResult() method.
221 * @see SetTextAlignment()
223 HorizontalAlignment GetTextAlignment(void) const;
226 * Sets the horizontal text alignment.
230 * @return An error code
231 * @param[in] alignment The horizontal text alignment
232 * @exception E_SUCCESS The method is successful.
233 * @exception E_SYSTEM A system error has occurred.
234 * @see GetTextAlignment()
236 result SetTextAlignment(HorizontalAlignment alignment);
239 * Checks whether the view mode is enabled.
243 * @return @c true if the view mode is enabled, @n
245 * @exception E_SUCCESS The method is successful.
246 * @exception E_SYSTEM A system error has occurred.
247 * @remarks The specific error code can be accessed using the GetLastResult() method.
248 * @see SetViewModeEnabled()
250 bool IsViewModeEnabled(void) const;
253 * Enables or disables the view mode.
257 * @return An error code
258 * @param[in] enable Set to @c true to enable the view mode, @n
260 * When it is set to @c true, the auto-detected links will be displayed as linked text.
261 * @exception E_SUCCESS The method is successful.
262 * @exception E_SYSTEM A system error has occurred.
263 * @see IsViewModeEnabled()
265 result SetViewModeEnabled(bool enable);
268 * Sets the auto-link mask.
272 * @return An error code
273 * @param[in] autoLinks The auto-link mask @n
274 * Multiple link types can be combined using bitwise OR. @n For more information,
275 * see <a href="../org.tizen.native.appprogramming/html/guide/ui/auto_link_detection.htm">AutoLink Detection</a>. @n
276 * When it is set to @c 0, the auto-link detection is disabled.
277 * @exception E_SUCCESS The method is successful.
278 * @exception E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation.@n
279 * The operation is not supported if the input style is not ::INPUT_STYLE_OVERLAY.
280 * @exception E_SYSTEM A system error has occurred.
281 * @see Tizen::Base::Utility::LinkType
282 * @see GetAutoLinkMask()
283 * @see IsViewModeEnabled()
284 * @see SetViewModeEnabled()
286 result SetAutoLinkMask(unsigned long autoLinks);
289 * Gets the auto-link mask.
293 * @return The auto-link mask
294 * @exception E_SUCCESS The method is successful.
295 * @exception E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation.@n
296 * This operation is not supported if the input style is not ::INPUT_STYLE_OVERLAY.
297 * @exception E_SYSTEM A system error has occurred.
298 * @remarks The specific error code can be accessed using the GetLastResult() method.
299 * @see SetAutoLinkMask()
301 unsigned long GetAutoLinkMask(void) const;
304 * Adds the specified link event listener. @n
305 * The added listener will be notified when the links are selected by the user. @n
306 * The %AddUiLinkEventListener() method is supported when the input style is ::INPUT_STYLE_OVERLAY
310 * @param[in] listener The event listener to add
311 * @see RemoveUiLinkEventListener()
313 void AddUiLinkEventListener(Tizen::Ui::IUiLinkEventListener& listener);
316 * Removes the specified link event listener. @n
317 * The removed listener cannot listen to the events when they are fired. @n
318 * The %RemoveUiLinkEventListener() method is supported when the input style is ::INPUT_STYLE_OVERLAY.
322 * @param[in] listener The event listener to remove
323 * @see AddUiLinkEventListener()
325 void RemoveUiLinkEventListener(Tizen::Ui::IUiLinkEventListener& listener);
328 * Gets the line spacing.
332 * @return The line spacing, @n
333 * else @c -1 if an error occurs
334 * @exception E_SUCCESS The method is successful.
335 * @remarks The specific error code can be accessed using the GetLastResult() method.
336 * @see SetLineSpacing()
338 int GetLineSpacing(void) const;
341 * Gets the line spacing.
345 * @return The line spacing, @n
346 * else @c -1 if an error occurs
347 * @exception E_SUCCESS The method is successful.
348 * @remarks The specific error code can be accessed using the GetLastResult() method.
349 * @see SetLineSpacing()
351 float GetLineSpacingF(void) const;
354 * Sets the line spacing. @n
355 * The line spacing is determined by multiplying @c multiplier to the default line spacing and adding @c extra.
358 * The line spacing = (default line spacing) * multiplier + extra
362 * @return An error code
363 * @param[in] multiplier The line spacing multiplier
364 * @param[in] extra The extra line spacing
365 * @exception E_SUCCESS The method is successful.
366 * @exception E_INVALID_ARG A specified input parameter is invalid, or @n
367 * the specified line spacing value cannot be supported.
368 * @exception E_SYSTEM A system error has occurred.
369 * @see GetLineSpacing()
371 result SetLineSpacing(int multiplier, int extra);
374 * Sets the line spacing. @n
375 * The line spacing is determined by multiplying @c multiplier to the default line spacing and adding @c extra.
378 * The line spacing = (default line spacing) * multiplier + extra
382 * @return An error code
383 * @param[in] multiplier The line spacing multiplier
384 * @param[in] extra The extra line spacing
385 * @exception E_SUCCESS The method is successful.
386 * @exception E_INVALID_ARG A specified input parameter is invalid, or @n
387 * the specified line spacing value cannot be supported.
388 * @exception E_SYSTEM A system error has occurred.
389 * @see GetLineSpacingF()
391 result SetLineSpacing(int multiplier, float extra);
394 * Gets the margin value of the specified margin type.
398 * @return The margin value, @n
399 * else @c -1 if an error occurs
400 * @param[in] marginType The margin type
401 * @exception E_SUCCESS The method is successful.
402 * @exception E_SYSTEM A system error has occurred.
403 * @remarks The specific error code can be accessed using the GetLastResult() method.
406 int GetMargin(EditMarginType marginType) const;
409 * Gets the margin value of the specified margin type.
413 * @return The margin value, @n
414 * else @c -1 if an error occurs
415 * @param[in] marginType The margin type
416 * @exception E_SUCCESS The method is successful.
417 * @exception E_SYSTEM A system error has occurred.
418 * @remarks The specific error code can be accessed using the GetLastResult() method.
421 float GetMarginF(EditMarginType marginType) const;
424 * Sets the margin value for the specified margin type.
428 * @return An error code
429 * @param[in] marginType The margin type
430 * @param[in] margin The margin value to set
431 * @exception E_SUCCESS The method is successful.
432 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
433 * The specified @c margin cannot be a negative integer.
434 * @exception E_SYSTEM A system error has occurred.
437 result SetMargin(EditMarginType marginType, int margin);
440 * Sets the margin value for the specified margin type.
444 * @return An error code
445 * @param[in] marginType The margin type
446 * @param[in] margin The margin value to set
447 * @exception E_SUCCESS The method is successful.
448 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
449 * The specified @c margin cannot be a negative integer.
450 * @exception E_SYSTEM A system error has occurred.
453 result SetMargin(EditMarginType marginType, float margin);
456 * Enables or disables the keypad action.
459 * @return An error code
460 * @param[in] enable Set to @c true to enable the keypad action, @n
462 * @exception E_SUCCESS The method is successful.
463 * @exception E_UNSUPPORTED_OPERATION The underlying input method does not support this operation.
464 * @remarks Depending on the value of input param, the enter key have a enable or disable look accordingly.
466 result SetKeypadActionEnabled(bool enable);
469 * Checks whether the keypad action is enabled.
472 * @return @c true if the keypad action is enabled, @n
475 bool IsKeypadActionEnabled(void) const;
478 * Gets the keypad action type.
482 * @return The keypad action
483 * @exception E_SUCCESS The method is successful.
484 * @exception E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation.@n
485 * This operation is not supported if the input style is not ::INPUT_STYLE_OVERLAY.
486 * @exception E_SYSTEM A system error has occurred.
487 * @remarks The specific error code can be accessed using the GetLastResult() method.
489 Tizen::Ui::KeypadAction GetKeypadAction(void) const;
492 * Sets the keypad action type.
496 * @return An error code
497 * @param[in] keypadAction The keypad action
498 * @exception E_SUCCESS The method is successful.
499 * @exception E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation.@n
500 * This operation is not supported if the input style is not ::INPUT_STYLE_OVERLAY.
501 * @exception E_SYSTEM A system error has occurred.
502 * @remarks Depending on the value of input param, the enter key label of the keypad will change accordingly.
504 result SetKeypadAction(Tizen::Ui::KeypadAction keypadAction);
507 * Gets the keypad style.
511 * @return The keypad style
512 * @exception E_SUCCESS The method is successful.
513 * @exception E_SYSTEM A system error has occurred.
514 * @remarks The specific error code can be accessed using the GetLastResult() method.
515 * @see SetKeypadStyle()
517 KeypadStyle GetKeypadStyle(void) const;
520 * Sets the keypad style.
524 * @return An error code
525 * @param[in] keypadStyle The keypad style
526 * @exception E_SUCCESS The method is successful.
527 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
528 * The specified @c keypadStyle cannot be @c KEYPAD_STYLE_PASSWORD.
529 * @exception E_SYSTEM A system error has occurred.
530 * @remarks Depending on the value of input param, the keypad's layout will change accordingly.
531 * @see GetKeypadStyle()
533 result SetKeypadStyle(KeypadStyle keypadStyle);
536 * Checks whether the text prediction is enabled.
539 * @return @c true if the text prediction is enabled, @n
541 * @exception E_SUCCESS The method is successful.
542 * @see SetTextPredictionEnabled()
544 bool IsTextPredictionEnabled(void) const;
547 * Enables or disables the text prediction.
550 * @param[in] enable Set to @c true to enable the text prediction, @n
552 * @return An error code
553 * @exception E_SUCCESS The method is successful.
554 * @exception E_UNSUPPORTED_OPERATION This operation is not supported.
555 * @see IsTextPredictionEnabled()
557 result SetTextPredictionEnabled(bool enable);
560 * Sets the visibility of the command buttons of the overlay style keypad.
564 * @return An error code
565 * @param[in] visible Set to @c true to make the overlay keypad command buttons visible, @n
567 * @exception E_SUCCESS The method is successful.
568 * @exception E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation.@n
569 * This operation is not supported if the input style is not ::INPUT_STYLE_OVERLAY.
570 * @exception E_SYSTEM A system error has occurred.
572 result SetOverlayKeypadCommandButtonVisible(bool visible);
575 * Checks whether the command buttons of the overlay style keypad are visible.
579 * @return @c true if the overlay command buttons are set to be visible, @n
581 * @exception E_SUCCESS The method is successful.
582 * @exception E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation.@n
583 * This operation is not supported if the input style is not ::INPUT_STYLE_OVERLAY.
584 * @exception E_SYSTEM A system error has occurred.
585 * @remarks The specific error code can be accessed using the GetLastResult() method.
587 bool IsOverlayCommandButtonVisible(void) const;
594 * @return An error code
595 * @exception E_SUCCESS The method is successful.
596 * @exception E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation.@n
597 * This operation is not supported if the input style is not ::INPUT_STYLE_OVERLAY.
598 * @exception E_SYSTEM A system error has occurred.
601 result HideKeypad(void);
604 * Gets the text size.
608 * @return The size of the text, @n
609 * else @c -1 if an error occurs
610 * @exception E_SUCCESS The method is successful.
611 * @exception E_SYSTEM A system error has occurred.
612 * @remarks The specific error code can be accessed using the GetLastResult() method.
615 int GetTextSize(void) const;
618 * Gets the text size.
622 * @return The size of the text, @n
623 * else @c -1 if an error occurs
624 * @exception E_SUCCESS The method is successful.
625 * @exception E_SYSTEM A system error has occurred.
626 * @remarks The specific error code can be accessed using the GetLastResult() method.
629 float GetTextSizeF(void) const;
632 * Sets the text size.
636 * @return An error code
637 * @param[in] size The text size @n
638 * The value should be greater than or equal to minimum font size which is 4.
639 * @exception E_SUCCESS The method is successful.
640 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
641 * The specified @c size cannot be a negative integer.
642 * @exception E_SYSTEM A system error has occurred.
645 result SetTextSize(int size);
648 * Sets the text size.
652 * @return An error code
653 * @param[in] size The text size @n
654 * The value should be greater than or equal to minimum font size which is 4.0f.
655 * @exception E_SUCCESS The method is successful.
656 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
657 * The specified @c size cannot be a negative integer.
658 * @exception E_SYSTEM A system error has occurred.
659 * @see GetTextSizeF()
661 result SetTextSize(float size);
664 * Gets the color of %EditArea for the specified status.
668 * @return The color, @n
669 * else RGBA (0,0,0,0) if an error occurs
670 * @param[in] status The status
671 * @exception E_SUCCESS The method is successful.
672 * @exception E_SYSTEM A system error has occurred.
673 * @remarks The specific error code can be accessed using the GetLastResult() method.
675 Tizen::Graphics::Color GetColor(EditStatus status) const;
678 * Gets the text color of the specified text color type.
682 * @return The color, @n
683 * else RGBA (0,0,0,0) if an error occurs
684 * @param[in] type The text color type
685 * @exception E_SUCCESS The method is successful.
686 * @exception E_SYSTEM A system error has occurred.
687 * @remarks The specific error code can be accessed using the GetLastResult() method.
688 * @see SetTextColor()
690 Tizen::Graphics::Color GetTextColor(EditTextColor type) const;
693 * Sets the background bitmap of the %EditArea control for the specified status.
697 * @return An error code
698 * @param[in] status The status
699 * @param[in] bitmap The background bitmap
700 * @exception E_SUCCESS The method is successful.
701 * @exception E_SYSTEM A system error has occurred.
703 result SetBackgroundBitmap(EditStatus status, const Tizen::Graphics::Bitmap& bitmap);
706 * Sets the color of the %EditArea control for the specified status.
710 * @return An error code
711 * @param[in] status The status
712 * @param[in] color The color
713 * @exception E_SUCCESS The method is successful.
714 * @exception E_SYSTEM A system error has occurred.
717 result SetColor(EditStatus status, const Tizen::Graphics::Color& color);
720 * Sets the text color of the %EditArea control for the specified text color type.
724 * @return An error code
725 * @param[in] type The text color type
726 * @param[in] color The text color
727 * @exception E_SUCCESS The method is successful.
728 * @exception E_SYSTEM A system error has occurred.
729 * @see GetTextColor()
731 result SetTextColor(EditTextColor type, const Tizen::Graphics::Color& color);
734 * Gets a portion of text that is displayed by the %EditArea control.
738 * @return The specified portion of the text, @n
739 * else an empty string if an error occurs
740 * @param[in] start The starting index of the range
741 * @param[in] end The last index of the range
742 * @exception E_SUCCESS The method is successful.
743 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure. @n
744 * The index is greater than the number of elements or less than @c 0.
745 * @exception E_SYSTEM A system error has occurred.
746 * @remarks The specific error code can be accessed using the GetLastResult() method.
749 Tizen::Base::String GetText(int start, int end) const;
752 * Adds the specified keypad event listener. @n
753 * The added listener is notified when the keypad associated with the %EditArea control is opened or closed.
757 * @param[in] listener The event listener to add
758 * @see RemoveKeypadEventListener()
760 void AddKeypadEventListener(Tizen::Ui::IKeypadEventListener& listener);
763 * Removes the specified keypad event listener. @n
764 * The removed listener cannot listen to events when they are fired.
768 * @param[in] listener The event listener to remove
769 * @see AddKeypadEventListener()
771 void RemoveKeypadEventListener(Tizen::Ui::IKeypadEventListener& listener);
774 * Adds a text block event listener.
775 * The added listener is notified when the text block is selected.
779 * @param[in] listener The event listener to add
780 * @remarks Programmatically modifying the text block does not cause the text block selection event to fire.
781 * @see RemoveTextBlockEventListener()
783 void AddTextBlockEventListener(Tizen::Ui::ITextBlockEventListener& listener);
786 * Removes the specified text block event listener. @n
787 * The removed listener cannot listen to events when they are fired.
791 * @param[in] listener The event listener to remove
792 * @see AddTextBlockEventListener()
794 void RemoveTextBlockEventListener(Tizen::Ui::ITextBlockEventListener& listener);
797 * Adds a listener instance. @n
798 * The added listener can listen to the text related events.
802 * @param[in] listener The listener to add
803 * @see RemoveTextEventListener()
805 void AddTextEventListener(Tizen::Ui::ITextEventListener& listener);
808 * Removes a listener instance. @n
809 * The removed listener cannot listen to events when they are fired.
813 * @param[in] listener The listener to remove
814 * @see AddTextEventListener()
816 void RemoveTextEventListener(Tizen::Ui::ITextEventListener& listener);
819 * Adds a listener instance to listen to the scroll panel events. @n
820 * To listen to scroll panel events, the parent of the %EditArea control must be an instance of ScrollPanel.
824 * @param[in] listener The listener to add
825 * @remarks When OnOverlayControlCreated() or OnOvelayControlClosed() is called, the application resets the bounds of the controls placed
826 * within the ScrollPanel. %ScrollPanel is automatically redrawn after this method is called.
827 * @see RemoveScrollPanelEventListener()
829 void AddScrollPanelEventListener(Tizen::Ui::IScrollPanelEventListener& listener);
832 * Removes the scroll panel event listener. @n
833 * The removed listener cannot listen to events when they are fired.
837 * @param[in] listener The listener to remove
838 * @see AddScrollPanelEventListener()
840 void RemoveScrollPanelEventListener(Tizen::Ui::IScrollPanelEventListener& listener);
843 * Adds a listener instance. @n
844 * The added listener is notified when the action event is fire by the command buttons of the keypad.
848 * @param[in] listener The event listener to add
849 * @see RemoveActionEventListener()
851 void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
855 * Removes a listener instance. @n
856 * The removed listener cannot listen to events when they are fired.
860 * @param[in] listener The event listener to remove
861 * @see AddActionEventListener()
863 void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
866 * Adds a listener instance for language events. @n
867 * The added listener is notified when the input language is changed.
871 * @param[in] listener The listener to add
872 * @remarks The application can recognize when the language is changed from the keypad by adding Tizen::Ui::ILanguageEventListener.
873 * @see RemoveLanguageEventListener()
875 void AddLanguageEventListener(Tizen::Ui::ILanguageEventListener& listener);
878 * Removes the specified listener instance. @n
879 * The removed listener cannot listen to events when they are fired.
883 * @param[in] listener The listener to remove
884 * @see AddLanguageEventListener()
886 void RemoveLanguageEventListener(Tizen::Ui::ILanguageEventListener& listener);
889 * Gets the remaining length of the %EditArea control.
893 * @return The remaining length of the %EditArea control, @n
894 * else @c -1 if an error occurs.
896 int GetRemainingLength(void) const;
899 * Enables or disables the lowercase mode.
903 * @param[in] enable Set to @c true to enable the lowercase mode, @n
906 void SetLowerCaseModeEnabled(bool enable);
909 * Checks whether the lowercase mode is enabled.
913 * @return @c true if the lowercase mode is enabled, @n
916 bool IsLowerCaseModeEnabled(void) const;
920 * Sets the input mode category.
922 * @brief <i> [Deprecated] </i>
923 * @deprecated We no longer provide a method to specify the list of styles which the user can set the keypad to, @n
924 * or the current mode to initially set the keypad to, from this list. It is recommended to use SetKeypadStyle() method instead.
927 * @return An error code
928 * @param[in] categories The categories to set @n
929 * Multiple input categories can be combined using bitwise OR.
930 * @param[in] enable The category value to set
931 * @exception E_SUCCESS The method is successful.
932 * @exception E_INVALID_ARG A specified input mode category is invalid.
933 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation @n
934 * The specified @c categories cannot be supported with the current keypad style.
935 * @exception E_SYSTEM A system error has occurred.
936 * @see EditInputModeCategory
939 result SetInputModeCategory(unsigned long categories, bool enable);
943 * Sets the current input mode category.
945 * @brief <i> [Deprecated] </i>
946 * @deprecated We no longer provide a method to specify the list of styles which the user can set the keypad to, @n
947 * or the current mode to initially set the keypad to, from this list. It is recommended to use SetKeypadStyle() method instead.
950 * @return An error code
951 * @param[in] inputModeCategory An item of input category
952 * @exception E_SUCCESS The method is successful.
953 * @exception E_SYSTEM A system error has occurred.
956 result SetCurrentInputModeCategory(EditInputModeCategory inputModeCategory);
960 * Gets the input mode category.
962 * @brief <i> [Deprecated] </i>
963 * @deprecated This method is deprecated because we no longer provide a method to specify the list of styles @n
964 * which the user can set the keypad to. It is recommended to use GetKeypadStyle() method instead.
967 * @return A bitwise combination of Tizen::Ui::Controls::EditInputModeCategory, @n
968 * else @c EDIT_INPUTMODE_ALPHA if an error occurs
971 unsigned long GetInputModeCategory(void) const;
975 * Gets the current input mode category.
977 * @brief <i> [Deprecated] </i>
978 * @deprecated This method is deprecated because we no longer provide a method to specify the list of styles @n
979 * which the user can set the keypad to. It is recommended to use GetKeypadStyle() method instead.
982 * @return The current input mode category
985 EditInputModeCategory GetCurrentInputModeCategory(void) const;
988 * Sets the cursor at the specified position.
992 * @return An error code
993 * @param[in] position The cursor position to set
994 * @exception E_SUCCESS The method is successful.
995 * @exception E_OUT_OF_RANGE The specified @c position is less than @c 0 or greater than the maximum length.
996 * @exception E_SYSTEM A system error has occurred.
998 result SetCursorPosition(int position);
1001 * Gets the cursor position.
1005 * @return The current cursor position, @n
1006 * else @c -1 if an error occurs
1008 int GetCursorPosition(void) const;
1011 * Gets the text that is displayed by the %EditArea control.
1015 * @return The text of the %EditArea control, @n
1016 * else an empty string if an error occurs
1018 Tizen::Base::String GetText(void) const;
1021 * Gets the length of the text that is displayed by the %EditArea control.
1025 * @return The length of the text, @n
1026 * else @c -1 if an error occurs
1028 int GetTextLength(void) const;
1031 * Sets the text of the %EditArea control.
1035 * @param[in] text The text to display by the %EditArea control @n
1036 * Use @htmlonly '\n' @endhtmlonly to denote the end of the line.
1037 * @exception E_SUCCESS The method is successful.
1038 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
1039 * The length of the specified @c text exceeds the system limitation or the limit length.
1040 * @exception E_SYSTEM A system error has occurred.
1042 result SetText(const Tizen::Base::String& text);
1045 * Inserts the specified text at the current cursor position.
1049 * @return An error code
1050 * @param[in] text The text to insert @n
1051 * Use @htmlonly '\n' @endhtmlonly to denote the end of the line.
1052 * @exception E_SUCCESS The method is successful.
1053 * @exception E_SYSTEM A system error has occurred.
1055 result InsertTextAtCursorPosition(const Tizen::Base::String& text);
1058 * Appends the specified text at the end of the existing text.
1062 * @return An error code
1063 * @param[in] text The text to append @n
1064 * Use @htmlonly '\n' @endhtmlonly to denote the end of the line.
1065 * @exception E_SUCCESS The method is successful.
1066 * @exception E_SYSTEM A system error has occurred.
1068 result AppendText(const Tizen::Base::String& text);
1071 * Appends the specified character at the end of the existing text.
1075 * @return An error code
1076 * @param[in] character The character to append
1077 * @exception E_SUCCESS The method is successful.
1078 * @exception E_SYSTEM A system error has occurred.
1079 * @remarks The method modifies the text buffer that is managed by the %EditArea control. To display the
1080 * changes, the control must be drawn again.
1082 result AppendCharacter(const Tizen::Base::Character& character);
1085 * Inserts the text that will be displayed by bitmap at the specified text position.
1089 * @return An error code
1090 * @param[in] position The position to insert the text
1091 * @param[in] text The text to insert
1092 * @param[in] textImage The alternate bitmap to draw
1093 * @exception E_SUCCESS The method is successful.
1094 * @exception E_OUT_OF_RANGE The specified @c position is outside the valid range. @n
1095 * Either the specified @c position is greater than the number of existing text in the %EditArea or less than @c 0.
1096 * @exception E_MAX_EXCEEDED The length of the specified @c text exceeds the maximum length of the text that can be displayed by %EditArea.
1097 * @remarks The method modifies the text buffer that is managed by the %EditArea control. To display the changes, the control must be drawn again.
1099 result InsertTextAt(int position, const Tizen::Base::String& text, const Tizen::Graphics::Bitmap& textImage);
1102 * Appends the text that will be displayed by bitmap at the end of the existing text.
1106 * @return An error code
1107 * @param[in] text The text to append
1108 * @param[in] textImage The alternate bitmap to draw
1109 * @exception E_SUCCESS The method is successful.
1110 * @exception E_MAX_EXCEEDED The length of the specified @c text exceeds the maximum length of the text that can be displayed by %EditArea.
1111 * @remarks The method modifies the text buffer that is managed by the %EditArea control. To display the changes, the control must be drawn again.
1113 result AppendText(const Tizen::Base::String& text, const Tizen::Graphics::Bitmap& textImage);
1116 * Clears the text that is displayed by the %EditArea control.
1120 * @return An error code
1121 * @exception E_SUCCESS The method is successful.
1122 * @exception E_SYSTEM A system error has occurred.
1123 * @remarks The method modifies the text buffer that is managed by the %EditArea control. To display the
1124 * changes, the control must be drawn again.
1129 * Deletes a character at the current cursor position.
1133 * @return An error code
1134 * @exception E_SUCCESS The method is successful.
1135 * @exception E_SYSTEM A system error has occurred.
1136 * @remarks The method modifies the text buffer that is managed by the %EditArea control. To display the
1137 * changes, the control must be drawn again.
1139 result DeleteCharacterAtCursorPosition(void);
1142 * Gets the range of the current text block.
1146 * @param[out] start The first index of the current text block
1147 * @param[out] end The last index of the current text block
1149 void GetCurrentTextRange(int& start, int& end) const;
1152 * Displays the guide text when there is no text in the %EditArea control.
1156 * @param[in] guideText The guide text that is displayed in the %EditArea control when the focus is given to it.
1158 void SetGuideText(const Tizen::Base::String& guideText);
1161 * Gets the guide text.
1165 * @return The guide text, @n
1166 * else an empty string if an error occurs
1167 * @exception E_SUCCESS The method is successful.
1168 * @exception E_SYSTEM A system error has occurred.
1169 * @remarks The specific error code can be accessed using the GetLastResult() method.
1170 * @see SetGuideText()
1172 Tizen::Base::String GetGuideText(void) const;
1175 * Gets the text color of the guide text.
1179 * @return The guide text color
1180 * @exception E_SUCCESS The method is successful.
1181 * @exception E_SYSTEM A system error has occurred.
1182 * @remarks The specific error code can be accessed using the GetLastResult() method.
1183 * @see SetGuideTextColor()
1185 Tizen::Graphics::Color GetGuideTextColor(void) const;
1188 * Sets the text color of the guide text.
1192 * @return An error code
1193 * @param[in] color The guide text color
1194 * @exception E_SUCCESS The method is successful.
1195 * @exception E_SYSTEM A system error has occurred.
1196 * @see GetGuideTextColor()
1198 result SetGuideTextColor(const Tizen::Graphics::Color& color);
1201 * Enables or disables the keypad.
1205 * @param[in] enable Set to @c true to enable the keypad, @n
1208 void SetKeypadEnabled(bool enable);
1211 * Checks whether the keypad is enabled.
1215 * @return @c true if the keypad is enabled, @n
1218 bool IsKeypadEnabled(void) const;
1221 * Shows the keypad. @n
1222 * The %ShowKeypad() method is supported only when the input style is ::INPUT_STYLE_OVERLAY.
1226 * @return An error code
1227 * @exception E_SUCCESS The method is successful.
1228 * @exception E_INVALID_STATE This instance is in an invalid state.
1229 * @exception E_SYSTEM A system error has occurred.
1231 result ShowKeypad(void);
1234 * Gets the line count.
1238 * @return The line count
1240 int GetTextLineCount(void) const;
1243 * Gets the range of the current text block.
1247 * @param[out] start The starting index of the current text block
1248 * @param[out] end The end index of the current text block
1250 void GetBlockRange(int& start, int& end) const;
1253 * Begins the text block from the current cursor position.
1257 * @return An error code
1258 * @exception E_SUCCESS The method is successful.
1259 * @exception E_SYSTEM A system error has occurred.
1260 * @remarks Move the cursor position to the end of the text block.
1261 * @see SetCursorPosition()
1262 * @see ReleaseBlock()
1265 result BeginBlock(void);
1268 * Releases the text block.
1272 * @return An error code
1273 * @exception E_SUCCESS The method is successful.
1274 * @exception E_SYSTEM A system error has occurred.
1278 result ReleaseBlock(void);
1281 * Checks whether a portion of the text is blocked.
1285 * @return @c true if the text is blocked, @n
1288 * @see ReleaseBlock()
1290 bool IsBlocked(void) const;
1293 * Copies the text block to the clipboard.
1297 * @return An error code
1298 * @exception E_SUCCESS The method is successful.
1299 * @exception E_SYSTEM A system error has occurred.
1307 * Cuts the text block and copies it to the clipboard.
1311 * @return An error code
1312 * @exception E_SUCCESS The method is successful.
1313 * @exception E_SYSTEM A system error has occurred.
1321 * Pastes the copied text at the cursor position.
1325 * @return An error code
1326 * @exception E_SUCCESS The method is successful.
1327 * @exception E_SYSTEM A system error has occurred.
1335 * Removes the text that is marked by the text block.
1339 * @return An error code
1340 * @exception E_SUCCESS The method is successful.
1341 * @exception E_SYSTEM A system error has occurred.
1346 result Remove(void);
1349 * Checks whether the text in the %EditArea control has been clipped.
1353 * @return @c true if the text has been clipped, @n
1355 * @remarks 'Clipped' means that the text has been copied to the clipboard.
1361 bool IsClipped(void) const;
1364 * Sets the command button properties of the keypad. @n
1365 * The %SetOverlayKeypadCommandButton() method is supported when the input style is ::INPUT_STYLE_OVERLAY.
1369 * @return An error code
1370 * @param[in] position The position of the command button
1371 * @param[in] text The label of the command button
1372 * @param[in] actionId The action ID
1373 * @exception E_SUCCESS The method is successful.
1374 * @exception E_SYSTEM A system error has occurred.
1376 result SetOverlayKeypadCommandButton(CommandButtonPosition position, const Tizen::Base::String& text, int actionId);
1379 * Gets the text of the specified command button. @n
1380 * The %GetOverlayKeypadCommandButtonText() method is supported when the input style is ::INPUT_STYLE_OVERLAY.
1384 * @return The text of the specified command button
1385 * @param[in] position The position of the command button
1387 Tizen::Base::String GetOverlayKeypadCommandButtonText(CommandButtonPosition position) const;
1390 * Gets the action ID of the specified command button. @n
1391 * The %GetOverlayKeypadCommandButtonActionId() method is supported when the input style is ::INPUT_STYLE_OVERLAY.
1395 * @return The action ID of the specified command button
1396 * @param[in] position The position of the command button
1398 int GetOverlayKeypadCommandButtonActionId(CommandButtonPosition position) const;
1401 * Sets the input language.
1403 * @brief <i> [Deprecated] </i>
1404 * @deprecated We no longer provide a method to set the language of the current keypad. @n
1405 * This method is provided only for backward compatibility and will be deleted in the near future.
1408 * @return An error code
1409 * @param[in] languageCode The language to set
1410 * @exception E_SUCCESS The method is successful.
1411 * @exception E_OUT_OF_MEMORY The memory is insufficient.
1413 * - The application can set the language of the current keypad that is associated with the current %EditArea.
1414 * - This method only works if the language to set is supported by the current preloaded keypad.
1416 result SetCurrentLanguage(Tizen::Locales::LanguageCode languageCode);
1419 * Gets the current input language of the keypad that is associated with the current %EditArea.
1423 * @return An error code
1424 * @param[out] language The current input language
1425 * @exception E_SUCCESS The method is successful.
1427 result GetCurrentLanguage(Tizen::Locales::LanguageCode& language) const;
1430 * Sets the text filter. @n
1431 * The %EditArea control checks with the registered filter to decide whether the user-entered text should be replaced or not.
1435 * @param[in] pFilter The filter to set
1437 void SetEditTextFilter(IEditTextFilter* pFilter);
1440 * Sends opaque command to the input method.
1444 * @param[in] command The opaque command to send
1446 * - This method can be used to provide domain-specific features that are only known between certain input methods and their clients.
1447 * - This method may not work, depending on the active Input Method.
1449 void SendOpaqueCommand (const Tizen::Base::String& command);
1452 friend class _EditAreaImpl;
1455 EditArea(const EditArea&);
1456 EditArea& operator =(const EditArea&);
1459 }}} // Tizen::Ui::Controls
1461 #endif // _FUI_CTRL_EDIT_AREA_H_