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.
18 * @file FUiCtrlTextBox.h
19 * @brief This is the header file for the %TextBox class.
21 * This header file contains the declarations of the %TextBox class and its helper classes.
24 #ifndef _FUI_CTRL_TEXT_BOX_H_
25 #define _FUI_CTRL_TEXT_BOX_H_
27 #include <FGrpRectangle.h>
28 #include <FUiCtrlControlsTypes.h>
29 #include <FUiControl.h>
30 #include <FUiITextBlockEventListener.h>
31 #include <FUiIUiLinkEventListener.h>
33 namespace Tizen { namespace Ui { namespace Controls
40 namespace Tizen { namespace Ui { namespace Controls
45 * Defines the possible types of text box borders.
51 TEXT_BOX_BORDER_NONE, /**< No border */
52 TEXT_BOX_BORDER_ROUNDED /**< The rounded border */
59 * Defines the possible states of the text box.
65 TEXT_BOX_STATUS_NORMAL, /**< The normal state */
66 TEXT_BOX_STATUS_HIGHLIGHTED, /**< The focus-highlighted state */
67 TEXT_BOX_STATUS_DISABLED /**< The disabled state */
72 * @enum TextBoxTextColor
74 * Defines the possible text colors.
80 TEXT_BOX_TEXT_COLOR_NORMAL, /**< The default text color */
81 TEXT_BOX_TEXT_COLOR_HIGHLIGHTED, /**< The highlighted text color */
82 TEXT_BOX_TEXT_COLOR_DISABLED, /**< The disabled text color */
83 TEXT_BOX_TEXT_COLOR_BLOCKED, /**< The text block color */
84 TEXT_BOX_TEXT_COLOR_LINK /**< The link text color */
89 * @enum TextBoxTextStyle
91 * Defines the possible text styles.
97 TEXT_BOX_TEXT_STYLE_NORMAL = 0x0000, /**< The normal text style */
98 TEXT_BOX_TEXT_STYLE_BOLD = 0x0001, /**< The bold text style */
99 TEXT_BOX_TEXT_STYLE_ITALIC = 0x0002, /**< The italic text style */
100 TEXT_BOX_TEXT_STYLE_UNDERLINE = 0x0004, /**< The underline text style */
101 TEXT_BOX_TEXT_STYLE_STRIKEOUT = 0x0008, /**< The strikeout text style */
102 TEXT_BOX_TEXT_STYLE_MAX = 0x7FFF /**< The placeholder */
107 * @brief This class is an implementation of a %TextBox control.
111 * The %TextBox class displays a non-editable text field.
113 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_textbox.htm">TextBox</a>.
115 * The following example demonstrates how to use the %TextBox class.
118 // Sample code for TextBoxSample.h
122 : public Tizen::Ui::Controls::Form
128 bool Initialize(void);
129 virtual result OnInitializing(void);
132 Tizen::Ui::Controls::TextBox* __pTextBox;
137 // Sample code for TextBoxSample.cpp
138 #include <FGraphics.h>
140 #include "TextBoxSample.h"
142 using namespace Tizen::Graphics;
143 using namespace Tizen::Ui::Controls;
146 TextBoxSample::Initialize(void)
148 Construct(FORM_STYLE_NORMAL);
153 TextBoxSample::OnInitializing(void)
155 result r = E_SUCCESS;
157 // Creates an instance of TextBox
158 __pTextBox = new TextBox();
159 __pTextBox->Construct(Rectangle(50, 50, GetClientAreaBounds().width-80, 300), TEXT_BOX_BORDER_ROUNDED);
161 // Sets properties on the text box
162 __pTextBox->SetTextSize(50);
163 __pTextBox->SetText(L"Tizen Developer");
164 __pTextBox->SetTextColor(TEXT_BOX_TEXT_COLOR_HIGHLIGHTED, Color::GetColor(COLOR_ID_RED));
165 __pTextBox->AppendText(L"\nTizen SDK");
167 // Adds the text box to the form
168 AddControl(__pTextBox);
174 class _OSP_EXPORT_ TextBox
175 : public Tizen::Ui::Control
180 * The object is not fully constructed after this constructor is called. @n
181 * For full construction, the %Construct() method must be called right after calling this constructor.
189 * This polymorphic destructor should be overridden if required.@n
190 * This way, the destructors of the derived classes are called when the destructor of this interface is called.
194 virtual ~TextBox(void);
197 * Initializes this instance of %TextBox with the specified parameters.
201 * @return An error code
202 * @param[in] rect An instance of the Graphics::Rectangle class @n
203 * This instance represents the x and y coordinates of the top-left corner of the created window along with
204 * the width and height of the control.@n
205 * The optimal size of the control is defined in
206 * <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
207 * @param[in] border The border style
208 * @exception E_SUCCESS The method is successful.
209 * @exception E_SYSTEM A system error has occurred.
211 result Construct(const Tizen::Graphics::Rectangle& rect, TextBoxBorder border = TEXT_BOX_BORDER_ROUNDED);
214 * Initializes this instance of %TextBox with the specified parameters.
218 * @return An error code
219 * @param[in] rect An instance of the Tizen::Graphics::FloatRectangle class @n
220 * This instance represents the x and y coordinates of the top-left corner of the created window along with
221 * the width and height of the control.@n
222 * The optimal size of the control is defined in
223 * <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
224 * @param[in] border The border style
225 * @exception E_SUCCESS The method is successful.
226 * @exception E_SYSTEM A system error has occurred.
228 result Construct(const Tizen::Graphics::FloatRectangle& rect, TextBoxBorder border = TEXT_BOX_BORDER_ROUNDED);
233 * Sets the auto-link mask.
237 * @return An error code
238 * @param[in] autoLinks The auto-link mask @n
239 * Multiple link types can be combined using the bitwise OR operator (see Tizen::Base::Utility::LinkType). @n For more information,
240 * see <a href="../org.tizen.native.appprogramming/html/guide/ui/auto_link_detection.htm">AutoLink Detection</a>.
241 * @exception E_SUCCESS The method is successful.
242 * @exception E_SYSTEM A system error has occurred.
243 * @remarks When @c autoLinks is set to @c 0, the auto-link detection is disabled.
244 * @see Tizen::Base::Utility::LinkType
245 * @see GetAutoLinkMask()
247 result SetAutoLinkMask(unsigned long autoLinks);
250 * Gets the auto-link mask.
254 * @return The auto-link mask
255 * @exception E_SUCCESS The method is successful.
256 * @exception E_SYSTEM A system error has occurred.
257 * @remarks The specific error code can be accessed using the GetLastResult() method.
258 * @see SetAutoLinkMask()
260 unsigned long GetAutoLinkMask(void) const;
263 * Adds a link event listener.
267 * @param[in] listener The event listener to add
268 * @see RemoveUiLinkEventListener()
270 void AddUiLinkEventListener(Tizen::Ui::IUiLinkEventListener& listener);
273 * Removes the specified link event listener. @n
274 * The removed listener cannot listen to events when they are fired.
278 * @param[in] listener The event listener to remove
279 * @see AddUiLinkEventListener()
281 void RemoveUiLinkEventListener(Tizen::Ui::IUiLinkEventListener& listener);
285 * Appends the specified character at the end of the text.
289 * @return An error code
290 * @param[in] character The character to add
291 * @exception E_SUCCESS The method is successful.
292 * @exception E_SYSTEM A system error has occurred.
294 * - The method modifies the text buffer that is managed by the %TextBox control.
295 * -To display the changes, the control must be drawn again.
297 result AppendCharacter(const Tizen::Base::Character& character);
300 * Appends the specified text at the end of the text.
304 * @return An error code
305 * @param[in] text The text to append
306 * @exception E_SUCCESS The method is successful.
307 * @exception E_SYSTEM A system error has occurred.
309 * -To denote the end of a line use '\\n'.
310 * -The method modifies the text buffer that is managed by the %TextBox control.
311 * -To display the changes, the control must be drawn again.
313 result AppendText(const Tizen::Base::String& text);
316 * Clears the text that is displayed by the %TextBox control.
320 * @return An error code
321 * @exception E_SUCCESS The method is successful.
322 * @exception E_SYSTEM A system error has occurred.
324 * -The method modifies the text buffer that is managed by the %TextBox control.
325 * -To display the changes, the control must be drawn again.
330 * Gets the number of the lines contained in the %TextBox control.
334 * @return The line count of the text, @n
335 * else @c -1 if an error occurs
336 * @exception E_SUCCESS The method is successful.
337 * @remarks The specific error code can be accessed using the GetLastResult() method.
339 int GetLineCount(void) const;
342 * Gets the text that is displayed by the %TextBox control.
346 * @return The text of the %TextBox control, @n
347 * else an empty string if an error occurs
348 * @exception E_SUCCESS The method is successful.
349 * @exception E_SYSTEM A system error has occurred.
350 * @remarks The specific error code can be accessed using the GetLastResult() method.
353 Tizen::Base::String GetText(void) const;
356 * Gets a portion of the text that is displayed by the %TextBox control.
360 * @return The specified portion of the text, @n
361 * else an empty string if an error occurs
362 * @param[in] start The starting index of the range
363 * @param[in] end The last index of the range
364 * @exception E_SUCCESS The method is successful.
365 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure. @n
366 * The index is greater than the number of elements or less than @c 0.
367 * @exception E_SYSTEM A system error has occurred.
368 * @remarks The specific error code can be accessed using the GetLastResult() method.
371 Tizen::Base::String GetText(int start, int end) const;
374 * Gets the length of the text that is displayed by the %TextBox control.
378 * @return The length of the text, @n
379 * else @c -1 if an error occurs
380 * @exception E_SUCCESS The method is successful.
381 * @exception E_SYSTEM A system error has occurred.
382 * @remarks The specific error code can be accessed using the GetLastResult() method.
384 int GetTextLength(void) const;
387 * Inserts the character at the specified index.
391 * @return An error code
392 * @param[in] index The position at which to insert the character
393 * @param[in] character The character to insert
394 * @exception E_SUCCESS The method is successful.
395 * @exception E_OUT_OF_RANGE The specified @c index is outside the bounds of the data structure. @n
396 * The specified @c index is greater than the number of elements or less than @c 0.
397 * @exception E_SYSTEM A system error has occurred.
399 result InsertCharacterAt(int index, const Tizen::Base::Character& character);
402 * Inserts the text at the specified index.
406 * @return An error code
407 * @param[in] index The position at which to insert the text
408 * @param[in] text The text to insert
409 * @exception E_SUCCESS The method is successful.
410 * @exception E_OUT_OF_RANGE The specified @c index is outside the bounds of the data structure. @n
411 * The specified @c index is greater than the number of elements or less than @c 0.
412 * @exception E_SYSTEM A system error has occurred.
414 result InsertTextAt(int index, const Tizen::Base::String& text);
417 * Sets the text to be displayed.
421 * @return An error code
422 * @param[in] text The text to display
423 * @exception E_SUCCESS The method is successful.
424 * @exception E_SYSTEM A system error has occurred.
426 * -To denote the end of a line use '\\n'.
427 * -The method modifies the text buffer that is managed by the %TextBox control.
428 * -To display the changes, the control must be drawn again.
430 result SetText(const Tizen::Base::String& text);
434 * Gets the line spacing.
438 * @return The line spacing, @n
439 * else @c -1 if an error occurs
440 * @exception E_SUCCESS The method is successful.
441 * @remarks The specific error code can be accessed using the GetLastResult() method.
442 * @see SetLineSpacing()
444 int GetLineSpacing(void) const;
447 * Gets the line spacing.
451 * @return The line spacing, @n
452 * else @c -1 if an error occurs
453 * @exception E_SUCCESS The method is successful.
454 * @remarks The specific error code can be accessed using the GetLastResult() method.
455 * @see SetLineSpacing()
457 float GetLineSpacingF(void) const;
460 * Sets the line spacing. @n
461 * The line spacing is determined by multiplying @c multiplier to the default line spacing and adding @c extra. @n
464 * The line spacing = (default line spacing) * multiplier + extra
469 * @return An error code
470 * @param[in] multiplier The line spacing multiplier
471 * @param[in] extra The extra line spacing
472 * @exception E_SUCCESS The method is successful.
473 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
474 * The specified line spacing value cannot be supported.
475 * @exception E_SYSTEM A system error has occurred.
476 * @see GetLineSpacing()
478 result SetLineSpacing(int multiplier, int extra);
481 * Sets the line spacing. @n
482 * The line spacing is determined by multiplying @c multiplier to the default line spacing and adding @c extra. @n
485 * The line spacing = (default line spacing) * multiplier + extra
490 * @return An error code
491 * @param[in] multiplier The line spacing multiplier
492 * @param[in] extra The extra line spacing
493 * @exception E_SUCCESS The method is successful.
494 * @exception E_INVALID_ARG A specified input parameter is invalid. @n
495 * The specified line spacing value cannot be supported.
496 * @exception E_SYSTEM A system error has occurred.
497 * @see GetLineSpacingF()
499 result SetLineSpacing(int multiplier, float extra);
503 * Gets the horizontal text alignment.
507 * @return The horizontal text alignment
508 * @exception E_SUCCESS The method is successful.
509 * @exception E_SYSTEM A system error has occurred.
510 * @remarks The specific error code can be accessed using the GetLastResult() method.
511 * @see SetTextAlignment()
513 HorizontalAlignment GetTextAlignment(void) const;
516 * Sets the horizontal text alignment.
520 * @return An error code
521 * @param[in] alignment The horizontal text alignment
522 * @exception E_SUCCESS The method is successful.
523 * @exception E_SYSTEM A system error has occurred.
524 * @see GetTextAlignment()
526 result SetTextAlignment(HorizontalAlignment alignment);
530 * Gets the text size of the %TextBox control.
534 * @return The size of the text, @n
535 * else @c -1 if an error occurs
536 * @exception E_SUCCESS The method is successful.
537 * @exception E_SYSTEM A system error has occurred.
538 * @remarks The specific error code can be accessed using the GetLastResult() method.
541 int GetTextSize(void) const;
544 * Gets the text size of the %TextBox control.
548 * @return The size of the text, @n
549 * else @c -1 if an error occurs
550 * @exception E_SUCCESS The method is successful.
551 * @exception E_SYSTEM A system error has occurred.
552 * @remarks The specific error code can be accessed using the GetLastResult() method.
555 float GetTextSizeF(void) const;
558 * Sets the text size.
562 * @return An error code
563 * @param[in] size The text size
564 * @exception E_SUCCESS The method is successful.
565 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
566 * The specified @c size cannot be a negative integer.
567 * @exception E_SYSTEM A system error has occurred.
568 * @remarks The specified @c size should be greater than or equal to minimum font size which is 4.
571 result SetTextSize(int size);
574 * Sets the text size.
578 * @return An error code
579 * @param[in] size The text size
580 * @exception E_SUCCESS The method is successful.
581 * @exception E_INVALID_ARG The specified input parameter is invalid. @n
582 * The specified @c size cannot be a negative integer.
583 * @exception E_SYSTEM A system error has occurred.
584 * @remarks The specified @c size should be greater than or equal to minimum font size which is 4.0f.
585 * @see GetTextSizeF()
587 result SetTextSize(float size);
592 * Gets the font typeface name and the style mask of the %TextBox control.
594 * @brief <i> [Deprecated] </i>
595 * @deprecated This method is deprecated. Instead of using this method, use the GetTextStyle() method.
598 * @return An error code
599 * @param[out] typefaceName The name of the font typeface
600 * @param[out] style The text style (see TextBoxTextStyle)
601 * @exception E_SUCCESS The method is successful.
602 * @exception E_SYSTEM A system error has occurred.
603 * @remarks Multiple styles can be combined using the bitwise OR operator.
605 * @see Tizen::Graphics::Font::GetSystemFontListN()
606 * @see TextBoxTextStyle
609 result GetFontType(Tizen::Base::String& typefaceName, unsigned long& style) const;
612 * Gets the text style mask of the %TextBox control.
616 * @return A bitwise combination of Tizen::Ui::Controls::TextBoxTextStyle
617 * @see SetTextStyle()
618 * @see TextBoxTextStyle
620 unsigned long GetTextStyle(void) const;
624 * Sets the font and the style mask of the %TextBox control.
626 * @brief <i> [Deprecated] </i>
627 * @deprecated This method is deprecated. Instead of using this method, use the SetTextStyle() method.
630 * @return An error code
631 * @param[in] typefaceName The name of the font typeface
632 * @param[in] style The text style @n
633 * Multiple styles can be combined using the bitwise OR operator(see TextBoxTextStyle).
634 * @exception E_SUCCESS The method is successful.
635 * @exception E_INVALID_ARG A specified input parameter is invalid, or the specified font typeface is not supported.
636 * @exception E_SYSTEM A system error has occurred.
637 * @remarks The specified font typeface must be one of the system fonts. @n
638 * @c italic and @c bold cannot be applied at the same time. If the specified style mask contains both @c italic and @c bold, @c italic will
641 * @see Tizen::Graphics::Font::GetSystemFontListN()
642 * @see TextBoxTextStyle
645 result SetFontType(const Tizen::Base::String& typefaceName, unsigned long style);
648 * Sets the text style mask of the %TextBox control.
652 * @return An error code
653 * @param[in] style The text style @n
654 * Multiple styles can be combined using the bitwise OR operator (see Tizen::Ui::Controls::TextBoxTextStyle).
655 * @exception E_SUCCESS The method is successful.
656 * @exception E_OUT_OF_MEMORY The memory is insufficient.
657 * @see GetTextStyle()
658 * @see TextBoxTextStyle
660 result SetTextStyle(unsigned long style);
662 using Control::SetFont;
665 * Sets the font to render the text.
667 * @brief <i> [Deprecated] </i>
668 * @deprecated This method is deprecated. Instead of using this method, use the SetFont(const String& fontName) method of superclass.
671 * @return An error code
672 * @param[in] font The text font
673 * @exception E_SUCCESS The method is successful.
674 * @exception E_SYSTEM A system error has occurred.
675 * @remarks All previously set text attributes (style, weight, decoration, and size) will be discarded.
678 result SetFont(const Tizen::Graphics::Font& font);
682 * Releases the selection of the current text block.
686 * @return An error code
687 * @exception E_SUCCESS The method is successful.
688 * @exception E_SYSTEM A system error has occurred.
689 * @see GetBlockRange()
690 * @see SetBlockRange()
692 result ReleaseBlock(void);
695 * Gets the start and the end index of the currently selected text block.
699 * @return An error code
700 * @param[out] start The start index of the text block
701 * @param[out] end The end index of the text block
702 * @exception E_SUCCESS The method is successful.
703 * @exception E_SYSTEM A system error has occurred.
704 * @remarks The method returns @c start = 0 and @c end = 0 if there is no selected text block.
705 * @see ReleaseBlock()
706 * @see SetBlockRange()
708 result GetBlockRange(int& start, int& end) const;
711 * Sets the specified block of the text.
715 * @return An error code
716 * @param[in] start The start index of the text block
717 * @param[in] end The end index of the text block
718 * @exception E_SUCCESS The method is successful.
719 * @exception E_OUT_OF_RANGE The specified index is outside the bounds of the data structure. @n
720 * Either the @c start or @c end parameters are greater than the number of elements or less than @c 0.
721 * @exception E_SYSTEM A system error has occurred.
722 * @see ReleaseBlock()
723 * @see GetBlockRange()
725 result SetBlockRange(int start, int end);
729 * Gets the color of the %TextBox control for the specified status.
733 * @return The color of the %TextBox control, @n
734 * else RGBA (0,0,0,0) if an error occurs
735 * @param[in] status The state of the %TextBox control
736 * @exception E_SUCCESS The method is successful.
737 * @remarks The specific error code can be accessed using the GetLastResult() method.
740 Tizen::Graphics::Color GetColor(TextBoxStatus status) const;
743 * Gets the text color of the specified text color type.
747 * @return The color, @n
748 * else RGBA (0,0,0,0) if an error occurs
749 * @param[in] type The text color type
750 * @exception E_SUCCESS The method is successful.
751 * @exception E_SYSTEM A system error has occurred.
752 * @remarks The specific error code can be accessed using the GetLastResult() method.
753 * @see SetTextColor()
755 Tizen::Graphics::Color GetTextColor(TextBoxTextColor type) const;
758 * Sets the background bitmap of the %TextBox control.
762 * @return An error code
763 * @param[in] status The state of the %TextBox control
764 * @param[in] bitmap The background bitmap
765 * @exception E_SUCCESS The method is successful.
766 * @exception E_SYSTEM A system error has occurred.
767 * @see SetBackgroundColor()
769 result SetBackgroundBitmap(TextBoxStatus status, const Tizen::Graphics::Bitmap& bitmap);
772 * Sets the color of the %TextBox control for the specified status.
776 * @return An error code
777 * @param[in] status The state of the %TextBox control
778 * @param[in] color The color to set
779 * @exception E_SUCCESS The method is successful.
780 * @exception E_SYSTEM A system error has occurred.
783 result SetColor(TextBoxStatus status, const Tizen::Graphics::Color& color);
786 * Sets the text color of the %TextBox control for the specified text type.
790 * @return An error code
791 * @param[in] type The text color type
792 * @param[in] color The text color to set
793 * @exception E_SUCCESS The method is successful.
794 * @exception E_SYSTEM A system error has occurred.
795 * @see GetTextColor()
797 result SetTextColor(TextBoxTextColor type, const Tizen::Graphics::Color& color);
800 * Adds a text block event listener.
804 * @param[in] listener The event listener to add
805 * @remarks Programmatically modifying the text selection does not cause the text block selection event to fire.
806 * @see RemoveTextBlockEventListener()
808 void AddTextBlockEventListener(Tizen::Ui::ITextBlockEventListener& listener);
811 * Removes the specified text block event listener. @n
812 * The removed listener cannot listen to events when they are fired.
816 * @param[in] listener The event listener to remove
817 * @see AddTextBlockEventListener()
819 void RemoveTextBlockEventListener(Tizen::Ui::ITextBlockEventListener& listener);
822 friend class _TextBoxImpl;
825 TextBox(const TextBox& value);
826 TextBox& operator =(const TextBox& value);
828 }}} //Tizen::Ui::Controls
830 #endif // _FUI_CTRL_TEXT_BOX_H_