dali-toolkit/internal/text/text-controller.h

   1 #ifndef DALI_TOOLKIT_TEXT_CONTROLLER_H
   2 #define DALI_TOOLKIT_TEXT_CONTROLLER_H
   3
   4 /*
   5  * Copyright (c) 2016 Samsung Electronics Co., Ltd.
   6  *
   7  * Licensed under the Apache License, Version 2.0 (the "License");
   8  * you may not use this file except in compliance with the License.
   9  * You may obtain a copy of the License at
  10  *
  11  * http://www.apache.org/licenses/LICENSE-2.0
  12  *
  13  * Unless required by applicable law or agreed to in writing, software
  14  * distributed under the License is distributed on an "AS IS" BASIS,
  15  * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  16  * See the License for the specific language governing permissions and
  17  * limitations under the License.
  18  *
  19  */
  20
  21 // EXTERNAL INCLUDES
  22 #include <dali/devel-api/adaptor-framework/imf-manager.h>
  23 #include <dali/public-api/events/gesture.h>
  24
  25 // INTERNAL INCLUDES
  26 #include <dali-toolkit/devel-api/controls/text-controls/text-selection-popup-callback-interface.h>
  27 #include <dali-toolkit/internal/text/decorator/text-decorator.h>
  28 #include <dali-toolkit/internal/text/layouts/layout-engine.h>
  29 #include <dali-toolkit/internal/text/text-scroller-interface.h>
  30
  31 namespace Dali
  32 {
  33
  34 namespace Toolkit
  35 {
  36
  37 namespace Text
  38 {
  39
  40 class Controller;
  41 class ControlInterface;
  42 class EditableControlInterface;
  43 class View;
  44 struct ScrollerData;
  45
  46 typedef IntrusivePtr<Controller> ControllerPtr;
  47
  48 /**
  49  * @brief A Text Controller is used by UI Controls which display text.
  50  *
  51  * It manipulates the Logical & Visual text models on behalf of the UI Controls.
  52  * It provides a view of the text that can be used by rendering back-ends.
  53  *
  54  * For selectable/editable UI controls, the controller handles input events from the UI control
  55  * and decorations (grab handles etc) via the Decorator::ControllerInterface interface.
  56  *
  57  * The text selection popup button callbacks are as well handled via the TextSelectionPopupCallbackInterface interface.
  58  */
  59 class Controller : public RefObject, public Decorator::ControllerInterface, public TextSelectionPopupCallbackInterface, public Text::ScrollerInterface
  60 {
  61 public: // Enumerated types.
  62
  63   /**
  64    * @brief Text related operations to be done in the relayout process.
  65    */
  66   enum OperationsMask
  67   {
  68     NO_OPERATION       = 0x0000,
  69     CONVERT_TO_UTF32   = 0x0001,
  70     GET_SCRIPTS        = 0x0002,
  71     VALIDATE_FONTS     = 0x0004,
  72     GET_LINE_BREAKS    = 0x0008,
  73     GET_WORD_BREAKS    = 0x0010,
  74     BIDI_INFO          = 0x0020,
  75     SHAPE_TEXT         = 0x0040,
  76     GET_GLYPH_METRICS  = 0x0080,
  77     LAYOUT             = 0x0100,
  78     UPDATE_LAYOUT_SIZE = 0x0200,
  79     REORDER            = 0x0400,
  80     ALIGN              = 0x0800,
  81     COLOR              = 0x1000,
  82     UPDATE_DIRECTION   = 0x2000,
  83     ALL_OPERATIONS     = 0xFFFF
  84   };
  85
  86   /**
  87    * @brief Used to distinguish between regular key events and IMF events
  88    */
  89   enum InsertType
  90   {
  91     COMMIT,
  92     PRE_EDIT
  93   };
  94
  95   /**
  96    * @brief Used to specify whether to update the input style.
  97    */
  98   enum UpdateInputStyleType
  99   {
 100     UPDATE_INPUT_STYLE,
 101     DONT_UPDATE_INPUT_STYLE
 102   };
 103
 104   /**
 105    * @brief Used to specify what has been updated after the Relayout() method has been called.
 106    */
 107   enum UpdateTextType
 108   {
 109     NONE_UPDATED      = 0x0, ///< Nothing has been updated.
 110     MODEL_UPDATED     = 0x1, ///< The text's model has been updated.
 111     DECORATOR_UPDATED = 0x2  ///< The decoration has been updated.
 112   };
 113
 114   /**
 115    * @brief Different placeholder-text can be shown when the control is active/inactive.
 116    */
 117   enum PlaceholderType
 118   {
 119     PLACEHOLDER_TYPE_ACTIVE,
 120     PLACEHOLDER_TYPE_INACTIVE,
 121   };
 122
 123 public: // Constructor.
 124
 125   /**
 126    * @brief Create a new instance of a Controller.
 127    *
 128    * @return A pointer to a new Controller.
 129    */
 130   static ControllerPtr New();
 131
 132   /**
 133    * @brief Create a new instance of a Controller.
 134    *
 135    * @param[in] controlInterface The control's interface.
 136    *
 137    * @return A pointer to a new Controller.
 138    */
 139   static ControllerPtr New( ControlInterface* controlInterface );
 140
 141   /**
 142    * @brief Create a new instance of a Controller.
 143    *
 144    * @param[in] controlInterface The control's interface.
 145    * @param[in] editableControlInterface The editable control's interface.
 146    *
 147    * @return A pointer to a new Controller.
 148    */
 149   static ControllerPtr New( ControlInterface* controlInterface,
 150                             EditableControlInterface* editableControlInterface );
 151
 152   /**
 153    * @brief Sets the text-control interface.
 154    *
 155    * @param[in] controlInterface The text-control interface.
 156    */
 157   void SetTextControlInterface( ControlInterface* controlInterface );
 158
 159 public: // Configure the text controller.
 160
 161   /**
 162    * @brief Called to enable text input.
 163    *
 164    * @note Selectable or editable controls should call this once after Controller::New().
 165    * @param[in] decorator Used to create cursor, selection handle decorations etc.
 166    */
 167   void EnableTextInput( DecoratorPtr decorator );
 168
 169   /**
 170    * @brief Used to switch between bitmap & vector based glyphs
 171    *
 172    * @param[in] glyphType The type of glyph; note that metrics for bitmap & vector based glyphs are different.
 173    */
 174   void SetGlyphType( TextAbstraction::GlyphType glyphType );
 175
 176   /**
 177    * @brief Enables/disables the mark-up processor.
 178    *
 179    * By default is disabled.
 180    *
 181    * @param[in] enable Whether to enable the mark-up processor.
 182    */
 183   void SetMarkupProcessorEnabled( bool enable );
 184
 185   /**
 186    * @brief Retrieves whether the mark-up processor is enabled.
 187    *
 188    * By default is disabled.
 189    *
 190    * @return @e true if the mark-up processor is enabled, otherwise returns @e false.
 191    */
 192   bool IsMarkupProcessorEnabled() const;
 193
 194   /**
 195    * @brief Enables/disables the auto text scrolling
 196    *
 197    * By default is disabled.
 198    *
 199    * @param[in] enable Whether to enable the auto scrolling
 200    */
 201   void SetAutoScrollEnabled( bool enable );
 202
 203   /**
 204    * @brief Retrieves whether auto text scrolling is enabled.
 205    *
 206    * By default is disabled.
 207    *
 208    * @return @e true if auto scrolling is enabled, otherwise returns @e false.
 209    */
 210   bool IsAutoScrollEnabled() const;
 211
 212   /**
 213    * @brief Sets the speed the text should automatically scroll at.
 214    *
 215    * @param[in] scrollSpeed The speed of scrolling in pixels per second.
 216    */
 217   void SetAutoscrollSpeed( int scrollSpeed );
 218
 219   /**
 220    * @brief Retrieves the auto scroll speed.
 221    *
 222    * @return The auto scroll speed in pixels per second.
 223    */
 224   int GetAutoScrollSpeed() const;
 225
 226   /**
 227    * @brief Sets the number of loops the text should scroll.
 228    *
 229    * @param[in] loopCount The number of loops.
 230    */
 231   void SetAutoScrollLoopCount( int loopCount );
 232
 233   /**
 234    * @brief Retrieves the number of loops the text should scroll.
 235    *
 236    * @return The numebr of loops.
 237    */
 238   int GetAutoScrollLoopCount() const;
 239
 240   /**
 241    * @brief Sets the gap before text wraps around when scrolling.
 242    *
 243    * @param[in] wrapGap The gap in pixels.
 244    */
 245   void SetAutoScrollWrapGap( float wrapGap );
 246
 247   /**
 248    * @brief Retrieves the gap before text wraps around when scrolling.
 249    *
 250    * @return The gap in pixels.
 251    */
 252   float GetAutoScrollWrapGap() const;
 253
 254   /**
 255    * @brief Retrieves the text's autoscroll data.
 256    *
 257    * @return The text's autoscroll data.
 258    */
 259   const ScrollerData* const GetAutoScrollData();
 260
 261   /**
 262    * @brief Enables the horizontal scrolling.
 263    *
 264    * @param[in] enable Whether to enable the horizontal scrolling.
 265    */
 266   void SetHorizontalScrollEnabled( bool enable );
 267
 268   /**
 269    * @brief Retrieves whether the horizontal scrolling is enabled.
 270    *
 271    * @return @e true if the horizontal scrolling is enabled, otherwise it returns @e false.
 272    */
 273   bool IsHorizontalScrollEnabled() const;
 274
 275   /**
 276    * @brief Enables the vertical scrolling.
 277    *
 278    * @param[in] enable Whether to enable the vertical scrolling.
 279    */
 280   void SetVerticalScrollEnabled( bool enable );
 281
 282   /**
 283    * @brief Retrieves whether the verticall scrolling is enabled.
 284    *
 285    * @return @e true if the vertical scrolling is enabled, otherwise it returns @e false.
 286    */
 287   bool IsVerticalScrollEnabled() const;
 288
 289   /**
 290    * @brief Enables the smooth handle panning.
 291    *
 292    * @param[in] enable Whether to enable the smooth handle panning.
 293    */
 294   void SetSmoothHandlePanEnabled( bool enable );
 295
 296   /**
 297    * @brief Retrieves whether the smooth handle panning is enabled.
 298    *
 299    * @return @e true if the smooth handle panning is enabled.
 300    */
 301   bool IsSmoothHandlePanEnabled() const;
 302
 303   /**
 304    * @brief Sets the maximum number of characters that can be inserted into the TextModel
 305    *
 306    * @param[in] maxCharacters maximum number of characters to be accepted
 307    */
 308   void SetMaximumNumberOfCharacters( Length maxCharacters );
 309
 310   /**
 311    * @brief Sets the maximum number of characters that can be inserted into the TextModel
 312    *
 313    * @param[in] maxCharacters maximum number of characters to be accepted
 314    */
 315   int GetMaximumNumberOfCharacters();
 316
 317   /**
 318    * @brief Called to enable/disable cursor blink.
 319    *
 320    * @note Only editable controls should calls this.
 321    * @param[in] enabled Whether the cursor should blink or not.
 322    */
 323   void SetEnableCursorBlink( bool enable );
 324
 325   /**
 326    * @brief Query whether cursor blink is enabled.
 327    *
 328    * @return Whether the cursor should blink or not.
 329    */
 330   bool GetEnableCursorBlink() const;
 331
 332   /**
 333    * @brief Whether to enable the multi-line layout.
 334    *
 335    * @param[in] enable \e true enables the multi-line (by default)
 336    */
 337   void SetMultiLineEnabled( bool enable );
 338
 339   /**
 340    * @return Whether the multi-line layout is enabled.
 341    */
 342   bool IsMultiLineEnabled() const;
 343
 344   /**
 345    * @copydoc Dali::Toolkit::Text::LayoutEngine::SetHorizontalAlignment()
 346    */
 347   void SetHorizontalAlignment( LayoutEngine::HorizontalAlignment alignment );
 348
 349   /**
 350    * @copydoc Dali::Toolkit::Text::LayoutEngine::GetHorizontalAlignment()
 351    */
 352   LayoutEngine::HorizontalAlignment GetHorizontalAlignment() const;
 353
 354   /**
 355    * @copydoc Dali::Toolkit::Text::LayoutEngine::SetVerticalAlignment()
 356    */
 357   void SetVerticalAlignment( LayoutEngine::VerticalAlignment alignment );
 358
 359   /**
 360    * @copydoc Dali::Toolkit::Text::LayoutEngine::GetVerticalAlignment()
 361    */
 362   LayoutEngine::VerticalAlignment GetVerticalAlignment() const;
 363
 364 public: // Update.
 365
 366   /**
 367    * @brief Replaces any text previously set.
 368    *
 369    * @note This will be converted into UTF-32 when stored in the text model.
 370    * @param[in] text A string of UTF-8 characters.
 371    */
 372   void SetText( const std::string& text );
 373
 374   /**
 375    * @brief Retrieve any text previously set.
 376    *
 377    * @param[out] text A string of UTF-8 characters.
 378    */
 379   void GetText( std::string& text ) const;
 380
 381   /**
 382    * @brief Replaces any placeholder text previously set.
 383    *
 384    * @param[in] type Different placeholder-text can be shown when the control is active/inactive.
 385    * @param[in] text A string of UTF-8 characters.
 386    */
 387   void SetPlaceholderText( PlaceholderType type, const std::string& text );
 388
 389   /**
 390    * @brief Retrieve any placeholder text previously set.
 391    *
 392    * @param[in] type Different placeholder-text can be shown when the control is active/inactive.
 393    * @param[out] A string of UTF-8 characters.
 394    */
 395   void GetPlaceholderText( PlaceholderType type, std::string& text ) const;
 396
 397   /**
 398    * @ brief Update the text after a font change
 399    * @param[in] newDefaultFont The new font to change to
 400    */
 401   void UpdateAfterFontChange( const std::string& newDefaultFont );
 402
 403 public: // Default style & Input style
 404
 405   /**
 406    * @brief Set the default font family.
 407    *
 408    * @param[in] defaultFontFamily The default font family.
 409    */
 410   void SetDefaultFontFamily( const std::string& defaultFontFamily );
 411
 412   /**
 413    * @brief Retrieve the default font family.
 414    *
 415    * @return The default font family.
 416    */
 417   const std::string& GetDefaultFontFamily() const;
 418
 419   /**
 420    * @brief Sets the default font weight.
 421    *
 422    * @param[in] weight The font weight.
 423    */
 424   void SetDefaultFontWeight( FontWeight weight );
 425
 426   /**
 427    * @brief Whether the font's weight has been defined.
 428    */
 429   bool IsDefaultFontWeightDefined() const;
 430
 431   /**
 432    * @brief Retrieves the default font weight.
 433    *
 434    * @return The default font weight.
 435    */
 436   FontWeight GetDefaultFontWeight() const;
 437
 438   /**
 439    * @brief Sets the default font width.
 440    *
 441    * @param[in] width The font width.
 442    */
 443   void SetDefaultFontWidth( FontWidth width );
 444
 445   /**
 446    * @brief Whether the font's width has been defined.
 447    */
 448   bool IsDefaultFontWidthDefined() const;
 449
 450   /**
 451    * @brief Retrieves the default font width.
 452    *
 453    * @return The default font width.
 454    */
 455   FontWidth GetDefaultFontWidth() const;
 456
 457   /**
 458    * @brief Sets the default font slant.
 459    *
 460    * @param[in] slant The font slant.
 461    */
 462   void SetDefaultFontSlant( FontSlant slant );
 463
 464   /**
 465    * @brief Whether the font's slant has been defined.
 466    */
 467   bool IsDefaultFontSlantDefined() const;
 468
 469   /**
 470    * @brief Retrieves the default font slant.
 471    *
 472    * @return The default font slant.
 473    */
 474   FontSlant GetDefaultFontSlant() const;
 475
 476   /**
 477    * @brief Set the default point size.
 478    *
 479    * @param[in] pointSize The default point size.
 480    */
 481   void SetDefaultPointSize( float pointSize );
 482
 483   /**
 484    * @brief Retrieve the default point size.
 485    *
 486    * @return The default point size.
 487    */
 488   float GetDefaultPointSize() const;
 489
 490   /**
 491    * @brief Set the text color
 492    *
 493    * @param textColor The text color
 494    */
 495   void SetTextColor( const Vector4& textColor );
 496
 497   /**
 498    * @brief Retrieve the text color
 499    *
 500    * @return The text color
 501    */
 502   const Vector4& GetTextColor() const;
 503
 504   /**
 505    * @brief Set the text color
 506    *
 507    * @param textColor The text color
 508    */
 509   void SetPlaceholderTextColor( const Vector4& textColor );
 510
 511   /**
 512    * @brief Retrieve the text color
 513    *
 514    * @return The text color
 515    */
 516   const Vector4& GetPlaceholderTextColor() const;
 517
 518   /**
 519    * @brief Set the shadow offset.
 520    *
 521    * @param[in] shadowOffset The shadow offset, 0,0 indicates no shadow.
 522    */
 523   void SetShadowOffset( const Vector2& shadowOffset );
 524
 525   /**
 526    * @brief Retrieve the shadow offset.
 527    *
 528    * @return The shadow offset.
 529    */
 530   const Vector2& GetShadowOffset() const;
 531
 532   /**
 533    * @brief Set the shadow color.
 534    *
 535    * @param[in] shadowColor The shadow color.
 536    */
 537   void SetShadowColor( const Vector4& shadowColor );
 538
 539   /**
 540    * @brief Retrieve the shadow color.
 541    *
 542    * @return The shadow color.
 543    */
 544   const Vector4& GetShadowColor() const;
 545
 546   /**
 547    * @brief Set the underline color.
 548    *
 549    * @param[in] color color of underline.
 550    */
 551   void SetUnderlineColor( const Vector4& color );
 552
 553   /**
 554    * @brief Retrieve the underline color.
 555    *
 556    * @return The underline color.
 557    */
 558   const Vector4& GetUnderlineColor() const;
 559
 560   /**
 561    * @brief Set the underline enabled flag.
 562    *
 563    * @param[in] enabled The underline enabled flag.
 564    */
 565   void SetUnderlineEnabled( bool enabled );
 566
 567   /**
 568    * @brief Returns whether the text is underlined or not.
 569    *
 570    * @return The underline state.
 571    */
 572   bool IsUnderlineEnabled() const;
 573
 574   /**
 575    * @brief Set the override used for underline height, 0 indicates height will be supplied by font metrics
 576    *
 577    * @param[in] height The height in pixels of the underline
 578    */
 579   void SetUnderlineHeight( float height );
 580
 581   /**
 582    * @brief Retrieves the override height of an underline, 0 indicates height is supplied by font metrics
 583    *
 584    * @return The height of the underline, or 0 if height is not overrided.
 585    */
 586   float GetUnderlineHeight() const;
 587
 588   /**
 589    * @brief Sets the emboss's properties string.
 590    *
 591    * @note The string is stored to be recovered.
 592    *
 593    * @param[in] embossProperties The emboss's properties string.
 594    */
 595   void SetDefaultEmbossProperties( const std::string& embossProperties );
 596
 597   /**
 598    * @brief Retrieves the emboss's properties string.
 599    *
 600    * @return The emboss's properties string.
 601    */
 602   const std::string& GetDefaultEmbossProperties() const;
 603
 604   /**
 605    * @brief Sets the outline's properties string.
 606    *
 607    * @note The string is stored to be recovered.
 608    *
 609    * @param[in] outlineProperties The outline's properties string.
 610    */
 611   void SetDefaultOutlineProperties( const std::string& outlineProperties );
 612
 613   /**
 614    * @brief Retrieves the outline's properties string.
 615    *
 616    * @return The outline's properties string.
 617    */
 618   const std::string& GetDefaultOutlineProperties() const;
 619
 620   /**
 621    * @brief Sets the default line spacing.
 622    *
 623    * @param[in] lineSpacing The line spacing.
 624    */
 625   void SetDefaultLineSpacing( float lineSpacing );
 626
 627   /**
 628    * @brief Retrieves the default line spacing.
 629    *
 630    * @return The line spacing.
 631    */
 632   float GetDefaultLineSpacing() const;
 633
 634   /**
 635    * @brief Sets the input text's color.
 636    *
 637    * @param[in] color The input text's color.
 638    */
 639   void SetInputColor( const Vector4& color );
 640
 641   /**
 642    * @brief Retrieves the input text's color.
 643    *
 644    * @return The input text's color.
 645    */
 646   const Vector4& GetInputColor() const;
 647
 648   /**
 649    * @brief Sets the input text's font family name.
 650    *
 651    * @param[in] fontFamily The text's font family name.
 652    */
 653   void SetInputFontFamily( const std::string& fontFamily );
 654
 655   /**
 656    * @brief Retrieves the input text's font family name.
 657    *
 658    * @return The input text's font family name.
 659    */
 660   const std::string& GetInputFontFamily() const;
 661
 662   /**
 663    * @brief Sets the input font's weight.
 664    *
 665    * @param[in] weight The input font's weight.
 666    */
 667   void SetInputFontWeight( FontWeight weight );
 668
 669   /**
 670    * @return Whether the font's weight has been defined.
 671    */
 672   bool IsInputFontWeightDefined() const;
 673
 674   /**
 675    * @brief Retrieves the input font's weight.
 676    *
 677    * @return The input font's weight.
 678    */
 679   FontWeight GetInputFontWeight() const;
 680
 681   /**
 682    * @brief Sets the input font's width.
 683    *
 684    * @param[in] width The input font's width.
 685    */
 686   void SetInputFontWidth( FontWidth width );
 687
 688   /**
 689    * @return Whether the font's width has been defined.
 690    */
 691   bool IsInputFontWidthDefined() const;
 692
 693   /**
 694    * @brief Retrieves the input font's width.
 695    *
 696    * @return The input font's width.
 697    */
 698   FontWidth GetInputFontWidth() const;
 699
 700   /**
 701    * @brief Sets the input font's slant.
 702    *
 703    * @param[in] slant The input font's slant.
 704    */
 705   void SetInputFontSlant( FontSlant slant );
 706
 707   /**
 708    * @return Whether the font's slant has been defined.
 709    */
 710   bool IsInputFontSlantDefined() const;
 711
 712   /**
 713    * @brief Retrieves the input font's slant.
 714    *
 715    * @return The input font's slant.
 716    */
 717   FontSlant GetInputFontSlant() const;
 718
 719   /**
 720    * @brief Sets the input font's point size.
 721    *
 722    * @param[in] size The input font's point size.
 723    */
 724   void SetInputFontPointSize( float size );
 725
 726   /**
 727    * @brief Retrieves the input font's point size.
 728    *
 729    * @return The input font's point size.
 730    */
 731   float GetInputFontPointSize() const;
 732
 733   /**
 734    * @brief Sets the input line spacing.
 735    *
 736    * @param[in] lineSpacing The line spacing.
 737    */
 738   void SetInputLineSpacing( float lineSpacing );
 739
 740   /**
 741    * @brief Retrieves the input line spacing.
 742    *
 743    * @return The line spacing.
 744    */
 745   float GetInputLineSpacing() const;
 746
 747   /**
 748    * @brief Sets the input shadow's properties string.
 749    *
 750    * @note The string is stored to be recovered.
 751    *
 752    * @param[in] shadowProperties The shadow's properties string.
 753    */
 754   void SetInputShadowProperties( const std::string& shadowProperties );
 755
 756   /**
 757    * @brief Retrieves the input shadow's properties string.
 758    *
 759    * @return The shadow's properties string.
 760    */
 761   const std::string& GetInputShadowProperties() const;
 762
 763   /**
 764    * @brief Sets the input underline's properties string.
 765    *
 766    * @note The string is stored to be recovered.
 767    *
 768    * @param[in] underlineProperties The underline's properties string.
 769    */
 770   void SetInputUnderlineProperties( const std::string& underlineProperties );
 771
 772   /**
 773    * @brief Retrieves the input underline's properties string.
 774    *
 775    * @return The underline's properties string.
 776    */
 777   const std::string& GetInputUnderlineProperties() const;
 778
 779   /**
 780    * @brief Sets the input emboss's properties string.
 781    *
 782    * @note The string is stored to be recovered.
 783    *
 784    * @param[in] embossProperties The emboss's properties string.
 785    */
 786   void SetInputEmbossProperties( const std::string& embossProperties );
 787
 788   /**
 789    * @brief Retrieves the input emboss's properties string.
 790    *
 791    * @return The emboss's properties string.
 792    */
 793   const std::string& GetInputEmbossProperties() const;
 794
 795   /**
 796    * @brief Sets input the outline's properties string.
 797    *
 798    * @note The string is stored to be recovered.
 799    *
 800    * @param[in] outlineProperties The outline's properties string.
 801    */
 802   void SetInputOutlineProperties( const std::string& outlineProperties );
 803
 804   /**
 805    * @brief Retrieves the input outline's properties string.
 806    *
 807    * @return The outline's properties string.
 808    */
 809   const std::string& GetInputOutlineProperties() const;
 810
 811 public: // Queries & retrieves.
 812
 813   /**
 814    * @brief Return the layout engine.
 815    *
 816    * @return A reference to the layout engine.
 817    */
 818   LayoutEngine& GetLayoutEngine();
 819
 820   /**
 821    * @brief Return a view of the text.
 822    *
 823    * @return A reference to the view.
 824    */
 825   View& GetView();
 826
 827   /**
 828    * @brief Query the current scroll position; the UI control is responsible for moving actors to this position.
 829    *
 830    * @return The scroll position.
 831    */
 832   const Vector2& GetScrollPosition() const;
 833
 834   /**
 835    * @copydoc Control::GetNaturalSize()
 836    */
 837   Vector3 GetNaturalSize();
 838
 839   /**
 840    * @copydoc Control::GetHeightForWidth()
 841    */
 842   float GetHeightForWidth( float width );
 843
 844 public: // Relayout.
 845
 846   /**
 847    * @brief Triggers a relayout which updates View (if necessary).
 848    *
 849    * @note UI Controls are expected to minimize calls to this method e.g. call once after size negotiation.
 850    * @param[in] size A the size of a bounding box to layout text within.
 851    *
 852    * @return Whether the text model or decorations were updated.
 853    */
 854   UpdateTextType Relayout( const Size& size );
 855
 856   /**
 857    * @brief Request a relayout using the ControlInterface.
 858    */
 859   void RequestRelayout();
 860
 861 public: // Input style change signals.
 862
 863   /**
 864    * @return Whether the queue of input style changed signals is empty.
 865    */
 866   bool IsInputStyleChangedSignalsQueueEmpty();
 867
 868   /**
 869    * @brief Process all pending input style changed signals.
 870    *
 871    * Calls the Text::ControlInterface::InputStyleChanged() method which is overriden by the
 872    * text controls. Text controls may send signals to state the input style has changed.
 873    */
 874   void ProcessInputStyleChangedSignals();
 875
 876 public: // Text-input Event Queuing.
 877
 878   /**
 879    * @brief Called by editable UI controls when keyboard focus is gained.
 880    */
 881   void KeyboardFocusGainEvent();
 882
 883   /**
 884    * @brief Called by editable UI controls when focus is lost.
 885    */
 886   void KeyboardFocusLostEvent();
 887
 888   /**
 889    * @brief Called by editable UI controls when key events are received.
 890    *
 891    * @param[in] event The key event.
 892    * @param[in] type Used to distinguish between regular key events and IMF events.
 893    */
 894   bool KeyEvent( const Dali::KeyEvent& event );
 895
 896   /**
 897    * @brief Called by editable UI controls when a tap gesture occurs.
 898    * @param[in] tapCount The number of taps.
 899    * @param[in] x The x position relative to the top-left of the parent control.
 900    * @param[in] y The y position relative to the top-left of the parent control.
 901    */
 902   void TapEvent( unsigned int tapCount, float x, float y );
 903
 904   /**
 905    * @brief Called by editable UI controls when a pan gesture occurs.
 906    *
 907    * @param[in] state The state of the gesture.
 908    * @param[in] displacement This distance panned since the last pan gesture.
 909    */
 910   void PanEvent( Gesture::State state, const Vector2& displacement );
 911
 912   /**
 913    * @brief Called by editable UI controls when a long press gesture occurs.
 914    *
 915    * @param[in] state The state of the gesture.
 916    * @param[in] x The x position relative to the top-left of the parent control.
 917    * @param[in] y The y position relative to the top-left of the parent control.
 918    */
 919   void LongPressEvent( Gesture::State state, float x, float y );
 920
 921   /**
 922    * @brief Event received from IMF manager
 923    *
 924    * @param[in] imfManager The IMF manager.
 925    * @param[in] imfEvent The event received.
 926    * @return A data struture indicating if update is needed, cursor position and current text.
 927    */
 928   ImfManager::ImfCallbackData OnImfEvent( ImfManager& imfManager, const ImfManager::ImfEventData& imfEvent );
 929
 930   /**
 931    * @brief Event from Clipboard notifying an Item has been selected for pasting
 932    */
 933   void PasteClipboardItemEvent();
 934
 935 protected: // Inherit from Text::Decorator::ControllerInterface.
 936
 937   /**
 938    * @copydoc Dali::Toolkit::Text::Decorator::ControllerInterface::GetTargetSize()
 939    */
 940   virtual void GetTargetSize( Vector2& targetSize );
 941
 942   /**
 943    * @copydoc Dali::Toolkit::Text::Decorator::ControllerInterface::AddDecoration()
 944    */
 945   virtual void AddDecoration( Actor& actor, bool needsClipping );
 946
 947   /**
 948    * @copydoc Dali::Toolkit::Text::Decorator::ControllerInterface::DecorationEvent()
 949    */
 950   virtual void DecorationEvent( HandleType handle, HandleState state, float x, float y );
 951
 952 protected: // Inherit from TextSelectionPopup::TextPopupButtonCallbackInterface.
 953
 954   /**
 955    * @copydoc Dali::Toolkit::TextSelectionPopup::TextPopupButtonCallbackInterface::TextPopupButtonTouched()
 956    */
 957   virtual void TextPopupButtonTouched( Dali::Toolkit::TextSelectionPopup::Buttons button );
 958
 959 private: // Inherit from TextScroller
 960
 961   /**
 962    * @copydoc Text::ScrollerInterface::ScrollingFinished()
 963    */
 964   virtual void ScrollingFinished();
 965
 966 private: // Update.
 967
 968   /**
 969    * @brief Called by editable UI controls when key events are received.
 970    *
 971    * @param[in] text The text to insert.
 972    * @param[in] type Used to distinguish between regular key events and IMF events.
 973    */
 974   void InsertText( const std::string& text, InsertType type );
 975
 976   /**
 977    * @brief Paste given string into Text model
 978    * @param[in] stringToPaste this string will be inserted into the text model
 979    */
 980   void PasteText( const std::string& stringToPaste );
 981
 982   /**
 983    * @brief Remove a given number of characters
 984    *
 985    * When predictve text is used the pre-edit text is removed and inserted again with the new characters.
 986    * The UpdateInputStyleType @type parameter if set to DONT_UPDATE_INPUT_STYLE avoids to update the input
 987    * style when pre-edit text is removed.
 988    *
 989    * @param[in] cursorOffset Start position from the current cursor position to start deleting characters.
 990    * @param[in] numberOfCharacters The number of characters to delete from the cursorOffset.
 991    * @param[in] type Whether to update the input style.
 992    * @return True if the remove was successful.
 993    */
 994   bool RemoveText( int cursorOffset,
 995                    int numberOfCharacters,
 996                    UpdateInputStyleType type  );
 997
 998   /**
 999    * @brief Checks if text is selected and if so removes it.
1000    * @return true if text was removed
1001    */
1002   bool RemoveSelectedText();
1003
1004 private: // Relayout.
1005
1006   /**
1007    * @brief Lays-out the text.
1008    *
1009    * GetNaturalSize(), GetHeightForWidth() and Relayout() calls this method.
1010    *
1011    * @param[in] size A the size of a bounding box to layout text within.
1012    * @param[in] operations The layout operations which need to be done.
1013    * @param[out] layoutSize The size of the laid-out text.
1014    */
1015   bool DoRelayout( const Size& size,
1016                    OperationsMask operations,
1017                    Size& layoutSize );
1018
1019   /**
1020    * @brief Calulates the vertical offset to align the text inside the bounding box.
1021    *
1022    * @param[in] size The size of the bounding box.
1023    */
1024   void CalculateVerticalOffset( const Size& size );
1025
1026 private: // Events.
1027
1028   /**
1029    * @brief Process queued events which modify the model.
1030    */
1031   void ProcessModifyEvents();
1032
1033   /**
1034    * @brief Used to process an event queued from SetText()
1035    */
1036   void TextReplacedEvent();
1037
1038   /**
1039    * @brief Used to process an event queued from key events etc.
1040    */
1041   void TextInsertedEvent();
1042
1043   /**
1044    * @brief Used to process an event queued from backspace key etc.
1045    */
1046   void TextDeletedEvent();
1047
1048   /**
1049    * @brief Creates a selection event.
1050    *
1051    * It could be called from the TapEvent (double tap) or when the text selection popup's sellect all button is pressed.
1052    *
1053    * @param[in] x The x position relative to the top-left of the parent control.
1054    * @param[in] y The y position relative to the top-left of the parent control.
1055    * @param[in] selectAll Whether the whole text is selected.
1056    */
1057   void SelectEvent( float x, float y, bool selectAll );
1058
1059   /**
1060    * @brief Helper to KeyEvent() to handle the backspace case.
1061    *
1062    * @return True if a character was deleted.
1063    */
1064   bool BackspaceKeyEvent();
1065
1066 private: // Helpers.
1067
1068   /**
1069    * @brief Used to remove the text included the placeholder text.
1070    */
1071   void ResetText();
1072
1073   /**
1074    * @brief Helper to show the place holder text..
1075    */
1076   void ShowPlaceholderText();
1077
1078   /**
1079    * @brief Helper to clear font-specific data (only).
1080    */
1081   void ClearFontData();
1082
1083   /**
1084    * @brief Helper to clear text's style data.
1085    */
1086   void ClearStyleData();
1087
1088   /**
1089    * @brief Used to reset the cursor position after setting a new text.
1090    *
1091    * @param[in] cursorIndex Where to place the cursor.
1092    */
1093   void ResetCursorPosition( CharacterIndex cursorIndex );
1094
1095   /**
1096    * @brief Used to reset the scroll position after setting a new text.
1097    */
1098   void ResetScrollPosition();
1099
1100 private: // Private contructors & copy operator.
1101
1102   /**
1103    * @brief Private constructor.
1104    */
1105   Controller();
1106
1107   /**
1108    * @brief Private constructor.
1109    */
1110   Controller( ControlInterface* controlInterface );
1111
1112   /**
1113    * @brief Private constructor.
1114    */
1115   Controller( ControlInterface* controlInterface,
1116               EditableControlInterface* editableControlInterface );
1117
1118   // Undefined
1119   Controller( const Controller& handle );
1120
1121   // Undefined
1122   Controller& operator=( const Controller& handle );
1123
1124 protected: // Destructor.
1125
1126   /**
1127    * @brief A reference counted object may only be deleted by calling Unreference().
1128    */
1129   virtual ~Controller();
1130
1131 private:
1132
1133   struct Impl;
1134   Impl* mImpl;
1135 };
1136
1137 } // namespace Text
1138
1139 } // namespace Toolkit
1140
1141 } // namespace Dali
1142
1143 #endif // DALI_TOOLKIT_TEXT_CONTROLLER_H