inc/FUiCtrlEditArea.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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        FUiCtrlEditArea.h
  20  * @brief       This is the header file for the %EditArea class.
  21  *
  22  * This header file contains the declarations of the %EditArea class and its helper classes.
  23  */
  24
  25 #ifndef _FUI_CTRL_EDIT_AREA_H_
  26 #define _FUI_CTRL_EDIT_AREA_H_
  27
  28 #include <FBaseString.h>
  29 #include <FBaseCharacter.h>
  30 #include <FGrpBitmap.h>
  31 #include <FGrpColor.h>
  32 #include <FGrpPoint.h>
  33 #include <FGrpRectangle.h>
  34 #include <FUiContainer.h>
  35 #include <FUiControl.h>
  36 #include <FUiCtrlControlsTypes.h>
  37 #include <FUiCtrlEditTypes.h>
  38 #include <FUiCtrlInputTypes.h>
  39 #include <FUiIActionEventListener.h>
  40 #include <FUiIKeypadEventListener.h>
  41 #include <FUiILanguageEventListener.h>
  42 #include <FUiIScrollPanelEventListener.h>
  43 #include <FUiITextBlockEventListener.h>
  44 #include <FUiITextEventListener.h>
  45 #include <FUiIUiLinkEventListener.h>
  46
  47 namespace Tizen { namespace Locales
  48 {
  49 class Locale;
  50 }} // Tizen::Locales
  51
  52 namespace Tizen { namespace Ui { namespace Controls
  53 {
  54
  55 /**
  56  * @class       EditArea
  57  * @brief       This class defines the common behavior for the %EditArea control.
  58  *
  59  * @since       2.0
  60  *
  61  * The %EditArea  class displays a multi-line text editor.
  62  *
  63  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/ui/implementing_editfield_editarea.htm">EditArea and EditField</a>.
  64  *
  65  * The following example demonstrates how to use the %EditArea class.
  66  *
  67  * @code
  68 // Sample code for EditAreaSample.h
  69 #include <FUi.h>
  70
  71 class EditAreaSample
  72         : public Tizen::Ui::Controls::Form
  73         , public Tizen::Ui::ITextEventListener
  74 {
  75 public:
  76         EditAreaSample(void)
  77         : __pEditArea(null){}
  78
  79         bool Initialize(void);
  80         virtual result OnInitializing(void);
  81
  82         // ITextEventListener
  83         virtual void OnTextValueChanged(const Tizen::Ui::Control& source);
  84         virtual void OnTextValueChangeCanceled(const Tizen::Ui::Control& source);
  85
  86 private:
  87         Tizen::Ui::Controls::EditArea* __pEditArea;
  88 };
  89  * @endcode
  90  *
  91  * @code
  92 // Sample code for EditAreaSample.cpp
  93 #include <FGraphics.h>
  94
  95 #include "EditAreaSample.h"
  96
  97 using namespace Tizen::Graphics;
  98 using namespace Tizen::Ui::Controls;
  99
 100 bool
 101 EditAreaSample::Initialize(void)
 102 {
 103         Construct(FORM_STYLE_NORMAL);
 104         return true;
 105 }
 106
 107 result
 108 EditAreaSample::OnInitializing(void)
 109 {
 110     result r = E_SUCCESS;
 111
 112         // Creates an instance of EditArea
 113         __pEditArea = new EditArea();
 114         __pEditArea->Construct(Rectangle(50, 100, 400, 150));
 115         __pEditArea->AddTextEventListener(*this);
 116
 117         // Adds the edit area to the form
 118         AddControl(*__pEditArea);
 119
 120         return r;
 121 }
 122
 123 // ITextEventListener implementation
 124 void
 125 EditAreaSample::OnTextValueChanged(const Tizen::Ui::Control& source)
 126 {
 127     // ....
 128 }
 129
 130 void
 131 EditAreaSample::OnTextValueChangeCanceled(const Tizen::Ui::Control& source)
 132 {
 133     // ....
 134 }
 135  * @endcode
 136  *
 137  */
 138 class _OSP_EXPORT_ EditArea
 139         : public Tizen::Ui::Control
 140 {
 141 // Lifecycle
 142 public:
 143         /**
 144          * The object is not fully constructed after this constructor is called. For full construction, the Construct() method must be called right after calling this constructor.
 145          *
 146          * @since               2.0
 147          */
 148         EditArea(void);
 149
 150         /**
 151          * This polymorphic destructor should be overridden if required. This way, the destructors of the derived classes are called when the destructor of this interface is called.
 152          *
 153          * @since               2.0
 154          */
 155         virtual ~EditArea(void);
 156
 157         /**
 158          * Initializes this instance of the %EditArea control with the specified parameters.
 159          *
 160          * @since                       2.0
 161          *
 162          * @return              An error code
 163          * @param[in]   rect            An instance of the Graphics::Rectangle class @n
 164          *                                  This instance represents the x and y coordinates of the top-left corner of the created window along with
 165          *                                  the width and height of the control.
 166          * @param[in]   inputStyle                      Determines whether the fullscreen keypad or overlay keypad is displayed
 167          * @param[in]   limitLength                     The maximum limit of the length of the text that can be displayed by %EditArea
 168          * @exception   E_SUCCESS                       The method is successful.
 169          * @exception   E_INVALID_ARG           A specified input parameter is invalid.@n
 170          *                                                                      The specified @c limitLength is less than or equal to @c 0. @n
 171          *                                                                      The @c rect.width or the @c rect.height is less than 0.
 172          * @exception   E_SYSTEM                        A system error has occurred.
 173          * @remarks             Some methods of the control will only work as expected when it becomes 'displayable'.
 174          *                              For more information, see Control::IsDisplayable() @n
 175          *                              The orientation of the full-screen style keypad is determined by the current device orientation.
 176          */
 177         result Construct(const Tizen::Graphics::Rectangle& rect, InputStyle inputStyle = INPUT_STYLE_FULLSCREEN, int limitLength = 1000);
 178
 179 public:
 180         /**
 181          * Gets the horizontal text alignment.
 182          *
 183          * @since               2.0
 184          *
 185          * @return              The horizontal text alignment
 186          * @exception   E_SUCCESS                       The method is successful.
 187          * @exception   E_SYSTEM                        A system error has occurred.
 188          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 189          * @see                 SetTextAlignment()
 190          */
 191         HorizontalAlignment GetTextAlignment(void) const;
 192
 193         /**
 194          * Sets the horizontal text alignment.
 195          *
 196          * @since               2.0
 197          *
 198          * @return              An error code
 199          * @param[in]   alignment           The horizontal text alignment
 200          * @exception   E_SUCCESS                       The method is successful.
 201          * @exception   E_SYSTEM                        A system error has occurred.
 202          * @see                 GetTextAlignment()
 203          */
 204         result SetTextAlignment(HorizontalAlignment alignment);
 205
 206         /**
 207          * Checks whether the view mode is enabled.
 208          *
 209          * @since               2.0
 210          *
 211          * @return              @c true if the view mode is enabled, @n
 212          *                              else @c false
 213          * @exception   E_SUCCESS                       The method is successful.
 214          * @exception   E_SYSTEM                        A system error has occurred.
 215          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 216          * @see                 SetViewModeEnabled()
 217          */
 218         bool IsViewModeEnabled(void) const;
 219
 220         /**
 221          * Enables or disables the view mode.
 222          *
 223          * @since               2.0
 224          *
 225          * @return              An error code
 226          * @param[in]   enable                          Set to @c true to enable the view mode, @n
 227          *                                                                      else @c false
 228          * @exception   E_SUCCESS                       The method is successful.
 229          * @exception   E_SYSTEM                        A system error has occurred.
 230          * @remarks             When the view mode is enabled, the auto-detected links will be displayed as linked text.
 231          * @see                 IsViewModeEnabled()
 232          */
 233         result SetViewModeEnabled(bool enable);
 234
 235         /**
 236          * Sets the auto-link mask.
 237          *
 238          * @since               2.0
 239          *
 240          * @return              An error code
 241          * @param[in]   autoLinks                               The auto-link mask @n
 242          *                                                                              Multiple link types can be combined using bitwise OR (see Tizen::Base::Utility::LinkType). @n
 243          *                                                                              For more information, see <a href="../org.tizen.native.appprogramming/html/guide/ui/auto_link_detection.htm">AutoLink Detection</a>.
 244          * @exception   E_SUCCESS                               The method is successful.
 245          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation.@n
 246          *                                                                              The operation is not supported if the input style is not INPUT_STYLE_OVERLAY.
 247          * @exception   E_SYSTEM                                A system error has occurred.
 248          * @remarks             When @c autoLinks is set to zero, the auto-link detection is disabled.
 249          * @see                 Tizen::Base::Utility::LinkType
 250          * @see                 GetAutoLinkMask()
 251          * @see                 IsViewModeEnabled()
 252          * @see                 SetViewModeEnabled()
 253          */
 254         result SetAutoLinkMask(unsigned long autoLinks);
 255
 256         /**
 257          * Gets the auto-link mask.
 258          *
 259          * @since               2.0
 260          *
 261          * @return              The auto-link mask
 262          * @exception   E_SUCCESS                               The method is successful.
 263          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation.@n
 264          *                                                                              This operation is not supported if the input style is not INPUT_STYLE_OVERLAY.
 265          * @exception   E_SYSTEM                                A system error has occurred.
 266          * @remarks             The specific error code can be accessed using the GetLastResult()() method.
 267          * @see                 SetAutoLinkMask()
 268          */
 269         unsigned long GetAutoLinkMask(void) const;
 270
 271         /**
 272          * Adds the specified link event listener.
 273          *
 274          * @since               2.0
 275          *
 276          * @param[in]   listener        The event listener to be added
 277          * @remarks             This method is supported when the input style is @c INPUT_STYLE_OVERLAY.@n
 278          *                              The added listener will be notified when the links are selected by the user.
 279          * @see                 RemoveUiLinkEventListener()
 280          */
 281         void AddUiLinkEventListener(Tizen::Ui::IUiLinkEventListener& listener);
 282
 283         /**
 284          * Removes the specified link event listener. @n
 285          * The removed listener cannot listen to the events when they are fired.
 286          *
 287          * @since               2.0
 288          *
 289          * @param[in]   listener        The event listener to be removed
 290          * @remarks             This method is supported when the input style is @c INPUT_STYLE_OVERLAY.
 291          * @see                 AddUiLinkEventListener()
 292          */
 293         void RemoveUiLinkEventListener(Tizen::Ui::IUiLinkEventListener& listener);
 294
 295         /**
 296          * Gets the line spacing.
 297          *
 298          * @since               2.0
 299          *
 300          * @return              The line spacing,  @n
 301          *                              else @c -1 if an error occurs
 302          * @exception   E_SUCCESS                       The method is successful.
 303          * @remarks             The specific error code can be accessed using the GetLastResult()() method.
 304          * @see         SetLineSpacing()
 305          */
 306         int GetLineSpacing(void) const;
 307
 308         /**
 309          * Sets the line spacing. @n
 310          * The line spacing is determined by multiplying @c multiplier to the default line spacing and adding @c extra.
 311          *
 312          * @code
 313          * The line spacing = (default line spacing) * multiplier + extra
 314          * @endcode
 315          * @since          2.0
 316          *
 317          * @return         An error code
 318          * @param[in]      multiplier           The line spacing multiplier
 319          * @param[in]      extra            The extra line spacing
 320          * @exception   E_SUCCESS               The method is successful.
 321          * @exception   E_INVALID_ARG   A specified input parameter is invalid, or @n
 322          *                                                              the specified line spacing value cannot be supported.
 323          * @exception   E_SYSTEM                A system error has occurred.
 324          * @see            GetLineSpacing()
 325          */
 326         result SetLineSpacing(int multiplier, int extra);
 327
 328         /**
 329          * Gets the margin value of the specified margin type.
 330          *
 331          * @since               2.0
 332          *
 333          * @return      The margin value, @n
 334          *              else @c -1 if an error occurs
 335          * @param[in]   marginType                      The margin type
 336          * @exception   E_SUCCESS                       The method is successful.
 337          * @exception   E_SYSTEM                        A system error has occurred.
 338          * @remarks             The specific error code can be accessed using the GetLastResult()() method.
 339          * @see         SetMargin()
 340          */
 341         int GetMargin(EditMarginType marginType) const;
 342
 343         /**
 344          * Sets the margin value for the specified margin type.
 345          *
 346          * @since               2.0
 347          *
 348          * @return      An error code
 349          * @param[in]   marginType              The margin type
 350          * @param[in]   margin                  The margin value to set
 351          * @exception   E_SUCCESS               The method is successful.
 352          * @exception   E_INVALID_ARG   A specified input parameter is invalid. @n
 353          *                                                              The specified @c margin cannot be a negative integer.
 354          * @exception   E_SYSTEM                A system error has occurred.
 355          * @see         GetMargin()
 356          */
 357         result SetMargin(EditMarginType marginType, int margin);
 358
 359         /**
 360          * Enables or disables the keypad action.
 361          *
 362          * @since 2.0
 363          * @return      An error code
 364          * @param[in]   enable  Set to @c true to enable the keypad action, @n
 365          *                                              else @c false
 366          * @exception   E_SUCCESS                               The method is successful.
 367          * @exception   E_UNSUPPORTED_OPERATION  The underlying input method does not support this operation.
 368          * @remarks     Depending on the value of input param, the enter key have a enable or disable look accordingly.
 369          */
 370         result SetKeypadActionEnabled(bool enable);
 371
 372         /**
 373          * Checks whether the keypad action is enabled.
 374          *
 375          * @since 2.0
 376          * @return              @c true if the keypad action is enabled, @n
 377          *                              else @c false
 378          */
 379         bool IsKeypadActionEnabled(void) const;
 380
 381         /**
 382          * Gets the keypad action type.
 383          *
 384          * @since               2.0
 385          *
 386          * @return      The keypad action
 387          * @exception   E_SUCCESS               The method is successful.
 388          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation.@n
 389          *                                                                              This operation is not supported if the input style is not INPUT_STYLE_OVERLAY.
 390          * @exception   E_SYSTEM                A system error has occurred.
 391          * @remarks     The specific error code can be accessed using the GetLastResult()() method.
 392          */
 393         Tizen::Ui::KeypadAction GetKeypadAction(void) const;
 394
 395         /**
 396          * Sets the keypad action type.
 397          *
 398          * @since               2.0
 399          *
 400          * @return      An error code
 401          * @param[in]   keypadAction                    The keypad action
 402          * @exception   E_SUCCESS                               The method is successful.
 403          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation.@n
 404          *                                                                              This operation is not supported if the input style is not INPUT_STYLE_OVERLAY.
 405          * @exception   E_SYSTEM                                A system error has occurred.
 406          * @remarks     Depending on the value of @c keypadAction specified, the enter key label of the keypad will change accordingly.
 407          */
 408         result SetKeypadAction(Tizen::Ui::KeypadAction keypadAction);
 409
 410         /**
 411          * Gets the keypad style.
 412          *
 413          * @since               2.0
 414          *
 415          * @return              The keypad style
 416          * @exception   E_SUCCESS                       The method is successful.
 417          * @exception   E_SYSTEM            A system error has occurred.
 418          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 419          * @see         SetKeypadStyle()
 420          */
 421         KeypadStyle GetKeypadStyle(void) const;
 422
 423         /**
 424          * Sets the keypad style.
 425          *
 426          * @since               2.0
 427          *
 428          * @return      An error code
 429          * @param[in]   keypadStyle                     The keypad style
 430          * @exception   E_SUCCESS                       The method is successful.
 431          * @exception   E_INVALID_ARG           The specified input parameter is invalid. @n
 432          *                                  The specified @c keypadStyle cannot be @c KEYPAD_STYLE_PASSWORD.
 433          * @exception   E_SYSTEM            A system error has occurred.
 434          * @remarks     Depending on the value of the specified @c keypadStyle, the keypad's layout will change accordingly.
 435          * @see         GetKeypadStyle()
 436          */
 437         result SetKeypadStyle(KeypadStyle keypadStyle);
 438
 439         /**
 440          * Checks whether the text prediction is enabled.
 441          *
 442          * @since 2.0
 443          * @return                @c true if the text prediction is enabled, @n
 444          *                                 else @c false
 445          * @exception          E_SUCCESS                The method is successful.
 446          * @see                      SetTextPredictionEnabled()
 447          */
 448         bool IsTextPredictionEnabled(void) const;
 449
 450         /**
 451          * Enables or disables the text prediction.
 452          *
 453          * @since 2.0
 454          * @param[in]           enable                       Set to @c true to enable the text prediction, @n
 455          *                                                                    else @c false
 456          * @return                An error code
 457          * @exception           E_SUCCESS                The method is successful.
 458          * @exception           E_UNSUPPORTED_OPERATION     This operation is not supported.
 459          * @see                      IsTextPredictionEnabled()
 460          */
 461         result SetTextPredictionEnabled(bool enable);
 462
 463         /**
 464          * Sets the visibility of the command buttons of the overlay style keypad.
 465          *
 466          * @since               2.0
 467          *
 468          * @return              An error code
 469          * @param[in]   visible                                 Set to @c true to make the overlay keypad command buttons visible, @n
 470          *                                                                              else @c false
 471          * @exception   E_SUCCESS                               The method is successful.
 472          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation.@n
 473          *                                                                              This operation is not supported if the input style is not INPUT_STYLE_OVERLAY.
 474          * @exception   E_SYSTEM                                A system error has occurred.
 475          */
 476         result SetOverlayKeypadCommandButtonVisible(bool visible);
 477
 478         /**
 479          * Checks whether the command buttons of the overlay style keypad are visible.
 480          *
 481          * @since       2.0
 482          *
 483          * @return      @c true if the overlay command buttons are set to be visible, @n
 484          *              else @c false
 485          * @exception   E_SUCCESS               The method is successful.
 486          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation.@n
 487          *                                                                              This operation is not supported if the input style is not INPUT_STYLE_OVERLAY.
 488          * @exception   E_SYSTEM                A system error has occurred.
 489          * @remarks     The specific error code can be accessed using the GetLastResult()() method.
 490          */
 491         bool IsOverlayCommandButtonVisible(void) const;
 492
 493         /**
 494          * Hides the keypad.
 495          *
 496          * @since       2.0
 497          *
 498          * @return      An error code
 499          * @exception   E_SUCCESS                               The method is successful.
 500          * @exception   E_UNSUPPORTED_OPERATION The current state of the instance prohibits the execution of the specified operation.@n
 501          *                                                                              This operation is not supported if the input style is not INPUT_STYLE_OVERLAY.
 502          * @exception   E_SYSTEM                                A system error has occurred.
 503          * @see         ShowKeypad()
 504          */
 505         result HideKeypad(void);
 506
 507         /**
 508          * Gets the text size.
 509          *
 510          * @since       2.0
 511          *
 512          * @return      The size of the text, @n
 513          *              else @c -1 if an error occurs
 514          * @exception   E_SUCCESS                       The method is successful.
 515          * @exception   E_SYSTEM                        A system error has occurred.
 516          * @remarks     The specific error code can be accessed using the GetLastResult() method.
 517          * @see         SetTextSize()
 518          */
 519         int GetTextSize(void) const;
 520
 521         /**
 522          * Sets the text size.
 523          *
 524          * @since               2.0
 525          *
 526          * @return              An error code
 527          * @param[in]   size                    The text size
 528          * @exception   E_SUCCESS               The method is successful.
 529          * @exception   E_INVALID_ARG   The specified input parameter is invalid. @n
 530          *                                                              The specified @c size cannot be a negative integer.
 531          * @exception   E_SYSTEM                A system error has occurred.
 532          * @see                 GetTextSize()
 533          */
 534         result SetTextSize(int size);
 535
 536         /**
 537          * Gets the color of %EditArea for the specified status.
 538          *
 539          * @since        2.0
 540          *
 541          * @return       The color, @n
 542          *                               else RGBA (0,0,0,0) if an error occurs
 543          * @param[in]    status                         The status
 544          * @exception    E_SUCCESS                      The method is successful.
 545          * @exception    E_SYSTEM                       A system error has occurred.
 546          * @remarks      The specific error code can be accessed using the GetLastResult() method.
 547          */
 548         Tizen::Graphics::Color GetColor(EditStatus status) const;
 549
 550         /**
 551          * Gets the text color of the specified text color type.
 552          *
 553          * @since               2.0
 554          *
 555          * @return              The color, @n
 556          *                              else RGBA (0,0,0,0) if an error occurs
 557          * @param[in]   type                    The text color type
 558          * @exception   E_SUCCESS               The method is successful.
 559          * @exception   E_SYSTEM                A system error has occurred.
 560          * @remarks             The specific error code can be accessed using the GetLastResult() method.
 561          * @see                 SetTextColor()
 562          */
 563         Tizen::Graphics::Color GetTextColor(EditTextColor type) const;
 564
 565         /**
 566          * Sets the background bitmap of the %EditArea control for the specified status.
 567          *
 568          * @since               2.0
 569          *
 570          * @return              An error code
 571          * @param[in]   status                  The status
 572          * @param[in]   bitmap                  The background bitmap
 573          * @exception   E_SUCCESS               The method is successful.
 574          * @exception   E_SYSTEM                A system error has occurred.
 575          */
 576         result SetBackgroundBitmap(EditStatus status, const Tizen::Graphics::Bitmap& bitmap);
 577
 578         /**
 579          * Sets the color of the %EditArea control for the specified status.
 580          *
 581          * @since               2.0
 582          *
 583          * @return              An error code
 584          * @param[in]   status                  The status
 585          * @param[in]   color                   The color
 586          * @exception   E_SUCCESS               The method is successful.
 587          * @exception   E_SYSTEM                A system error has occurred.
 588          * @see                 GetColor()
 589          */
 590         result SetColor(EditStatus status, const Tizen::Graphics::Color& color);
 591
 592         /**
 593          * Sets the text color of the %EditArea control for the specified text color type.
 594          *
 595          * @since               2.0
 596          *
 597          * @return              An error code
 598          * @param[in]   type                    The text color type
 599          * @param[in]   color                   The text color
 600          * @exception   E_SUCCESS               The method is successful.
 601          * @exception   E_SYSTEM                A system error has occurred.
 602          * @see                 GetTextColor()
 603          */
 604         result SetTextColor(EditTextColor type, const Tizen::Graphics::Color& color);
 605
 606         /**
 607          * Gets a portion of text that is displayed by the %EditArea control.
 608          *
 609          * @since               2.0
 610          *
 611          * @return      The specified portion of the text, @n
 612          *                              else an empty string if an error occurs
 613          * @param[in]   start                   The starting index of the range
 614          * @param[in]   end                             The last index of the range
 615          * @exception   E_SUCCESS               The method is successful.
 616          * @exception   E_OUT_OF_RANGE  The specified index is outside the bounds of the data structure. @n
 617          *                                                              The index is greater than the number of elements or less than @c 0.
 618          * @exception   E_SYSTEM                A system error has occurred.
 619          * @remarks     The specific error code can be accessed using the GetLastResult()() method.
 620          * @see         SetText()
 621          */
 622         Tizen::Base::String GetText(int start, int end) const;
 623
 624         /**
 625          * Adds the specified keypad event listener. @n
 626          * The added listener is notified when the keypad associated with the %EditArea control is opened or closed.
 627          *
 628          * @since       2.0
 629          *
 630          * @param[in]   listener        The event listener to be added
 631          * @see         RemoveKeypadEventListener()
 632          */
 633         void AddKeypadEventListener(Tizen::Ui::IKeypadEventListener& listener);
 634
 635         /**
 636          * Removes the specified keypad event listener. @n
 637          * The removed listener cannot listen to events when they are fired.
 638          *
 639          * @since       2.0
 640          *
 641          * @param[in]   listener        The event listener to be removed
 642          * @see         AddKeypadEventListener()
 643          */
 644         void RemoveKeypadEventListener(Tizen::Ui::IKeypadEventListener& listener);
 645
 646         /**
 647          * Adds a text block event listener.
 648          * The added listener is notified when the text block is selected.
 649          *
 650          * @since               2.0
 651          *
 652          * @param[in]   listener        The event listener to be added
 653          * @remarks             Programmatically modifying the text block does not cause the text block selection event to fire.
 654          * @see                 RemoveTextBlockEventListener()
 655          */
 656         void AddTextBlockEventListener(Tizen::Ui::ITextBlockEventListener& listener);
 657
 658         /**
 659          * Removes the specified text block event listener. @n
 660          * The removed listener cannot listen to events when they are fired.
 661          *
 662          * @since               2.0
 663          *
 664          * @param[in]   listener        The event listener to be removed
 665          * @see         AddTextBlockEventListener()
 666          */
 667         void RemoveTextBlockEventListener(Tizen::Ui::ITextBlockEventListener& listener);
 668
 669         /**
 670          * Adds a listener instance. @n
 671          * The added listener can listen to the text related events.
 672          *
 673          * @since               2.0
 674          *
 675          * @param[in]   listener    The listener to be added
 676          * @see                 RemoveTextEventListener()
 677          */
 678         void AddTextEventListener(Tizen::Ui::ITextEventListener& listener);
 679
 680         /**
 681          * Removes a listener instance. @n
 682          * The removed listener cannot listen to events when they are fired.
 683          *
 684          * @since               2.0
 685          *
 686          * @param[in]   listener    The listener to be removed
 687          * @see                 AddTextEventListener()
 688          */
 689         void RemoveTextEventListener(Tizen::Ui::ITextEventListener& listener);
 690
 691         /**
 692          * Adds a listener instance to listen to the scroll panel events.
 693          *
 694          * @since               2.0
 695          *
 696          * @param[in]   listener    The listener to be added
 697          * @remarks     To listen to scroll panel events, the parent of the %EditArea control must be an instance of ScrollPanel. @n
 698          *              When OnOverlayControlCreated() or OnOvelayControlClosed() is called, the application resets the bounds of the controls placed
 699          *              within the %ScrollPanel. %ScrollPanel is automatically redrawn after this method is called.
 700          * @see                 RemoveScrollPanelEventListener()
 701          */
 702         void AddScrollPanelEventListener(Tizen::Ui::IScrollPanelEventListener& listener);
 703
 704         /**
 705          * Removes the scroll panel event listener. @n
 706          * The removed listener cannot listen to events when they are fired.
 707          *
 708          * @since               2.0
 709          *
 710          * @param[in]   listener    The listener to be removed
 711          * @see                 AddScrollPanelEventListener()
 712          */
 713         void RemoveScrollPanelEventListener(Tizen::Ui::IScrollPanelEventListener& listener);
 714
 715         /**
 716          * Adds a listener instance. @n
 717          * The added listener is notified when the action event is fire by the command buttons of the keypad.
 718          *
 719          * @since               2.0
 720          *
 721          * @param[in]   listener        The event listener to be added
 722          * @see                 RemoveActionEventListener()
 723          */
 724         void AddActionEventListener(Tizen::Ui::IActionEventListener& listener);
 725
 726
 727         /**
 728          * Removes a listener instance. @n
 729          * The removed listener cannot listen to events when they are fired.
 730          *
 731          * @since               2.0
 732          *
 733          * @param[in]   listener    The event listener to be removed
 734          * @see                 AddActionEventListener()
 735          */
 736         void RemoveActionEventListener(Tizen::Ui::IActionEventListener& listener);
 737
 738         /**
 739          * Adds a listener instance for language events. @n
 740          * The added listener is notified when the input language is changed.
 741          *
 742          * @since      2.0
 743          *
 744          * @param[in]  listener               The listener to be added
 745          * @remarks    The application can recognize when the language is changed from the keypad by adding Tizen::Ui::ILanguageEventListener.
 746          * @see            RemoveLanguageEventListener()
 747          */
 748         void AddLanguageEventListener(Tizen::Ui::ILanguageEventListener& listener);
 749
 750         /**
 751          * Removes the specified listener instance. @n
 752          * The removed listener cannot listen to events when they are fired.
 753          *
 754          * @since      2.0
 755          *
 756          * @param[in]  listener               The listener to be removed
 757          * @see             AddLanguageEventListener()
 758          */
 759         void RemoveLanguageEventListener(Tizen::Ui::ILanguageEventListener& listener);
 760
 761         /**
 762          * Gets the remaining length of the %EditArea control.
 763          *
 764          * @since       2.0
 765          *
 766          * @return      The remaining length of the %EditArea control, @n
 767          *                      else @c -1 if an error occurs.
 768          */
 769         int GetRemainingLength(void) const;
 770
 771         /**
 772          * Enables or disables the lowercase mode.
 773          *
 774          * @since               2.0
 775          *
 776          * @param[in]   enable  Set to @c true to enable the lowercase mode, @n
 777          *                                              else @c false
 778          */
 779         void SetLowerCaseModeEnabled(bool enable);
 780
 781         /**
 782          * Checks whether the lowercase mode is enabled.
 783          *
 784          * @since       2.0
 785          *
 786          * @return      @c true if the lowercase mode is enabled, @n
 787          *                      else @c false
 788          */
 789         bool IsLowerCaseModeEnabled(void) const;
 790
 791         /**
 792          * @if OSPDEPREC
 793          * Sets the input mode category.
 794          *
 795          * @brief <i> [Deprecated]  </i>
 796          * @deprecated We no longer provide a method to specify the list of styles which the user can set the keypad to, @n
 797          *                         or the current mode to initially set the keypad to, from this list. It is recommended to use SetKeypadStyle() method instead.
 798          * @since        2.0
 799          *
 800          * @return       An error code
 801          * @param[in]    categories     The categories to be set @n
 802          *                                      Multiple input categories can be combined using bitwise OR (see Tizen::Ui::Controls::EditInputModeCategory).
 803          * @param[in]    enable                 The category value to be set
 804          * @exception    E_SUCCESS                              The method is successful.
 805          * @exception    E_INVALID_ARG                  A specified input mode category is invalid.
 806          * @exception    E_INVALID_OPERATION    The current state of the instance prohibits the execution of the specified operation @n
 807          *                                                                              The specified @c categories cannot be supported with the current keypad style.
 808          * @exception    E_SYSTEM                               A system error has occurred.
 809          * @endif
 810          */
 811         result SetInputModeCategory(unsigned long categories, bool enable);
 812
 813         /**
 814          * @if OSPDEPREC
 815          * Sets the current input mode category.
 816          *
 817          * @brief <i> [Deprecated]  </i>
 818          * @deprecated We no longer provide a method to specify the list of styles which the user can set the keypad to, @n
 819          *                         or the current mode to initially set the keypad to, from this list. It is recommended to use SetKeypadStyle() method instead.
 820          * @since               2.0
 821          *
 822          * @return              An error code
 823          * @param[in]   inputModeCategory   An item of input category
 824          * @exception   E_SUCCESS                       The method is successful.
 825          * @exception   E_SYSTEM                        A system error has occurred.
 826          * @endif
 827          */
 828         result SetCurrentInputModeCategory(EditInputModeCategory inputModeCategory);
 829
 830         /**
 831          * @if OSPDEPREC
 832          * Gets the input mode category.
 833          *
 834          * @brief <i> [Deprecated]  </i>
 835          * @deprecated This method is deprecated because we no longer provide a method to specify the list of styles @n
 836          *                        which the user can set the keypad to. It is recommended to use GetKeypadStyle() method instead.
 837          * @since       2.0
 838          *
 839          * @return  A bitwise combination of Tizen::Ui::Controls::EditInputModeCategory, @n
 840          *                      else @c EDIT_INPUTMODE_ALPHA if an error occurs
 841          * @endif
 842          */
 843         unsigned long GetInputModeCategory(void) const;
 844
 845         /**
 846          * @if OSPDEPREC
 847          * Gets the current input mode category.
 848          *
 849          * @brief <i> [Deprecated]  </i>
 850          * @deprecated This method is deprecated because we no longer provide a method to specify the list of styles @n
 851          *                        which the user can set the keypad to. It is recommended to use GetKeypadStyle() method instead.
 852          * @since    2.0
 853          *
 854          * @return   The current input mode category
 855          * @endif
 856          */
 857         EditInputModeCategory GetCurrentInputModeCategory(void) const;
 858
 859         /**
 860          * Sets the cursor at the specified position.
 861          *
 862          * @since               2.0
 863          *
 864          * @return              An error code
 865          * @param[in]   position        The cursor position that is to be set
 866          * @exception   E_SUCCESS               The method is successful.
 867          * @exception   E_OUT_OF_RANGE  The specified @c position is less than @c 0 or greater than the maximum length.
 868          * @exception   E_SYSTEM                A system error has occurred.
 869          */
 870         result SetCursorPosition(int position);
 871
 872         /**
 873          * Gets the cursor position.
 874          *
 875          * @since                       2.0
 876          *
 877          * @return                      The current cursor position, @n
 878          *                  else @c -1 if an error occurs
 879          */
 880         int GetCursorPosition(void) const;
 881
 882         /**
 883          * Gets the text that is displayed by the %EditArea control.
 884          *
 885          * @since       2.0
 886          *
 887          * @return      The text of the %EditArea control, @n
 888          *          else an empty string if an error occurs
 889          */
 890         Tizen::Base::String GetText(void) const;
 891
 892         /**
 893          * Gets the length of the text that is displayed by the %EditArea control.
 894          *
 895          * @since       2.0
 896          *
 897          * @return      The length of the text, @n
 898          *          else @c -1 if an error occurs
 899          */
 900         int GetTextLength(void) const;
 901
 902         /**
 903          * Sets the text of the %EditArea control.
 904          *
 905          * @since               2.0
 906          *
 907          * @param[in]   text                    The text that needs to be displayed by the %EditArea control.
 908          * @exception   E_SUCCESS               The method is successful.
 909          * @exception   E_INVALID_ARG   The specified input parameter is invalid. @n
 910          *                                                              The length of the specified @c text exceeds the system limitation or the limit length.
 911          * @exception   E_SYSTEM                A system error has occurred.
 912          * @remarks     Use @htmlonly '\n' @endhtmlonly to denote the end of the line.
 913          */
 914         result SetText(const Tizen::Base::String& text);
 915
 916         /**
 917          * Inserts the specified text at the current cursor position.
 918          *
 919          * @since               2.0
 920          *
 921          * @return              An error code
 922          * @param[in]   text        The text to be inserted
 923          * @exception   E_SUCCESS       The method is successful.
 924          * @exception   E_SYSTEM        A system error has occurred.
 925          * @remarks     Use @htmlonly '\n' @endhtmlonly to denote the end of the line.@n
 926          */
 927         result InsertTextAtCursorPosition(const Tizen::Base::String& text);
 928
 929         /**
 930          * Appends the specified text at the end of the existing text.
 931          *
 932          * @since               2.0
 933          *
 934          * @return              An error code
 935          * @param[in]   text            The text to be appended
 936          * @exception   E_SUCCESS       The method is successful.
 937          * @exception   E_SYSTEM        A system error has occurred.
 938          * @remarks     Use @htmlonly '\n' @endhtmlonly to denote the end of the line.@n
 939          */
 940         result AppendText(const Tizen::Base::String& text);
 941
 942         /**
 943          * Appends the specified character at the end of the existing text.
 944          *
 945          * @since               2.0
 946          *
 947          * @return      An error code
 948          * @param[in]   character       The character to be appended
 949          * @exception   E_SUCCESS       The method is successful.
 950          * @exception   E_SYSTEM        A system error has occurred.
 951          * @remarks             The method modifies the text buffer that is managed by the %EditArea control. To display the
 952          *              changes, the control must be drawn again.
 953          */
 954         result AppendCharacter(const Tizen::Base::Character& character);
 955
 956         /**
 957          * Inserts the text that will be displayed by bitmap at the specified text position.
 958          *
 959          * @since 2.0
 960          *
 961          * @return             An error code
 962          * @param[in]   position       The position to insert the text
 963          * @param[in]   text            The text to be inserted
 964          * @param[in]   textImage    The alternate bitmap to be drawn
 965          * @exception   E_SUCCESS        The method is successful.
 966          * @exception   E_OUT_OF_RANGE  The specified @c position is outside the valid range. @n
 967          *                              Either the specified @c position is greater than the number of existing text in the %EditArea or less than @c 0.
 968          * @exception   E_MAX_EXCEEDED  The length of the specified @c text exceeds the maximum length of the text that can be displayed by %EditArea.
 969          * @remarks                 The method modifies the text buffer that is managed by the %EditArea control. @n
 970          *              To display the changes, the control must be drawn again. The text to be inserted will be displayed by @c textImage.
 971          */
 972         result InsertTextAt(int position, const Tizen::Base::String& text, const Tizen::Graphics::Bitmap& textImage);
 973
 974         /**
 975          * Appends the text that will be displayed by bitmap at the end of the existing text.
 976          *
 977          * @since 2.0
 978          *
 979          * @return             An error code
 980          * @param[in]   text            The text to be appended
 981          * @param[in]   textImage    The alternate bitmap to be drawn
 982          * @exception   E_SUCCESS        The method is successful.
 983          * @exception   E_MAX_EXCEEDED  The length of the specified @c text exceeds the maximum length of the text that can be displayed by %EditArea.
 984          * @remarks                 The method modifies the text buffer that is managed by the %EditArea control. @n
 985          *              To display the changes, the control must be drawn again. The text to be appended will be displayed by @c textImage.
 986          */
 987         result AppendText(const Tizen::Base::String& text, const Tizen::Graphics::Bitmap& textImage);
 988
 989         /**
 990          * Clears the text that is displayed by the %EditArea control.
 991          *
 992          * @since               2.0
 993          *
 994          * @return              An error code
 995          * @exception   E_SUCCESS   The method is successful.
 996          * @exception   E_SYSTEM    A system error has occurred.
 997          * @remarks             The method modifies the text buffer that is managed by the %EditArea control. To display the
 998          *              changes, the control must be drawn again.
 999          */
1000         result Clear(void);
1001
1002         /**
1003          * Deletes a character at the current cursor position.
1004          *
1005          * @since               2.0
1006          *
1007          * @return              An error code
1008          * @exception   E_SUCCESS       The method is successful.
1009          * @exception   E_SYSTEM        A system error has occurred.
1010          * @remarks             The method modifies the text buffer that is managed by the %EditArea control. To display the
1011          *              changes, the control must be drawn again.
1012          */
1013         result DeleteCharacterAtCursorPosition(void);
1014
1015         /**
1016          * Gets the range of the current text block.
1017          *
1018          * @since        2.0
1019          *
1020          * @param[out]   start   The first index of the current text block
1021          * @param[out]   end     The last index of the current text block
1022          */
1023         void GetCurrentTextRange(int& start, int& end) const;
1024
1025         /**
1026          * Displays the guide text when there is no text in the %EditArea control.
1027          *
1028          * @since               2.0
1029          *
1030          * @param[in]   guideText    The guide text
1031          * @remarks             This is the default text that is displayed in the %EditArea control when the focus is given to it.
1032          */
1033         void SetGuideText(const Tizen::Base::String& guideText);
1034
1035         /**
1036          * Gets the guide text.
1037          *
1038          * @since       2.0
1039          *
1040          * @return      The guide text, @n
1041          *              else an empty string if an error occurs
1042          * @exception   E_SUCCESS                       The method is successful.
1043          * @exception   E_SYSTEM                        A system error has occurred.
1044          * @remarks             The specific error code can be accessed using the GetLastResult() method.
1045          * @see         SetGuideText()
1046          */
1047         Tizen::Base::String GetGuideText(void) const;
1048
1049         /**
1050          * Gets the text color of the guide text.
1051          *
1052          * @since       2.0
1053          *
1054          * @return      The guide text color
1055          * @exception   E_SUCCESS        The method is successful.
1056          * @exception   E_SYSTEM         A system error has occurred.
1057          * @remarks     The specific error code can be accessed using the GetLastResult() method.
1058          * @see         SetGuideTextColor()
1059          */
1060         Tizen::Graphics::Color GetGuideTextColor(void) const;
1061
1062         /**
1063          * Sets the text color of the guide text.
1064          *
1065          * @since       2.0
1066          *
1067          * @return      An error code
1068          * @param[in]   color            The guide text color
1069          * @exception   E_SUCCESS        The method is successful.
1070          * @exception   E_SYSTEM         A system error has occurred.
1071          * @see         GetGuideTextColor()
1072          */
1073         result SetGuideTextColor(const Tizen::Graphics::Color& color);
1074
1075         /**
1076          * Enables or disables the keypad.
1077          *
1078          * @since               2.0
1079          *
1080          * @param[in]   enable  Set to @c true to enable the keypad, @n
1081          *                                              else @c false
1082          */
1083         void SetKeypadEnabled(bool enable);
1084
1085         /**
1086          * Checks whether the keypad is enabled.
1087          *
1088          * @since        2.0
1089          *
1090          * @return              @c true if the keypad is enabled, @n
1091          *                              else @c false
1092          */
1093         bool IsKeypadEnabled(void) const;
1094
1095         /**
1096          * Shows the keypad.
1097          *
1098          * @since               2.0
1099          *
1100          * @return              An error code
1101          * @exception   E_SUCCESS       The method is successful.
1102          * @exception   E_INVALID_STATE This instance is in an invalid state.
1103          * @exception   E_SYSTEM                A system error has occurred.
1104          * @remarks             This method is supported only when the input style is INPUT_STYLE_OVERLAY.
1105          */
1106         result ShowKeypad(void);
1107
1108         /**
1109          * Gets the line count.
1110          *
1111          * @since       2.0
1112          *
1113          * @return      The line count
1114          */
1115         int GetTextLineCount(void) const;
1116
1117         /**
1118          * Gets the range of the current text block.
1119          *
1120          * @since               2.0
1121          *
1122          * @param[out]  start   The starting index of the current text block
1123          * @param[out]  end     The end index of the current text block
1124          */
1125         void GetBlockRange(int& start, int& end) const;
1126
1127         /**
1128          * Begins the text block from the current cursor position.
1129          *
1130          * @since               2.0
1131          *
1132          * @return              An error code
1133          * @exception   E_SUCCESS       The method is successful.
1134          * @exception   E_SYSTEM        A system error has occurred.
1135          * @remarks             Move the cursor position to the end of the text block.
1136          * @see         SetCursorPosition()
1137          * @see         ReleaseBlock()
1138          * @see                 IsBlocked()
1139          */
1140         result BeginBlock(void);
1141
1142         /**
1143          * Releases the text block.
1144          *
1145          * @since               2.0
1146          *
1147          * @return              An error code
1148          * @exception   E_SUCCESS               The method is successful.
1149          * @exception   E_SYSTEM                A system error has occurred.
1150          * @see         BeginBlock()
1151          * @see                 IsBlocked()
1152          */
1153         result ReleaseBlock(void);
1154
1155         /**
1156          * Checks whether a portion of the text is blocked.
1157          *
1158          * @since       2.0
1159          *
1160          * @return      @c true if the text is blocked, @n
1161          *                      else @c false
1162          * @see     BeginBlock()
1163          * @see         ReleaseBlock()
1164          */
1165         bool IsBlocked(void) const;
1166
1167         /**
1168          * Copies the text block to the clipboard.
1169          *
1170          * @since               2.0
1171          *
1172          * @return              An error code
1173          * @exception   E_SUCCESS               The method is successful.
1174          * @exception   E_SYSTEM                A system error has occurred.
1175          * @see         Cut(), Paste(), Remove()
1176          */
1177         result Copy(void);
1178
1179         /**
1180          * Cuts the text block and copies it to the clipboard.
1181          *
1182          * @since               2.0
1183          *
1184          * @return              An error code
1185          * @exception   E_SUCCESS               The method is successful.
1186          * @exception   E_SYSTEM                A system error has occurred.
1187          * @see                 Copy(), Remove(), Paste()
1188          */
1189         result Cut(void);
1190
1191         /**
1192          * Pastes the copied text at the cursor position.
1193          *
1194          * @since               2.0
1195          *
1196          * @return              An error code
1197          * @exception   E_SUCCESS               The method is successful.
1198          * @exception   E_SYSTEM                A system error has occurred.
1199          * @see                 Copy(), Cut(), Remove()
1200          */
1201         result Paste(void);
1202
1203         /**
1204          * Removes the text that is marked by the text block.
1205          *
1206          * @since               2.0
1207          *
1208          * @return              An error code
1209          * @exception   E_SUCCESS               The method is successful.
1210          * @exception   E_SYSTEM                A system error has occurred.
1211          * @see                 Copy(), Cut(), Paste()
1212          */
1213         result Remove(void);
1214
1215         /**
1216          * Checks whether the text in the %EditArea control has been clipped.
1217          *
1218          * @since       2.0
1219          *
1220          * @return      @c true if the text has been clipped, @n
1221          *                      else @c false
1222          * @remarks     'Clipped' means that the text has been copied to the clipboard.
1223          * @see         Copy(), Cut(), Paste(), Remove()
1224          */
1225         bool IsClipped(void) const;
1226
1227         /**
1228          * Sets the command button properties of the keypad.
1229          *
1230          * @since       2.0
1231          *
1232          * @return              An error code
1233          * @param[in]   position                        The position of the command button
1234          * @param[in]   text                            The label of the command button
1235          * @param[in]   actionId                        The action ID
1236          * @exception   E_SUCCESS           The method is successful.
1237          * @exception   E_SYSTEM            A system error has occurred.
1238          * @remarks             This method is supported when the input style is @c INPUT_STYLE_OVERLAY.
1239          */
1240         result SetOverlayKeypadCommandButton(CommandButtonPosition position, const Tizen::Base::String& text, int actionId);
1241
1242         /**
1243          * Gets the text of the specified command button.
1244          *
1245          * @since               2.0
1246          *
1247          * @return              The text of the specified command button
1248          * @param[in]   position    The position of the command button
1249          * @remarks             This method is supported when the input style is @c INPUT_STYLE_OVERLAY.
1250          */
1251         Tizen::Base::String GetOverlayKeypadCommandButtonText(CommandButtonPosition position) const;
1252
1253         /**
1254          * Gets the action ID of the specified command button.
1255          *
1256          * @since               2.0
1257          *
1258          * @return              The action ID of the specified command button
1259          * @param[in]   position    The position of the command button
1260          * @remarks             This method is supported when the input style is @c INPUT_STYLE_OVERLAY.
1261          */
1262         int GetOverlayKeypadCommandButtonActionId(CommandButtonPosition position) const;
1263
1264         /**
1265          * Sets the input language.
1266          *
1267          * @since      2.0
1268          *
1269          * @return     An error code
1270          * @param[in]  languageCode               The language to be set
1271          * @exception  E_SUCCESS              The method is successful.
1272          * @exception  E_OUT_OF_MEMORY   The memory is insufficient.
1273          * @remarks    The application can set the language of the current keypad that is associated with the current %EditArea. @n
1274          *             This method only works if the language to set is supported by the current preloaded keypad.
1275          */
1276         result SetCurrentLanguage(Tizen::Locales::LanguageCode languageCode);
1277
1278         /**
1279          * Gets the current input language.
1280          *
1281          * @since      2.0
1282          *
1283          * @return     An error code
1284          * @param[out] language               The current input language
1285          * @exception   E_SUCCESS                       The method is successful.
1286          * @remarks   The application can get the current language of the keypad that is associated with the current %EditArea.
1287          */
1288         result GetCurrentLanguage(Tizen::Locales::LanguageCode& language) const;
1289
1290 protected:
1291         friend class _EditAreaImpl;
1292
1293 private:
1294         EditArea(const EditArea&);
1295         EditArea& operator =(const EditArea&);
1296 }; // EditArea
1297
1298 }}} // Tizen::Ui::Controls
1299
1300 #endif // _FUI_CTRL_EDIT_AREA_H_