inc/FUiCtrlExpandableEditArea.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        FUiCtrlExpandableEditArea.h
  20  * @brief       This is the header file for the %ExpandableEditArea class.
  21  *
  22  * This header file contains the declarations of the %ExpandableEditArea class.
  23  */
  24
  25 #ifndef _FUI_CTRL_EXPANDABLE_EDIT_AREA_H_
  26 #define _FUI_CTRL_EXPANDABLE_EDIT_AREA_H_
  27
  28 #include <FBaseObject.h>
  29 #include <FBaseString.h>
  30 #include <FBaseTypes.h>
  31 #include <FUiControl.h>
  32 #include <FUiCtrlEditTypes.h>
  33 #include <FUiCtrlIEditTextFilter.h>
  34 #include <FUiCtrlITokenFilter.h>
  35 #include <FUiIKeypadEventListener.h>
  36 #include <FUiILanguageEventListener.h>
  37 #include <FUiITextBlockEventListener.h>
  38 #include <FUiITextEventListener.h>
  39
  40 // Forward declaration
  41 namespace Tizen { namespace Graphics
  42 {
  43 class Rectangle;
  44 }}      // Tizen::Graphics
  45
  46 namespace Tizen { namespace Ui { namespace Controls
  47 {
  48
  49 class IExpandableEditAreaEventListener;
  50
  51 /**
  52  * @enum ExpandableEditAreaStyle
  53  *
  54  * Defines the possible styles of the expandable edit area.
  55  *
  56  * @since               2.0
  57  */
  58 enum ExpandableEditAreaStyle
  59 {
  60         EXPANDABLE_EDIT_AREA_STYLE_NORMAL,  /**< The normal expandable edit area */
  61         EXPANDABLE_EDIT_AREA_STYLE_TOKEN    /**< The token expandable edit area */
  62 };
  63
  64
  65 /**
  66  * @enum ExpandableEditAreaTitleStyle
  67  *
  68  * Defines the possible styles of the expandable edit area title.
  69  *
  70  * @since               2.0
  71  */
  72 enum ExpandableEditAreaTitleStyle
  73 {
  74         EXPANDABLE_EDIT_AREA_TITLE_STYLE_NONE = 0,      /**< The style with no title */
  75         EXPANDABLE_EDIT_AREA_TITLE_STYLE_INNER,         /**< The title appears as a right aligned text inside the edit text field */
  76         EXPANDABLE_EDIT_AREA_TITLE_STYLE_TOP            /**< The title appears at the top of the edit text field */
  77 };
  78
  79
  80 /**
  81  * @enum ExpandableEditAreaTokenStatus
  82  *
  83  * Defines the possible status of the expandable edit area tokens.
  84  *
  85  * @since               2.0
  86  */
  87 enum ExpandableEditAreaTokenStatus
  88 {
  89         EXPANDABLE_EDIT_AREA_TOKEN_STATUS_NORMAL = 0,   /**< The normal status */
  90         EXPANDABLE_EDIT_AREA_TOKEN_STATUS_SELECTED      /**< The selected status */
  91 };
  92
  93
  94 /**
  95  * @class       ExpandableEditArea
  96  * @brief       This class is an implementation of %ExpandableEditArea.
  97  *
  98  * @since       2.0
  99  *
 100  * The %ExpandableEditArea class displays a multi-line text editor the height of that is automatically adjusted according to the number of lines currently visible in the text box.
 101 *
 102 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_exp_editarea.htm">ExpandableEditArea</a>.
 103  *
 104 * The following sample code demonstrates how to use the %ExpandableEditArea class.
 105 *
 106 * @code
 107 // Sample code for ExpandableEditAreaSample.h
 108 #include <FUi.h>
 109
 110 class ExpandableEditAreaSample
 111         : public Tizen::Ui::Controls::Form
 112         , public Tizen::Ui::IKeypadEventListener
 113         , public Tizen::Ui::Controls::IExpandableEditAreaEventListener
 114 {
 115 public:
 116         ExpandableEditAreaSample(void)
 117         : __pExpandableEdit(null){}
 118
 119         bool Initialize(void);
 120         virtual result OnInitializing(void);
 121
 122         //IKeypadEventListener
 123         virtual void OnKeypadActionPerformed(Tizen::Ui::Control& source, Tizen::Ui::KeypadAction keypadAction);
 124         virtual void OnKeypadClosed(Tizen::Ui::Control& source);
 125         virtual void OnKeypadOpened(Tizen::Ui::Control& source);
 126         virtual void OnKeypadWillOpen(Tizen::Ui::Control& source);
 127
 128         //IExpandableEditAreaEventListener
 129         virtual void OnExpandableEditAreaLineAdded(Tizen::Ui::Controls::ExpandableEditArea& source, int newLineCount);
 130         virtual void OnExpandableEditAreaLineRemoved(Tizen::Ui::Controls::ExpandableEditArea& source, int newLineCount);
 131
 132 private:
 133         Tizen::Ui::Controls::ExpandableEditArea* __pExpandableEdit;
 134 };
 135
 136 * @endcode
 137 *
 138 * @code
 139 // Sample code for ExpandableEditAreaSample.cpp
 140 #include <FGraphics.h>
 141
 142 #include "ExpandableEditAreaSample.h"
 143
 144 using namespace Tizen::Graphics;;
 145 using namespace Tizen::Ui;
 146 using namespace Tizen::Ui::Controls;
 147
 148 bool
 149 ExpandableEditAreaSample::Initialize(void)
 150 {
 151         Construct(FORM_STYLE_NORMAL);
 152         return true;
 153 }
 154
 155 result
 156 ExpandableEditAreaSample::OnInitializing(void)
 157 {
 158         result r = E_SUCCESS;
 159
 160         __pExpandableEdit = new ExpandableEditArea();
 161         __pExpandableEdit->Construct(Rectangle(25, 100, GetClientAreaBounds().width - 50, 150),
 162                         EXPANDABLE_EDIT_AREA_STYLE_NORMAL, EXPANDABLE_EDIT_AREA_TITLE_STYLE_NONE, 5);
 163
 164         // Adds an instance of IKeypadEventListenerevent and an instance of IExpandableEditAreaEventListener
 165         __pExpandableEdit->AddKeypadEventListener(*this);
 166         __pExpandableEdit->AddExpandableEditAreaEventListener(*this);
 167
 168         AddControl(__pExpandableEdit);
 169
 170         // Sets a focus to the expandable edit area
 171         __pExpandableEdit->SetFocus();
 172
 173         return r;
 174 }
 175
 176 // IKeypadEventListener implementation
 177 void
 178 ExpandableEditAreaSample::OnKeypadActionPerformed(Tizen::Ui::Control& source, Tizen::Ui::KeypadAction keypadAction)
 179 {
 180         // ....
 181 }
 182
 183 void
 184 ExpandableEditAreaSample::OnKeypadClosed(Tizen::Ui::Control& source)
 185 {
 186         // ....
 187 }
 188
 189 void
 190 ExpandableEditAreaSample::OnKeypadOpened(Tizen::Ui::Control& source)
 191 {
 192         // ....
 193 }
 194
 195 void
 196 ExpandableEditAreaSample::OnKeypadWillOpen(Tizen::Ui::Control& source)
 197 {
 198         // ....
 199 }
 200
 201 // IExpandableEditAreaEventListener implementation
 202 void
 203 ExpandableEditAreaSample::OnExpandableEditAreaLineAdded(Tizen::Ui::Controls::ExpandableEditArea& source, int newLineCount)
 204 {
 205         // ....
 206 }
 207
 208 void
 209 ExpandableEditAreaSample::OnExpandableEditAreaLineRemoved(Tizen::Ui::Controls::ExpandableEditArea& source, int newLineCount)
 210 {
 211         // ....
 212 }
 213 * @endcode
 214 */
 215 class _OSP_EXPORT_ ExpandableEditArea
 216         : public Tizen::Ui::Control
 217 {
 218 public:
 219         /**
 220          * The object is not fully constructed after this constructor is called. @n
 221          * For full construction, the %Construct() method must be called right after calling this constructor.
 222          *
 223          * @since       2.0
 224          */
 225         ExpandableEditArea(void);
 226
 227         /**
 228          * This polymorphic destructor should be overridden if required.@n
 229          * This way, the destructors of the derived classes are called when the destructor of this interface is called.
 230          *
 231          * @since       2.0
 232          */
 233         virtual ~ExpandableEditArea(void);
 234
 235         /**
 236          * Initializes this instance of %ExpandableEditArea with the specified parameters.
 237          *
 238          * @since        2.0
 239          *
 240          * @return       An error code
 241          * @param[in]    rect             An instance of the Graphics::Rectangle class @n
 242          *                                                                              This instance represents the x and y coordinates of the top-left corner of the expandable edit area along with
 243          *                                                                              the width and height. @n
 244          *                                                                              The optimal size of the control is defined in
 245          *                                                                              <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 246          * @param[in]    style            The style of the expandable edit area
 247          * @param[in]    titleStyle       The title style
 248          * @param[in]    maxExpandableLines         The maximum number of lines to which the control can be expanded @n
 249          *                                                              By default, the line count is @c 1.
 250          * @exception   E_SUCCESS                               The method is successful.
 251          * @exception    E_UNSUPPORTED_OPTION   The specified option is not supported. @n
 252          *                                                                              The token style %ExpandabledEditArea does not support @c EXPANDABLE_EDIT_AREA_TITLE_STYLE_TOP.
 253          * @exception    E_MAX_EXCEEDED         The number of lines has exceeded the maximum limit.
 254          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or @n
 255          *                                                                              the specified @c maxLines is either negative or @c 0.
 256          * @exception   E_SYSTEM                A system error has occurred.
 257          */
 258         result Construct(const Tizen::Graphics::Rectangle& rect, ExpandableEditAreaStyle style, ExpandableEditAreaTitleStyle titleStyle, int maxExpandableLines = 10);
 259
 260         /**
 261          * Initializes this instance of %ExpandableEditArea with the specified parameters.
 262          *
 263          * @since        2.1
 264          *
 265          * @return       An error code
 266          * @param[in]    rect             An instance of the Tizen::Graphics::FloatRectangle class @n
 267          *                                                                              This instance represents the x and y coordinates of the top-left corner of the expandable edit area along with
 268          *                                                                              the width and height. @n
 269          *                                                                              The optimal size of the control is defined in
 270          *                                                                              <a href="../org.tizen.native.appprogramming/html/guide/ui/control_optimalsize.htm">Optimal Size of UI Controls</a>.
 271          * @param[in]    style            The style of the expandable edit area
 272          * @param[in]    titleStyle       The title style
 273          * @param[in]    maxExpandableLines         The maximum number of lines to which the control can be expanded @n
 274          *                                                              By default, the line count is @c 1.
 275          * @exception   E_SUCCESS                               The method is successful.
 276          * @exception    E_UNSUPPORTED_OPTION   The specified option is not supported. @n
 277          *                                                                              The token style %ExpandabledEditArea does not support @c EXPANDABLE_EDIT_AREA_TITLE_STYLE_TOP.
 278          * @exception    E_MAX_EXCEEDED         The number of lines has exceeded the maximum limit.
 279          * @exception   E_INVALID_ARG           A specified input parameter is invalid, or @n
 280          *                                                                              the specified @c maxLines is either negative or @c 0.
 281          * @exception   E_SYSTEM                A system error has occurred.
 282          */
 283         result Construct(const Tizen::Graphics::FloatRectangle& rect, ExpandableEditAreaStyle style, ExpandableEditAreaTitleStyle titleStyle, int maxExpandableLines = 10);
 284
 285 // TEXT MANAGEMENT
 286         /**
 287          * Appends the specified character at the end of the existing text.
 288          *
 289          * @since       2.0
 290          *
 291          * @return      An error code
 292          * @param[in]   character       The character to append
 293          * @exception   E_SUCCESS               The method is successful.
 294          * @exception   E_MAX_EXCEEDED  The number of items has exceeded the maximum limit. @n
 295          *                              The number of characters has exceeded the maximum limit.
 296          * @exception   E_SYSTEM                A system error has occurred.
 297          * @remarks     The method modifies the text buffer that is managed by the %ExpandableEditArea control. To display the changes, the control must be drawn again.
 298          */
 299         result AppendCharacter(const Tizen::Base::Character& character);
 300
 301         /**
 302          * Appends the specified text at the end of the existing text.
 303          *
 304          * @since       2.0
 305          *
 306          * @return      An error code
 307          * @param[in]   text            The text to append
 308          * @exception   E_SUCCESS       The method is successful.
 309          * @exception   E_MAX_EXCEEDED  The number of items has exceeded the maximum limit @n
 310          *                              The number of characters has exceeded the maximum limit.
 311          * @exception   E_SYSTEM        A system error has occurred.
 312          * @remarks     The method modifies the text buffer that is managed by the %ExpandableEditArea control. To display the changes, the control must be drawn again.
 313          */
 314         result AppendText(const Tizen::Base::String& text);
 315
 316         /**
 317         * Appends the text that will be displayed by bitmap at the end of the existing text.
 318         *
 319         * @since 2.0
 320         *
 321         * @return             An error code
 322         * @param[in]   text            The text to append @n
 323         *                                                                  It will be displayed by the @c textImage.
 324         * @param[in]   textImage The alternate bitmap to display
 325         * @exception   E_SUCCESS        The method is successful.
 326         * @exception   E_MAX_EXCEEDED  The length of the specified @c text exceeds the maximum length of the text that can be displayed by % ExpanableEditArea.
 327         * @exception   E_UNSUPPORTED_OPERATION  The current state of the instance prohibits the execution of the specified operation. @n
 328         *                                                             The operation is not supported if the style is ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
 329         * @remarks      The method modifies the text buffer that is managed by the %ExpanableEditArea control. To display the changes, the control must be drawn again.
 330         */
 331         result AppendText(const Tizen::Base::String& text, const Tizen::Graphics::Bitmap& textImage);
 332
 333         /**
 334         * Deletes the character present at the current cursor position.
 335         *
 336         * @since       2.0
 337         *
 338         * @return      An error code
 339         * @param[in]   index                    The index
 340         * @exception   E_SUCCESS                The method is successful.
 341         * @exception   E_INVALID_ARG    The specified input parameter is invalid. @n
 342         *                                                               The specified @c index is negative.
 343         * @exception   E_OUT_OF_RANGE  The specified @c index is outside the bounds of the data structure. @n
 344         *                                                               Either the specified @c index is greater than the number of elements or less than @c 0.
 345         * @exception   E_SYSTEM         A system error has occurred.
 346         * @remarks       The method modifies the text buffer that is managed by the %ExpandableEditArea control. To display the changes, the control must be drawn again.
 347         */
 348         result DeleteCharacterAt(int index);
 349
 350         /**
 351         * Inserts a character at the specified index.
 352         *
 353         * @since       2.0
 354         *
 355         * @return           An error code
 356         * @param[in]   index           The position to insert the character
 357         * @param[in]   character            The character to insert
 358         * @exception   E_SUCCESS        The method is successful.
 359         * @exception   E_OUT_OF_RANGE  The specified @c index is outside the bounds of the data structure. @n
 360         *                                                               Either the specified @c index is greater than the number of elements or less than @c 0.
 361         * @exception   E_MAX_EXCEEDED  The length of the specified @c text exceeds system limitations.
 362         * @exception   E_SYSTEM        A system error has occurred.
 363         * @remarks      The method modifies the text buffer that is managed by the %ExpandableEditArea control. To display the changes, the control must be drawn again.
 364         */
 365         result InsertCharacterAt(int index, const Tizen::Base::Character& character);
 366
 367         /**
 368         * Inserts the text at the specified index.
 369         *
 370         * @since       2.0
 371         *
 372         * @return           An error code
 373         * @param[in]   index           The position to insert the text
 374         * @param[in]   text            The text to insert
 375         * @exception   E_SUCCESS        The method is successful.
 376         * @exception   E_OUT_OF_RANGE  The specified @c index is outside the bounds of the data structure. @n
 377         *                                                               Either the specified @c index is greater than the number of elements or less than @c 0.
 378         * @exception   E_MAX_EXCEEDED  The length of the specified @c text exceeds system limitations.
 379         * @exception   E_SYSTEM     A system error has occurred.
 380         */
 381         result InsertTextAt(int index, const Tizen::Base::String& text);
 382
 383         /**
 384         * Inserts the text that will be displayed by bitmap at the specified text position.
 385         *
 386         * @since 2.0
 387         *
 388         * @return             An error code
 389         * @param[in]   position           The position to insert the text
 390         * @param[in]   text            The text to insert @n
 391         *                                                                  It will be displayed by the @c textImage.
 392         * @param[in]   textImage The alternate bitmap to display
 393         * @exception   E_SUCCESS        The method is successful.
 394         * @exception   E_OUT_OF_RANGE  The specified @c position is outside the valid range. @n
 395         *                                Either the specified @c position is greater than the number of existing text in the % ExpanableEditArea or less than @c 0.
 396         * @exception   E_MAX_EXCEEDED  The length of the specified @c text exceeds the maximum length of the text that can be displayed by % ExpanableEditArea.
 397         * @exception   E_UNSUPPORTED_OPERATION  The current state of the instance prohibits the execution of the specified operation. @n
 398         *                                                                               The operation is not supported if the style     is ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
 399         * @remarks      The method modifies the text buffer that is managed by the %ExpanableEditArea control. To display the changes, the control must be drawn again.
 400         */
 401         result InsertTextAt(int position, const Tizen::Base::String& text, const Tizen::Graphics::Bitmap& textImage);
 402
 403         /**
 404         * Gets the portion of the text that is displayed by the %ExpandableEditArea control.
 405         *
 406         * @since        2.0
 407         *
 408         * @return       The specified portion of the text, @n
 409         *               else an empty string if an error occurs
 410         * @param[in]    start           The starting index of the range
 411         * @param[in]    end             The last index of the range
 412         * @exception    E_SUCCESS       The method is successful.
 413         * @exception    E_OUT_OF_RANGE  The specified index is outside the bounds of the data structure. @n
 414         *                                                                The specified @c start or @c end is greater than the number of elements or less than @c 0.
 415         * @exception    E_SYSTEM        A system error has occurred.
 416         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 417         * @see          GetText()
 418         * @see          SetText()
 419         */
 420         Tizen::Base::String GetText(int start, int end) const;
 421
 422         /**
 423         * Gets the text of the %ExpandableEditArea control.
 424         *
 425         * @since        2.0
 426         *
 427         * @return       The text of the %ExpandableEditArea control, @n
 428         *               else an empty string if an error occurs
 429         * @exception    E_SUCCESS       The method is successful.
 430         * @exception    E_SYSTEM        A system error has occurred.
 431         * @remarks      The specific error code can be accessed using the GetLastResult() method.
 432         */
 433         Tizen::Base::String GetText(void) const;
 434
 435         /**
 436         * Gets the text length.
 437         *
 438         * @since       2.0
 439         *
 440         * @return      The length of the text, @n
 441         *                   else @c -1 if an error occurs
 442         * @exception   E_SUCCESS       The method is successful.
 443         * @exception   E_SYSTEM        A system error has occurred.
 444         * @remarks     The specific error code can be accessed using the GetLastResult() method.
 445         */
 446         int GetTextLength(void) const;
 447
 448         /**
 449         * Sets the text to be displayed by the %ExpandableEditArea control.
 450         *
 451         * @since                2.0
 452         *
 453         * @param[in]    text            The text to set @n
 454         *                                       To denote the end of a line use '\\n'.
 455         * @exception    E_SUCCESS       The method is successful.
 456         * @exception    E_INVALID_ARG   The specified input parameter is invalid, @n
 457         *                                                               or the length of the specified @c text exceeds system limitations.
 458         * @exception    E_SYSTEM        A system error has occurred.
 459         * @remarks      The method modifies the text buffer that is managed by the %ExpandableEditArea control. To display the changes, the control must be drawn again.
 460         */
 461         result SetText(const Tizen::Base::String& text);
 462
 463         /**
 464         * Clears the text that is displayed by the %ExpandableEditArea control.
 465         *
 466         * @since                2.0
 467         *
 468         * @return               An error code
 469         * @exception    E_SUCCESS       The method is successful.
 470         * @exception    E_SYSTEM        A system error has occurred.
 471         * @remarks      The method modifies the text buffer that is managed by the %ExpandableEditArea control. To display the changes, the control must be drawn again.
 472         */
 473         result Clear(void);
 474
 475         /**
 476          * Sets the title of the %ExpandableEditArea control.
 477          *
 478          * @since               2.0
 479          *
 480          * @return              An error code
 481          * @param[in]   title                   The title to set
 482          * @exception   E_SUCCESS               The method is successful.
 483          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
 484          *                                                                      This operation is not supported if the title is not set.
 485          * @exception   E_SYSTEM                A system error has occurred.
 486          */
 487         result SetTitleText(const Tizen::Base::String& title);
 488
 489         /**
 490          * Gets the title of the %ExpandableEditArea control.
 491          *
 492          * @since               2.0
 493          *
 494          * @return              The title text of the entered string, @n
 495          *                          else empty string if an error occurs
 496          * @exception   E_SUCCESS       The method is successful.
 497          * @exception   E_SYSTEM        A system error has occurred.
 498          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 499          */
 500         Tizen::Base::String GetTitleText(void) const;
 501
 502 // GUIDE TEXT
 503         /**
 504          * Gets the guide text.
 505          *
 506          * @since       2.0
 507          *
 508          * @return          The guide text, @n
 509          *              else an empty string if an error occurs
 510          * @exception   E_SUCCESS        The method is successful.
 511          * @exception   E_SYSTEM         A system error has occurred.
 512          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 513          * @see         SetGuideText()
 514          */
 515         Tizen::Base::String GetGuideText(void) const;
 516
 517         /**
 518         * Sets the guide text to be displayed, when there is no data in the search field.
 519         *
 520         * @since       2.0
 521         *
 522         * @return           An error code
 523         * @param[in]   guideText                 The guide text
 524         * @exception   E_SUCCESS        The method is successful.
 525         * @exception   E_SYSTEM         A system error has occurred.
 526         * @see         GetGuideText()
 527         */
 528         result SetGuideText(const Tizen::Base::String& guideText);
 529
 530 // LINE MANAGEMENT
 531         /**
 532          * Gets the maximum line count supported by the flexible text edit.
 533          *
 534          * @since       2.0
 535          *
 536          * @return      The maximum line count, @n
 537          *                  else @c -1 if an error occurs
 538          * @exception   E_SUCCESS           The method is successful.
 539          * @exception   E_SYSTEM            A system error has occurred.
 540          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 541          */
 542         int GetMaxLineCount(void) const;
 543
 544         /**
 545          * Gets the line spacing.
 546          *
 547          * @since 2.0
 548          * @return      The line spacing, @n
 549          *                  else @c -1 if an error occurs
 550          * @see         SetLineSpacing ()
 551          */
 552         int GetLineSpacing(void) const;
 553
 554         /**
 555          * Gets the line spacing.
 556          *
 557          * @since 2.1
 558          * @return      The line spacing, @n
 559          *                  else @c -1.0f if an error occurs
 560          * @see         SetLineSpacing ()
 561          */
 562
 563         float GetLineSpacingF(void) const;
 564
 565         /**
 566          * Sets the line spacing. @n
 567          * The line spacing is determined by multiplying @c multiplier to the default line spacing and adding @c extra.
 568          *
 569          * @code
 570          * The line spacing = (default line spacing) * multiplier + extra
 571          * @endcode
 572          *
 573          * @since 2.0
 574          * @return      An error code
 575          * @param[in]   multiplier               The line spacing multiplier
 576          * @param[in]   extra            The extra line spacing
 577          * @exception   E_SUCCESS           The method is successful.
 578          * @exception   E_INVALID_ARG       This exception is returned when @c multiplier or @c extra is less than 0.
 579          * @see         GetLineSpacing ()
 580          */
 581         result SetLineSpacing(int multiplier, int extra);
 582
 583         /**
 584          * Sets the line spacing. @n
 585          * The line spacing is determined by multiplying @c multiplier to the default line spacing and adding @c extra.
 586          *
 587          * @code
 588          * The line spacing = (default line spacing) * multiplier + extra
 589          * @endcode
 590          *
 591          * @since 2.1
 592          * @return      An error code
 593          * @param[in]   multiplier               The line spacing multiplier
 594          * @param[in]   extra            The extra line spacing
 595          * @exception   E_SUCCESS           The method is successful.
 596          * @exception   E_INVALID_ARG       This exception is returned when @c multiplier or @c extra is less than 0.
 597          * @see         GetLineSpacing ()
 598          */
 599         result SetLineSpacing(int multiplier, float extra);
 600
 601         /**
 602         * Gets the current line count.
 603         *
 604         * @since       2.0
 605         *
 606         * @return      The line count of the text
 607         * @exception   E_SUCCESS           The method is successful.
 608         * @exception   E_SYSTEM            A system error has occurred.
 609         * @remarks     The specific error code can be accessed using the GetLastResult() method.
 610         */
 611         int GetTextLineCount(void) const;
 612
 613 // TEXT SIZE
 614         /**
 615          * Gets the text size.
 616          *
 617          * @since       2.0
 618          *
 619          * @return      The size of the text, @n
 620          *                  else @c -1 if an error occurs
 621          * @exception   E_SUCCESS           The method is successful.
 622          * @exception   E_SYSTEM            A system error has occurred.
 623          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 624          * @see         SetTextSize()
 625          */
 626         int GetTextSize(void) const;
 627
 628         /**
 629          * Gets the text size.
 630          *
 631          * @since       2.1
 632          *
 633          * @return      The size of the text, @n
 634          *                  else @c -1 if an error occurs
 635          * @exception   E_SUCCESS           The method is successful.
 636          * @exception   E_SYSTEM            A system error has occurred.
 637          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 638          * @see         SetTextSize()
 639          */
 640         float GetTextSizeF(void) const;
 641
 642         /**
 643         * Sets the text size.
 644         *
 645         * @since       2.0
 646         *
 647         * @return      An error code
 648         * @param[in]   size                The text size
 649         * @exception   E_SUCCESS           The method is successful.
 650         * @exception   E_INVALID_ARG       The specified @c size is invalid, @n
 651         *                                                                       or the specified @c size is a negative integer.
 652         * @exception   E_SYSTEM            A system error has occurred.
 653         * @remarks     The specified @c size should be greater than or equal to minimum font size which is 4.
 654         * @see         GetTextSize()
 655         */
 656         result SetTextSize(int size);
 657
 658         /**
 659         * Sets the text size.
 660         *
 661         * @since       2.1
 662         *
 663         * @return      An error code
 664         * @param[in]   size                The text size @n
 665         *                                               The size should be greater than or equal to minimum font size which is 4.0f.
 666         * @exception   E_SUCCESS           The method is successful.
 667         * @exception   E_INVALID_ARG       The specified @c size is invalid, @n
 668         *                                                                       or the specified @c size is a negative integer.
 669         * @exception   E_SYSTEM            A system error has occurred.
 670         * @see         GetTextSizeF()
 671         */
 672         result SetTextSize(float size);
 673
 674 // MARGINS
 675         /**
 676          * Gets the margin of the specified margin type.
 677          *
 678          * @since       2.0
 679          *
 680          * @return      The margin value of the specified margin type, @n
 681          *                  else @c -1 if an error occurs
 682          * @param[in]   marginType      The margin type
 683          * @exception   E_SUCCESS       The method is successful.
 684          * @exception   E_SYSTEM        A system error has occurred.
 685          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 686          * @see         SetMargin()
 687          */
 688         int GetMargin(EditMarginType marginType) const;
 689
 690         /**
 691          * Gets the margin of the specified margin type.
 692          *
 693          * @since       2.1
 694          *
 695          * @return      The margin value of the specified margin type, @n
 696          *                  else @c -1.0f if an error occurs
 697          * @param[in]   marginType      The margin type
 698          * @exception   E_SUCCESS       The method is successful.
 699          * @exception   E_SYSTEM        A system error has occurred.
 700          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 701          * @see         SetMargin()
 702          */
 703         float GetMarginF(EditMarginType marginType) const;
 704
 705         /**
 706          * Sets the margin for the specified margin type.
 707          *
 708          * @if OSPCOMPAT
 709          * @brief <i> [Compatibility] </i>
 710          * @endif
 711          * @since       2.0
 712          * @if OSPCOMPAT
 713          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 714          *                         For more information, see @ref CompSetMarginPage "here".
 715          * @endif
 716          * @return      An error code
 717          * @param[in]   marginType          The margin type
 718          * @param[in]   margin              The margin to set
 719          * @exception   E_SUCCESS           The method is successful.
 720          * @exception   E_INVALID_ARG       A specified input parameter is invalid. @n
 721          *                                  The specified @c margin cannot be negative integer.
 722          * @exception   E_SYSTEM            A system error has occurred.
 723          * @see         GetMargin()
 724          */
 725         result SetMargin(EditMarginType marginType, int margin);
 726         /**
 727          * @if OSPCOMPAT
 728          * @page                  CompSetMarginPage Compatibility for SetMargin()
 729          * @section           CompSetMarginPageIssueSection                 Issues
 730          * Implementing this method in OSP compatible applications has the following issues:   @n
 731          * -# The SetMargin() method sets the margin value for ExpandableEditArea with only @c EXPANDABLE_EDIT_AREA_STYLE_NORMAL
 732          *      in API version 2.0. @n
 733          *
 734          * @section           CompSetMarginPageSolutionSection              Resolutions
 735          * This issue has been resolved in Tizen.  @n
 736          * @endif
 737          */
 738
 739         /*
 740          * Sets the margin for the specified margin type.
 741          *
 742          * @if OSPCOMPAT
 743          * @brief <i> [Compatibility] </i>
 744          * @endif
 745          * @since       2.1
 746          * @if OSPCOMPAT
 747          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 748          *                         For more information, see @ref CompSetMarginPage "here".
 749          * @endif
 750          * @return      An error code
 751          * @param[in]   marginType          The margin type
 752          * @param[in]   margin              The margin to set
 753          * @exception   E_SUCCESS           The method is successful.
 754          * @exception   E_INVALID_ARG       A specified input parameter is invalid. @n
 755          *                                  The specified @c margin cannot be negative integer.
 756          * @exception   E_SYSTEM            A system error has occurred.
 757          * @see         GetMargin()
 758          */
 759         result SetMargin(EditMarginType marginType, float margin);
 760         /*
 761          * @if OSPCOMPAT
 762          * @page                  CompSetMarginPage Compatibility for SetMargin()
 763          * @section           CompSetMarginPageIssueSection                 Issues
 764          * Implementing this method in OSP compatible applications has the following issues:   @n
 765          * -# The SetMargin() method sets the margin value for ExpandableEditArea with only @c EXPANDABLE_EDIT_AREA_STYLE_NORMAL
 766          *      in API version 2.0. @n
 767          *
 768          * @section           CompSetMarginPageSolutionSection              Resolutions
 769          * This issue has been resolved in Tizen.  @n
 770          * @endif
 771          */
 772
 773 // LOWER CASE
 774         /**
 775          * Enables or disables the lowercase mode. @n
 776          * When the lowercase mode is enabled, the text input starts with a lowercase character.
 777          * @since       2.0
 778          *
 779          * @return      An error code
 780          * @param[in]   enable              Set to @c true to enable the lowercase mode, @n
 781          *                                      else @c false
 782          * @exception   E_SUCCESS           The method is successful.
 783          * @exception   E_SYSTEM            A system error has occurred.
 784          * @see         IsLowerCaseModeEnabled()
 785          */
 786         result SetLowerCaseModeEnabled(bool enable);
 787
 788         /**
 789          * Checks whether the lowercase mode is enabled.
 790          *
 791          * @since       2.0
 792          *
 793          * @return      @c true if the lowercase mode is enabled, @n
 794          *                  else @c false
 795          * @exception   E_SUCCESS           The method is successful.
 796          * @exception   E_SYSTEM            A system error has occurred.
 797          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 798          * @see         SetLowerCaseModeEnabled()
 799          */
 800         bool IsLowerCaseModeEnabled(void) const;
 801
 802 // CURSOR MANAGEMENT
 803         /**
 804          * Gets the cursor position.
 805          *
 806          * @since        2.0
 807          *
 808          * @return       The current cursor position, @n
 809          *                               else @c -1 if an error occurs
 810          * @exception    E_SUCCESS          The method is successful.
 811          * @exception    E_SYSTEM           A system error has occurred.
 812          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 813          */
 814         int GetCursorPosition(void) const;
 815
 816         /**
 817          * Sets the cursor at the specified position.
 818          *
 819          * @since        2.0
 820          *
 821          * @return       An error code
 822          * @param[in]    position        The cursor position to set
 823          * @exception    E_SUCCESS       The method is successful.
 824          * @exception    E_OUT_OF_RANGE  The specified @c position is less than @c 0 or greater than the maximum length.
 825          * @exception    E_SYSTEM        A system error has occurred.
 826          */
 827         result SetCursorPosition(int position);
 828
 829 // TEXT BLOCKING
 830         /**
 831          * Gets the start and end indexes of the currently selected text block.
 832          *
 833          * @since       2.0
 834          *
 835          * @return      An error code
 836          * @param[out]  start              The start index of the text block @n
 837          *                                              The value is @c 0 if no text block is selected.
 838          * @param[out]  end                The end index of the text block @n
 839          *                                              The value is @c 0 if no text block is selected.
 840          * @exception   E_SUCCESS          The method is successful.
 841          * @exception   E_SYSTEM           A system error has occurred.
 842          * @see         ReleaseBlock()
 843          * @see         SetBlockRange()
 844          */
 845         result GetBlockRange(int& start, int& end) const;
 846
 847         /**
 848         * Releases the selection of the current text block.
 849         *
 850         * @since       2.0
 851         *
 852         * @return      An error code
 853         * @exception   E_SUCCESS          The method is successful.
 854         * @exception   E_SYSTEM           A system error has occurred.
 855         * @see         GetBlockRange()
 856         * @see         SetBlockRange()
 857         */
 858         result ReleaseBlock(void);
 859
 860         /**
 861         * Removes the text content of the current text block.
 862         *
 863         * @since        2.0
 864         *
 865         * @return       An error code
 866         * @exception    E_SUCCESS          The method is successful.
 867         * @exception    E_OBJ_NOT_FOUND    The specified instance is not found, @n
 868         *                                                                       or the text block is not selected.
 869         * @exception    E_SYSTEM           A system error has occurred.
 870         */
 871         result RemoveTextBlock(void);
 872
 873         /**
 874         * Sets the block range for the text.
 875         *
 876         * @since       2.0
 877         *
 878         * @return      An error code
 879         * @param[in]   start           The start index of the text block
 880         * @param[in]   end             The end index of the text block
 881         * @exception   E_SUCCESS       The method is successful.
 882         * @exception   E_OUT_OF_RANGE  The specified index is outside the bounds of the data structure. @n
 883         *                                                               Either the index is greater than the number of elements or less than @c 0.
 884         * @exception   E_SYSTEM        A system error has occurred.
 885         * @see         ReleaseBlock()
 886         * @see         GetBlockRange()
 887         */
 888         result SetBlockRange(int start, int end);
 889
 890 // KEYPAD MANAGEMENT
 891         /**
 892          * Gets the keypad action type.
 893          *
 894          * @since       2.0
 895          *
 896          * @return      The keypad action
 897          * @exception   E_SUCCESS           The method is successful.
 898          * @exception   E_SYSTEM            A system error has occurred.
 899          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 900          * @see         SetKeypadAction()
 901          */
 902         Tizen::Ui::KeypadAction GetKeypadAction(void) const;
 903
 904         /**
 905         * Gets the keypad style.
 906         *
 907         * @since       2.0
 908         *
 909         * @return      The keypad style
 910         * @exception   E_SUCCESS           The method is successful.
 911         * @exception   E_SYSTEM            A system error has occurred.
 912         * @remarks     The specific error code can be accessed using the GetLastResult() method.
 913         * @see         SetKeypadStyle()
 914         */
 915         KeypadStyle GetKeypadStyle(void) const;
 916
 917         /**
 918         * Hides the keypad associated with the %ExpandableEditArea control.
 919         *
 920         * @since       2.0
 921         *
 922         * @return      An error code
 923         * @exception   E_SUCCESS           The method is successful.
 924         * @exception   E_SYSTEM            A system error has occurred.
 925         * @see         ShowKeypad()
 926         */
 927         result HideKeypad(void);
 928
 929         /**
 930         * Checks whether the keypad is enabled.
 931         *
 932         * @since       2.0
 933         *
 934         * @return      @c true if the keypad is enabled, @n
 935         *                   else @c false
 936         * @exception   E_SUCCESS            The method is successful.
 937         * @exception   E_SYSTEM             A system error has occurred.
 938         * @remarks     The specific error code can be accessed using the GetLastResult() method.
 939         * @see         SetKeypadEnabled()
 940         */
 941         bool IsKeypadEnabled(void) const;
 942
 943         /**
 944          * Sets the keypad action type.
 945          *
 946          * @since               2.0
 947          *
 948          * @return      An error code
 949          * @param[in]   keypadAction                    The keypad action
 950          * @exception   E_SUCCESS                               The method is successful.
 951          * @exception   E_SYSTEM                                A system error has occurred.
 952          * @remarks     Depending on the value of input param, the enter key label of the keypad will change accordingly.
 953          * @see         GetKeypadAction()
 954          */
 955         result SetKeypadAction(Tizen::Ui::KeypadAction keypadAction);
 956
 957         /**
 958         * Sets the keypad style.
 959         *
 960         * @since       2.0
 961         *
 962         * @return      An error code
 963         * @param[in]   keypadStyle         The keypad style
 964         * @exception   E_SUCCESS           The method is successful.
 965         * @exception   E_INVALID_ARG       The specified input parameter is invalid. @n
 966         *                                  The specified @c keypadStyle is @c KEYPAD_STYLE_PASSWORD.
 967         * @exception   E_SYSTEM            A system error has occurred.
 968         * @remarks     Depending on the value of input param, the layout of the keypad will change accordingly.
 969         * @see         GetKeypadStyle()
 970         */
 971         result SetKeypadStyle(KeypadStyle keypadStyle);
 972
 973         /**
 974         * Checks whether the text prediction is enabled.
 975         *
 976         * @since 2.0
 977         * @return                @c true if the text prediction is enabled, @n
 978         *                                 else @c false
 979         * @see                      SetTextPredictionEnabled()
 980         */
 981         bool IsTextPredictionEnabled(void) const;
 982
 983         /**
 984         * Enables or disables the text prediction.
 985         *
 986         * @since 2.0
 987         * @param[in]           enable                       Set to @c true to enable the text prediction, @n
 988         *                                                                    else @c false
 989         * @return                An error code
 990         * @exception           E_SUCCESS                The method is successful.
 991         * @exception            E_UNSUPPORTED_OPERATION     This operation is not supported.
 992         * @see                    IsTextPredictionEnabled()
 993         */
 994         result SetTextPredictionEnabled(bool enable);
 995
 996         /**
 997         * Enables or disables the keypad.
 998         *
 999         * @since       2.0
1000         *
1001         * @return      An error code
1002         * @param[in]   enable                   Set to @c true to enable the virtual keypad, @n
1003         *                                                               else @c false
1004         * @exception   E_SUCCESS                The method is successful.
1005         * @exception   E_SYSTEM         A system error has occurred.
1006         * @see         IsKeypadEnabled()
1007         */
1008         result SetKeypadEnabled(bool enable);
1009
1010         /**
1011         * Shows the keypad.
1012         *
1013         * @since       2.0
1014         *
1015         * @return      An error code
1016         * @exception   E_SUCCESS           The method is successful.
1017         * @exception   E_SYSTEM            A system error has occurred.
1018         * @see         HideKeypad()
1019         */
1020         result ShowKeypad(void);
1021
1022 // TOKEN FILTER
1023         /**
1024          * Sets the text token filter.
1025          *
1026          * @since       2.0
1027          *
1028          * @return      An error code
1029          * @param[in]   pFilter                 The filter
1030          * @exception   E_SUCCESS               The method is successful.
1031          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
1032          *                                                                              The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1033          * @exception   E_SYSTEM                A system error has occurred.
1034          * @remarks     The %ExpandableEditArea control checks with the registered filter to decide whether the user-entered text should be replaced.
1035          */
1036         result SetTokenFilter(const ITokenFilter* pFilter);
1037
1038         /**
1039         * Gets the text token filter.
1040         *
1041         * @since        2.0
1042         *
1043         * @return       The filter, @n
1044         *                                else @c null if an error occurs
1045         * @exception    E_SUCCESS                   The method is successful.
1046         * @exception     E_UNSUPPORTED_OPERATION        The current state of the instance prohibits the execution of the specified operation. @n
1047         *                                                                                       The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1048         * @exception    E_SYSTEM                    A system error has occurred.
1049         * @remarks      The specific error code can be accessed using the GetLastResult() method.
1050         */
1051         ITokenFilter* GetTokenFilter(void) const;
1052
1053         /**
1054         * Appends the specified token.
1055         *
1056         * @since        2.0
1057         *
1058         * @return       An error code
1059         * @param[in]    token                   The token to append
1060         * @exception    E_SUCCESS               The method is successful.
1061         * @exception     E_UNSUPPORTED_OPERATION        The current state of the instance prohibits the execution of the specified operation. @n
1062         *                                                                                       The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1063         * @exception    E_INVALID_ARG           The specified input parameter is invalid. @n
1064         *                                           The length of the specified @c token is @c 0.
1065         * @exception    E_SYSTEM                A system error has occurred.
1066         */
1067         result AppendToken(const Tizen::Base::String& token);
1068
1069         /**
1070          * Inserts the token at the specified index.
1071          *
1072          * @since        2.0
1073          *
1074          * @return       An error code
1075          * @param[in]    index                                          The position to insert the token
1076          * @param[in]    token                      The token to add
1077          * @exception    E_SUCCESS                  The method is successful.
1078          * @exception    E_UNSUPPORTED_OPERATION        The current state of the instance prohibits the execution of the specified operation. @n
1079          *                                                                                      The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1080          * @exception    E_INVALID_ARG              A specified input parameter is invalid. @n
1081          *                                          The length of the specified @c token is @c 0.
1082          * @exception    E_SYSTEM                   A system error has occurred.
1083          */
1084         result InsertTokenAt(int index, const Tizen::Base::String& token);
1085
1086         /**
1087          * Gets the token text at the specified index.
1088          *
1089          * @since        2.0
1090          *
1091          * @return       The token text at the specified index, @n
1092          *               else an empty string if an error occurs
1093          * @param[in]      index                                                          The position to get the token
1094          * @exception    E_SUCCESS                  The method is successful.
1095          * @exception    E_UNSUPPORTED_OPERATION        The current state of the instance prohibits the execution of the specified operation. @n
1096          *                                                                                      The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1097          * @exception    E_OUT_OF_RANGE                         The specified index parameter is outside the bounds of the data structure. @n
1098          *                                                                                      Either the index is greater than the number of elements or less than @c 0.
1099          * @exception    E_SYSTEM                   A system error has occurred.
1100          * @remarks      The specific error code can be accessed using the GetLastResult() method.
1101          */
1102         Tizen::Base::String GetTokenAt(int index) const;
1103
1104         /**
1105          * Gets the total token count.
1106          *
1107          * @since        2.0
1108          *
1109          * @return       The total token count, @n
1110          *                   else @c -1 if an error occurs
1111          * @exception    E_SUCCESS                  The method is successful.
1112          * @exception    E_UNSUPPORTED_OPERATION        The current state of the instance prohibits the execution of the specified operation. @n
1113          *                                                                                      The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1114          * @exception    E_SYSTEM                   A system error has occurred.
1115          * @remarks      The specific error code can be accessed using the GetLastResult() method.
1116          */
1117         int GetTokenCount(void) const;
1118
1119         /**
1120          * Gets the index of the token that is selected.
1121          *
1122          * @since        2.0
1123          *
1124          * @return       The index of the selected token, @n
1125          *                   else @c -1 if no token is selected or if an error occurs
1126          * @exception    E_SUCCESS                  The method is successful.
1127          * @exception    E_UNSUPPORTED_OPERATION        The current state of the instance prohibits the execution of the specified operation. @n
1128          *                                                                                      The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1129          * @exception    E_SYSTEM                   A system error has occurred.
1130          * @remarks      The specific error code can be accessed using the GetLastResult() method.
1131          */
1132         int GetSelectedTokenIndex(void) const;
1133
1134         /**
1135         * Checks whether the token editing mode is enabled.
1136         *
1137         * @since        2.0
1138         *
1139         * @return       @c true if the editing mode is enabled, @n
1140         *                    else @c false
1141         * @exception    E_SUCCESS                   The method is successful.
1142         * @exception     E_UNSUPPORTED_OPERATION        The current state of the instance prohibits the execution of the specified operation. @n
1143         *                                                                                       The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1144         * @exception    E_SYSTEM                    A system error has occurred.
1145         * @remarks      The specific error code can be accessed using the GetLastResult() method.
1146         */
1147         bool IsTokenEditModeEnabled(void) const;
1148
1149         /**
1150         * Removes the token at the specified index.
1151         *
1152         * @since        2.0
1153         *
1154         * @return       An error code
1155         * @param[in]    index                   The index of the token to remove
1156         * @exception    E_SUCCESS               The method is successful.
1157         * @exception     E_UNSUPPORTED_OPERATION        The current state of the instance prohibits the execution of the specified operation. @n
1158         *                                                                                       The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1159         * @exception    E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure. @n
1160         *                                                                                       Either the index is greater than the number of elements or less than @c 0.
1161         * @exception    E_SYSTEM                A system error has occurred.
1162         */
1163         result RemoveTokenAt(int index);
1164
1165         /**
1166         * Sets the selected state of the specified token.
1167         *
1168         * @since        2.0
1169         *
1170         * @return       An error code
1171         * @param[in]    index                   The index of the token to select
1172         * @param[in]    selected                Set to @c true to select the specified token, @n
1173         *                                                                                       else @c false to unselect
1174         * @exception    E_SUCCESS               The method is successful.
1175         * @exception     E_UNSUPPORTED_OPERATION        The current state of the instance prohibits the execution of the specified operation. @n
1176         *                                                                                       The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1177         * @exception    E_OUT_OF_RANGE          The specified index is outside the bounds of the data structure. @n
1178         *                                                                                       Either the index is greater than the number of elements or less than @c 0.
1179         * @exception    E_SYSTEM                A system error has occurred.
1180         * @remarks      The currently selected token gets unselected automatically.
1181         */
1182         result SetTokenSelected(int index, bool selected);
1183
1184         /**
1185         * Enables or disables the token edit mode.
1186         *
1187         * @since        2.0
1188         *
1189         * @return       An error code
1190         * @param[in]    enable                      Set to @c true to enable the token editing mode, @n
1191         *                                                                                       else @c false
1192         * @exception    E_SUCCESS               The method is successful.
1193         * @exception     E_UNSUPPORTED_OPERATION        The current state of the instance prohibits the execution of the specified operation. @n
1194         *                                                                                       The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1195         * @exception    E_SYSTEM                A system error has occurred.
1196         */
1197         result SetTokenEditModeEnabled(bool enable);
1198
1199 // LIMIT LENGTH
1200         /**
1201          * Gets the limit length.
1202          *
1203          * @since               2.0
1204          *
1205          * @return      The limit length, @n
1206          *                  else @c -1 if an error occurs @n
1207          *                      The default limit length is @c 2048.
1208          * @exception   E_SUCCESS                       The method is successful.
1209          * @exception   E_SYSTEM                        A system error has occurred.
1210          * @remarks     The specific error code can be accessed using the GetLastResult() method.
1211          * @see         SetLimitLength()
1212          */
1213         int GetLimitLength(void) const;
1214
1215         /**
1216          * Sets the limit length.
1217          *
1218          * @since       2.0
1219          *
1220          * @return      An error code
1221          * @param[in]   limitLength             The limit text length to set
1222          * @exception   E_SUCCESS               The method is successful.
1223          * @exception   E_INVALID_ARG   The specified input parameter is invalid, @n
1224          *                                                              or the specified limit length is @c 0 or negative.
1225          * @exception   E_SYSTEM                A system error has occurred.
1226          * @remarks     The method modifies the text buffer that is managed by the %ExpandableEditArea control. To display the changes, the control must be drawn again.
1227          * @see         GetLimitLength()
1228          */
1229         result SetLimitLength(int limitLength);
1230
1231 // APPEARANCES
1232         /**
1233          * Gets the color of the %ExpandableEditArea control for the specified status.
1234          *
1235          * @since        2.0
1236          *
1237          * @return       The color, @n
1238          *                               else RGBA (0,0,0,0) if an error occurs
1239          * @param[in]    status                         The status
1240          * @exception    E_SUCCESS                      The method is successful.
1241          * @exception    E_SYSTEM                       A system error has occurred.
1242          * @remarks      The specific error code can be accessed using the GetLastResult() method.
1243          */
1244         Tizen::Graphics::Color GetColor(EditStatus status) const;
1245
1246         /**
1247          * Gets the text color of the specified text type.
1248          *
1249          * @since        2.0
1250          *
1251          * @return       The text color, @n
1252          *                               else RGBA (0,0,0,0) if an error occurs
1253          * @param[in]    type                The text type
1254          * @exception    E_SUCCESS                      The method is successful.
1255          * @exception    E_INVALID_ARG          The specified type is not supported, or @n
1256          *                                                                      the specified @c type is @c EDIT_TEXT_COLOR_LINK.
1257          * @exception    E_SYSTEM                       A system error has occurred.
1258          * @remarks      The specific error code can be accessed using the GetLastResult() method.
1259          * @see          SetTextColor()
1260          */
1261         Tizen::Graphics::Color GetTextColor(EditTextColor type) const;
1262
1263         /**
1264          * Gets the text color of the guide text.
1265          *
1266          * @since       2.0
1267          *
1268          * @return          The guide text color, @n
1269          *                              else RGBA (0,0,0,0) if an error occurs
1270          * @exception   E_SUCCESS                       The method is successful.
1271          * @exception   E_SYSTEM                        A system error has occurred.
1272          * @remarks     The specific error code can be accessed using the GetLastResult() method.
1273          * @see         SetGuideTextColor()
1274          */
1275         Tizen::Graphics::Color GetGuideTextColor(void) const;
1276
1277         /**
1278          * Gets the text color of the title for the specified status.
1279          *
1280          * @since               2.0
1281          *
1282          * @return              The title text color, @n
1283          *                              else RGBA (0,0,0,0) if an error occurs
1284          * @param[in]   status                  The state of the %ExpandableEditArea control
1285          * @exception   E_SUCCESS               The method is successful.
1286          * @exception   E_SYSTEM                A system error has occurred.
1287          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1288          * @see                 SetTitleTextColor()
1289          */
1290         Tizen::Graphics::Color GetTitleTextColor(EditStatus status) const;
1291
1292         /**
1293          * Gets the color of the tokens for the specified status.
1294          *
1295          * @since        2.0
1296          *
1297          * @return       The token color, @n
1298          *                               else RGBA (0,0,0,0) if an error occurs
1299          * @param[in]    status                     The status
1300          * @exception    E_SUCCESS                  The method is successful.
1301          * @exception    E_UNSUPPORTED_OPERATION        The current state of the instance prohibits the execution of the specified operation. @n
1302          *                                                                                      The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1303          * @exception    E_SYSTEM                   A system error has occurred.
1304          * @remarks      The specific error code can be accessed using the GetLastResult() method.
1305          * @see          SetTokenColor
1306          */
1307         Tizen::Graphics::Color GetTokenColor(ExpandableEditAreaTokenStatus status) const;
1308
1309         /**
1310          * Gets the text color of tokens.
1311          *
1312          * @since        2.0
1313          *
1314          * @return       The text color, @n
1315          *                               else RGBA (0,0,0,0) if an error occurs
1316          * @exception    E_SUCCESS                  The method is successful.
1317          * @exception    E_UNSUPPORTED_OPERATION        The current state of the instance prohibits the execution of the specified operation. @n
1318          *                                                                                      The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1319          * @exception    E_SYSTEM                   A system error has occurred.
1320          * @remarks      The specific error code can be accessed using the GetLastResult() method.
1321          * @see          SetTokenTextColor()
1322          */
1323         Tizen::Graphics::Color GetTokenTextColor(void) const;
1324
1325         /**
1326          * Gets the text color of tokens at the specified index.
1327          *
1328          * @since 2.0
1329          *
1330          * @return       The text color, @n
1331          *                              else RGBA (0,0,0,0) if an error occurs
1332          * @exception    E_SUCCESS                                      The method is successful.
1333          * @exception    E_UNSUPPORTED_OPERATION        The current state of the instance prohibits     the execution of the specified operation. @n
1334          *                                                                                      The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1335          * @exception    E_SYSTEM                   A system error has occurred.
1336          * @remarks      The specific error code can be accessed using the GetLastResult() method.
1337          * @see          SetSelectedTokenTextColor()
1338          */
1339         Tizen::Graphics::Color GetSelectedTokenTextColor(void) const;
1340
1341         /**
1342          * Sets the background bitmap of the %ExpandableEditArea control.
1343          *
1344          * @since       2.0
1345          *
1346          * @return      An error code
1347          * @param[in]   status          The status
1348          * @param[in]   bitmap          The background bitmap
1349          * @exception   E_SUCCESS       The method is successful.
1350          * @exception   E_SYSTEM        A system error has occurred.
1351          */
1352         result SetBackgroundBitmap(EditStatus status, const Tizen::Graphics::Bitmap& bitmap);
1353
1354         /**
1355          * Sets the color of the %ExpandableEditArea control.
1356          *
1357          * @since       2.0
1358          *
1359          * @return      An error code
1360          * @param[in]   status          The status of the %ExpandableEditArea control
1361          * @param[in]   color           The color
1362          * @exception   E_SUCCESS       The method is successful.
1363          * @exception   E_SYSTEM        A system error has occurred.
1364          * @see         GetColor()
1365          */
1366         result SetColor(EditStatus status, const Tizen::Graphics::Color& color);
1367
1368         /**
1369          * Sets the text color of the guide text.
1370          *
1371          * @since       2.0
1372          *
1373          * @return          An error code
1374          * @param[in]   color                The guide text color
1375          * @exception   E_SUCCESS        The method is successful.
1376          * @exception   E_SYSTEM         A system error has occurred.
1377          * @see         GetGuideTextColor()
1378          */
1379         result SetGuideTextColor(const Tizen::Graphics::Color& color);
1380
1381         /**
1382          * Sets the text color of the title for the specified status.
1383          *
1384          * @since       2.0
1385          *
1386          * @return          An error code
1387          * @param[in]   status                  The status of the %ExpandableEditArea control
1388          * @param[in]   color                   The title text color
1389          * @exception   E_SUCCESS               The method is successful.
1390          * @exception   E_SYSTEM                A system error has occurred.
1391          * @see         GetTitleTextColor()
1392          */
1393         result SetTitleTextColor(EditStatus status, const Tizen::Graphics::Color& color);
1394
1395         /**
1396          * Sets the text color of the %ExpandableEditArea control.
1397          *
1398          * @since       2.0
1399          *
1400          * @return      An error code
1401          * @param[in]   type             The text type
1402          * @param[in]   color            The text color
1403          * @exception   E_SUCCESS        The method is successful.
1404          * @exception   E_SYSTEM         A system error has occurred.
1405          * @see         GetTextColor()
1406          */
1407         result SetTextColor(EditTextColor type, const Tizen::Graphics::Color& color);
1408
1409         /**
1410          * Sets the text color of the tokens at the specified index.
1411          *
1412          * @since 2.0
1413          *
1414          * @return       An error code
1415          * @param[in]    color                  The token text color
1416          * @exception    E_SUCCESS                  The method is successful.
1417          * @exception    E_UNSUPPORTED_OPERATION        The current state of the instance prohibits     the execution of the specified operation. @n
1418          *                                                                                      The     operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1419          * @exception    E_SYSTEM                                       A system error has occurred.
1420          * @see          GetSelectedTokenTextColor()
1421          */
1422         result SetSelectedTokenTextColor(const Tizen::Graphics::Color& color);
1423
1424         /**
1425          * Sets the color of the tokens for the specified status.
1426          *
1427          * @since        2.0
1428          *
1429          * @return       An error code
1430          * @param[in]    status                     The status
1431          * @param[in]    color                      The token color
1432          * @exception    E_SUCCESS                  The method is successful.
1433          * @exception    E_UNSUPPORTED_OPERATION        The current state of the instance prohibits the execution of the specified operation. @n
1434          *                                                                                      The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1435          * @exception    E_SYSTEM                   A system error has occurred.
1436          * @see          GetTokenColor()
1437          */
1438         result SetTokenColor(ExpandableEditAreaTokenStatus status, const Tizen::Graphics::Color& color);
1439
1440         /**
1441          * Sets the text color of the tokens.
1442          *
1443          * @since        2.0
1444          *
1445          * @return       An error code
1446          * @param[in]    color                      The token text color
1447          * @exception    E_SUCCESS                  The method is successful.
1448          * @exception    E_UNSUPPORTED_OPERATION        The current state of the instance prohibits the execution of the specified operation. @n
1449          *                                                                                      The operation is not supported if the style is not ::EXPANDABLE_EDIT_AREA_STYLE_TOKEN.
1450          * @exception    E_SYSTEM                   A system error has occurred.
1451          * @see          GetTokenTextColor()
1452          */
1453         result SetTokenTextColor(const Tizen::Graphics::Color& color);
1454
1455         /**
1456          * @if OSPDEPREC
1457          * Enables or disables the auto resizing if the candidate word list appears.
1458          *
1459          * @brief <i> [Deprecated]  </i>
1460          * @deprecated     This method is deprecated because it is no longer necessary to handle the resizing of expandable edit area.
1461          * @since       2.0
1462          *
1463          * @return      An error code
1464          * @param[in]   enable                  Set to @c true to enable the auto resizing, @n
1465          *                                                                              else @c false
1466          * @exception   E_SUCCESS               The method is successful.
1467          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
1468          *                                      The current style of the %ExpandableEditArea does not support the operation.
1469          * @remarks     Note that when this option is enabled, the normal style %ExpandableEditArea is auto resized and the line added and removed events are
1470          *                              generated if the candidate word list pop-up appears during the predictive texting. @n
1471          *              The operation is not supported by the token style %ExpandableEditArea.
1472          * @see         IsAutoResizingEnabled()
1473          * @see         Tizen::Ui::Controls::IExpandableEditAreaEventListener
1474          * @endif
1475          */
1476         result SetAutoResizingEnabled(bool enable);
1477
1478         /**
1479          * @if OSPDEPREC
1480          * Checks whether the auto-resizing is enabled.
1481          *
1482          * @brief <i> [Deprecated]  </i>
1483          * @deprecated     This method is deprecated because it is no longer necessary to handle the resizing of expandable edit area.
1484          * @since       2.0
1485          *
1486          * @return      @c true if the auto-resizing is enabled, @n
1487          *                              else @c false
1488          * @exception   E_SUCCESS               The method is successful.
1489          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation. @n
1490          *                                                                              The current style of the %ExpandableEditArea control does not support the operation.
1491          * @remarks     The specific error code can be accessed using the GetLastResult() method.
1492          * @see         SetAutoResizingEnabled()
1493          * @endif
1494          */
1495         bool IsAutoResizingEnabled(void) const;
1496
1497         /**
1498         * Sets the input language. @n
1499         * The %SetCurrentLanguage() method only works if the language to set is supported by the current preloaded keypad.
1500         *
1501         * @since 2.0
1502         *
1503         * @brief <i> [Deprecated]  </i>
1504         * @deprecated We no longer provide a method to set the language of the current keypad. @n
1505         *                                        This method is provided only for backward compatibility and will be deleted in the near future.
1506         * @return     An error code
1507         * @param[in]  languageCode               The language to set
1508         * @exception  E_SUCCESS              The method is successful.
1509         * @exception  E_OUT_OF_MEMORY                   The memory is insufficient.
1510         * @remarks      The application can set the language of the current keypad that is associated with the current %ExpandableEditArea.
1511         */
1512         result SetCurrentLanguage(Tizen::Locales::LanguageCode languageCode);
1513
1514         /**
1515         * Gets the current input language.
1516         *
1517         * @since 2.0
1518         *
1519         * @return     An error code
1520         * @param[out] language               The current input language
1521         * @exception     E_SUCCESS                             The method is successful.
1522         * @remarks   The application can get the current language of the keypad that is associated with the current %ExpandableEditArea.
1523         */
1524         result GetCurrentLanguage(Tizen::Locales::LanguageCode& language) const;
1525
1526 // EVENT LISTENER MANAGEMENT
1527         /**
1528          * Adds the specified IExpandableEditAreaEventListener instance. @n
1529          * The added listener can listen to events when a line is added or removed or when a button is pressed.
1530          *
1531          * @since       2.0
1532          *
1533          * @param[in]   listener        The event listener to add
1534          * @see         RemoveExpandableEditAreaEventListener()
1535          */
1536         void AddExpandableEditAreaEventListener(IExpandableEditAreaEventListener& listener);
1537
1538         /**
1539          * Adds the specified IKeypadEventListener instance. @n
1540          * The added listener is notified if the keypad associated with the edit area is opened or closed.
1541          *
1542          * @since       2.0
1543          *
1544          * @param[in]   listener        The event listener to add
1545          * @see         RemoveKeypadEventListener()
1546          */
1547         void AddKeypadEventListener(Tizen::Ui::IKeypadEventListener& listener);
1548
1549         /**
1550          * Adds the specified ITextBlockEventListener instance.
1551          *
1552          * @since       2.0
1553          *
1554          * @param[in]   listener                The event listener to add
1555          * @remarks             Programmatically modifying the text block does not cause the text block selection event to fire.
1556          * @see         RemoveTextBlockEventListener()
1557          */
1558         void AddTextBlockEventListener(Tizen::Ui::ITextBlockEventListener& listener);
1559
1560         /**
1561         * Adds the specified ITextEventListener instance. @n
1562         * The added listener can listen to the text-changed event.
1563         *
1564         * @since       2.0
1565         *
1566         * @param[in]    listener                The listener to add
1567         * @see         RemoveTextEventListener()
1568         */
1569         void AddTextEventListener(Tizen::Ui::ITextEventListener& listener);
1570
1571         /**
1572          * Removes the specified IExpandableEditAreaEventListener instance. @n
1573          * The removed listener cannot listen to events when they are fired.
1574          *
1575          * @since       2.0
1576          *
1577          * @param[in]   listener                The event listener to remove
1578          * @see         AddActionEventListener()
1579          */
1580         void RemoveExpandableEditAreaEventListener(IExpandableEditAreaEventListener& listener);
1581
1582         /**
1583          * Removes the specified IKeypadEventListener listener. @n
1584          * The removed listener cannot listen to events when they are fired.
1585          *
1586          * @since       2.0
1587          *
1588          * @param[in]   listener                The event listener to remove
1589          * @see         AddKeypadEventListener()
1590          */
1591         void RemoveKeypadEventListener(Tizen::Ui::IKeypadEventListener& listener);
1592
1593         /**
1594          * Removes the specified ITextBlockEventListener listener. @n
1595          * The removed listener cannot listen to events when they are fired.
1596          *
1597          * @since       2.0
1598          *
1599          * @param[in]   listener                The event listener to remove
1600          * @see         AddTextBlockEventListener()
1601          */
1602         void RemoveTextBlockEventListener(Tizen::Ui::ITextBlockEventListener& listener);
1603
1604         /**
1605          * Removes the specified ITextEventListener instance. @n
1606          * The removed listener cannot listen to events when they are fired.
1607          *
1608          * @since       2.0
1609          *
1610          * @param[in]   listener                The listener to remove
1611          * @see         AddTextEventListener()
1612          */
1613         void RemoveTextEventListener(Tizen::Ui::ITextEventListener& listener);
1614
1615         /**
1616         * Adds a listener instance for language events. @n
1617         * The added listener is notified when the input language is changed.
1618         *
1619         * @since 2.0
1620         *
1621         * @param[in]  listener               The listener to add
1622         * @remarks    The application can recognize when the language is changed from the keypad by adding Tizen::Ui::ILanguageEventListener.
1623         * @see            RemoveLanguageEventListener()
1624         */
1625
1626         void AddLanguageEventListener(Tizen::Ui::ILanguageEventListener& listener);
1627
1628         /**
1629         * Removes the specified listener instance. @n
1630         * The removed listener cannot listen to events when they are fired.
1631         *
1632         * @since 2.0
1633         *
1634         * @param[in]  listener               The listener to remove
1635         * @see             AddLanguageEventListener()
1636         */
1637
1638         void RemoveLanguageEventListener(Tizen::Ui::ILanguageEventListener& listener);
1639
1640         /**
1641          * Enables or disables the auto shrinking if the focus is lost. @n
1642          * Note that when this option is enabled, the %ExpandableEditArea is auto shrinked if the %ExpandableEditArea lost its focus.
1643          *
1644          * @since 2.0
1645          *
1646          * @param[in]   enable                  Set to @c true to enable the auto shrinking, @n
1647          *                                                                              else @c false
1648          * @see         IsAutoShrinkModeEnabled()
1649          */
1650         void SetAutoShrinkModeEnabled(bool enable);
1651
1652         /**
1653          * Checks whether the auto-shrinking is enabled.
1654          *
1655          * @since 2.0
1656          *
1657          * @return      @c true if the auto-shrinking is enabled, @n
1658          *                              else @c false
1659          * @see         SetAutoShrinkModeEnabled()
1660          */
1661         bool IsAutoShrinkModeEnabled(void) const;
1662
1663         /**
1664          * Sets the text filter.
1665          *
1666          * @since               2.1
1667          *
1668          * @param[in]           pFilter The filter to set
1669          * @remarks     The %ExpandableEditArea control checks with the registered filter to decide whether the user-entered text should be replaced or not.
1670          */
1671         void  SetEditTextFilter(IEditTextFilter* pFilter);
1672
1673         /**
1674         * Sends opaque command to the input method.
1675         *
1676         * @since     2.1
1677         *
1678         * @param[in] command            The opaque command to send
1679         * @remarks
1680         *                       - This method can be used to provide domain-specific features that are only known between certain input methods and their clients.
1681         *                       - This method may not work, depending on the active Input Method.
1682         */
1683         void SendOpaqueCommand (const Tizen::Base::String& command);
1684
1685 protected:
1686         friend class _ExpandableEditAreaImpl;
1687
1688 private:
1689         //
1690         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
1691         //
1692         ExpandableEditArea(const ExpandableEditArea& rhs);
1693
1694         //
1695         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
1696         //
1697         ExpandableEditArea& operator =(const ExpandableEditArea& rhs);
1698 };      // ExpandableEditArea
1699
1700 }}} // Tizen::Ui::Controls
1701
1702 #endif      // _FUI_CTRL_EXPANDABLE_EDIT_AREA_H_