Revert "Move Some Devel Properties & APIs to the Public API"
[platform/core/uifw/dali-toolkit.git] / 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) 2017 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/public-api/text/text-enumerations.h>
27 #include <dali-toolkit/devel-api/controls/text-controls/text-selection-popup-callback-interface.h>
28 #include <dali-toolkit/devel-api/controls/text-controls/text-label-devel.h>
29 #include <dali-toolkit/devel-api/text/text-enumerations-devel.h>
30 #include <dali-toolkit/internal/text/decorator/text-decorator.h>
31 #include <dali-toolkit/internal/text/layouts/layout-engine.h>
32 #include <dali-toolkit/internal/text/hidden-text.h>
33 #include <dali-toolkit/internal/text/text-model-interface.h>
34
35 namespace Dali
36 {
37
38 namespace Toolkit
39 {
40
41 namespace Text
42 {
43
44 class Controller;
45 class ControlInterface;
46 class EditableControlInterface;
47 class View;
48 class RenderingController;
49
50 typedef IntrusivePtr<Controller> ControllerPtr;
51
52 /**
53  * @brief A Text Controller is used by UI Controls which display text.
54  *
55  * It manipulates the Logical & Visual text models on behalf of the UI Controls.
56  * It provides a view of the text that can be used by rendering back-ends.
57  *
58  * For selectable/editable UI controls, the controller handles input events from the UI control
59  * and decorations (grab handles etc) via the Decorator::ControllerInterface interface.
60  *
61  * The text selection popup button callbacks are as well handled via the TextSelectionPopupCallbackInterface interface.
62  */
63 class Controller : public RefObject, public Decorator::ControllerInterface, public TextSelectionPopupCallbackInterface, public HiddenText::Observer
64 {
65 public: // Enumerated types.
66
67   /**
68    * @brief Text related operations to be done in the relayout process.
69    */
70   enum OperationsMask
71   {
72     NO_OPERATION       = 0x0000,
73     CONVERT_TO_UTF32   = 0x0001,
74     GET_SCRIPTS        = 0x0002,
75     VALIDATE_FONTS     = 0x0004,
76     GET_LINE_BREAKS    = 0x0008,
77     GET_WORD_BREAKS    = 0x0010,
78     BIDI_INFO          = 0x0020,
79     SHAPE_TEXT         = 0x0040,
80     GET_GLYPH_METRICS  = 0x0080,
81     LAYOUT             = 0x0100,
82     UPDATE_LAYOUT_SIZE = 0x0200,
83     REORDER            = 0x0400,
84     ALIGN              = 0x0800,
85     COLOR              = 0x1000,
86     UPDATE_DIRECTION   = 0x2000,
87     ALL_OPERATIONS     = 0xFFFF
88   };
89
90   /**
91    * @brief Used to distinguish between regular key events and IMF events
92    */
93   enum InsertType
94   {
95     COMMIT,
96     PRE_EDIT
97   };
98
99   /**
100    * @brief Used to specify whether to update the input style.
101    */
102   enum UpdateInputStyleType
103   {
104     UPDATE_INPUT_STYLE,
105     DONT_UPDATE_INPUT_STYLE
106   };
107
108   /**
109    * @brief Used to specify what has been updated after the Relayout() method has been called.
110    */
111   enum UpdateTextType
112   {
113     NONE_UPDATED      = 0x0, ///< Nothing has been updated.
114     MODEL_UPDATED     = 0x1, ///< The text's model has been updated.
115     DECORATOR_UPDATED = 0x2  ///< The decoration has been updated.
116   };
117
118   /**
119    * @brief Different placeholder-text can be shown when the control is active/inactive.
120    */
121   enum PlaceholderType
122   {
123     PLACEHOLDER_TYPE_ACTIVE,
124     PLACEHOLDER_TYPE_INACTIVE,
125   };
126
127   /**
128    * @brief Enumeration for Font Size Type.
129    */
130   enum FontSizeType
131   {
132     POINT_SIZE,   // The size of font in points.
133     PIXEL_SIZE    // The size of font in pixels.
134   };
135
136   struct NoTextTap
137   {
138     enum Action
139     {
140       NO_ACTION,           ///< Does no action if there is a tap on top of an area with no text.
141       HIGHLIGHT,           ///< Highlights the nearest text (at the beginning or end of the text) and shows the text's selection popup.
142       SHOW_SELECTION_POPUP ///< Shows the text's selection popup.
143     };
144   };
145
146 public: // Constructor.
147
148   /**
149    * @brief Create a new instance of a Controller.
150    *
151    * @return A pointer to a new Controller.
152    */
153   static ControllerPtr New();
154
155   /**
156    * @brief Create a new instance of a Controller.
157    *
158    * @param[in] controlInterface The control's interface.
159    *
160    * @return A pointer to a new Controller.
161    */
162   static ControllerPtr New( ControlInterface* controlInterface );
163
164   /**
165    * @brief Create a new instance of a Controller.
166    *
167    * @param[in] controlInterface The control's interface.
168    * @param[in] editableControlInterface The editable control's interface.
169    *
170    * @return A pointer to a new Controller.
171    */
172   static ControllerPtr New( ControlInterface* controlInterface,
173                             EditableControlInterface* editableControlInterface );
174
175 public: // Configure the text controller.
176
177   /**
178    * @brief Called to enable text input.
179    *
180    * @note Selectable or editable controls should call this once after Controller::New().
181    * @param[in] decorator Used to create cursor, selection handle decorations etc.
182    */
183   void EnableTextInput( DecoratorPtr decorator );
184
185   /**
186    * @brief Used to switch between bitmap & vector based glyphs
187    *
188    * @param[in] glyphType The type of glyph; note that metrics for bitmap & vector based glyphs are different.
189    */
190   void SetGlyphType( TextAbstraction::GlyphType glyphType );
191
192   /**
193    * @brief Enables/disables the mark-up processor.
194    *
195    * By default is disabled.
196    *
197    * @param[in] enable Whether to enable the mark-up processor.
198    */
199   void SetMarkupProcessorEnabled( bool enable );
200
201   /**
202    * @brief Retrieves whether the mark-up processor is enabled.
203    *
204    * By default is disabled.
205    *
206    * @return @e true if the mark-up processor is enabled, otherwise returns @e false.
207    */
208   bool IsMarkupProcessorEnabled() const;
209
210   /**
211    * @brief Enables/disables the auto text scrolling
212    *
213    * By default is disabled.
214    *
215    * @param[in] enable Whether to enable the auto scrolling
216    */
217   void SetAutoScrollEnabled( bool enable );
218
219   /**
220    * @brief Retrieves whether auto text scrolling is enabled.
221    *
222    * By default is disabled.
223    *
224    * @return @e true if auto scrolling is enabled, otherwise returns @e false.
225    */
226   bool IsAutoScrollEnabled() const;
227
228   /**
229    * @brief Get direction of the text from the first line of text,
230    * @return bool rtl (right to left) is true
231    */
232   CharacterDirection GetAutoScrollDirection() const;
233
234   /**
235    * @brief Get the alignment offset of the first line of text.
236    *
237    * @return The alignment offset.
238    */
239   float GetAutoScrollLineAlignment() const;
240
241   /**
242    * @brief Enables the horizontal scrolling.
243    *
244    * @param[in] enable Whether to enable the horizontal scrolling.
245    */
246   void SetHorizontalScrollEnabled( bool enable );
247
248   /**
249    * @brief Retrieves whether the horizontal scrolling is enabled.
250    *
251    * @return @e true if the horizontal scrolling is enabled, otherwise it returns @e false.
252    */
253   bool IsHorizontalScrollEnabled() const;
254
255   /**
256    * @brief Enables the vertical scrolling.
257    *
258    * @param[in] enable Whether to enable the vertical scrolling.
259    */
260   void SetVerticalScrollEnabled( bool enable );
261
262   /**
263    * @brief Retrieves whether the verticall scrolling is enabled.
264    *
265    * @return @e true if the vertical scrolling is enabled, otherwise it returns @e false.
266    */
267   bool IsVerticalScrollEnabled() const;
268
269   /**
270    * @brief Enables the smooth handle panning.
271    *
272    * @param[in] enable Whether to enable the smooth handle panning.
273    */
274   void SetSmoothHandlePanEnabled( bool enable );
275
276   /**
277    * @brief Retrieves whether the smooth handle panning is enabled.
278    *
279    * @return @e true if the smooth handle panning is enabled.
280    */
281   bool IsSmoothHandlePanEnabled() const;
282
283   /**
284    * @brief Sets the maximum number of characters that can be inserted into the TextModel
285    *
286    * @param[in] maxCharacters maximum number of characters to be accepted
287    */
288   void SetMaximumNumberOfCharacters( Length maxCharacters );
289
290   /**
291    * @brief Sets the maximum number of characters that can be inserted into the TextModel
292    *
293    * @param[in] maxCharacters maximum number of characters to be accepted
294    */
295   int GetMaximumNumberOfCharacters();
296
297   /**
298    * @brief Called to enable/disable cursor blink.
299    *
300    * @note Only editable controls should calls this.
301    * @param[in] enabled Whether the cursor should blink or not.
302    */
303   void SetEnableCursorBlink( bool enable );
304
305   /**
306    * @brief Query whether cursor blink is enabled.
307    *
308    * @return Whether the cursor should blink or not.
309    */
310   bool GetEnableCursorBlink() const;
311
312   /**
313    * @brief Whether to enable the multi-line layout.
314    *
315    * @param[in] enable \e true enables the multi-line (by default)
316    */
317   void SetMultiLineEnabled( bool enable );
318
319   /**
320    * @return Whether the multi-line layout is enabled.
321    */
322   bool IsMultiLineEnabled() const;
323
324   /**
325    * @brief Sets the text's horizontal alignment.
326    *
327    * @param[in] alignment The horizontal alignment.
328    */
329   void SetHorizontalAlignment( HorizontalAlignment::Type alignment );
330
331   /**
332    * @copydoc ModelInterface::GetHorizontalAlignment()
333    */
334   HorizontalAlignment::Type GetHorizontalAlignment() const;
335
336   /**
337    * @brief Sets the text's vertical alignment.
338    *
339    * @param[in] alignment The vertical alignment.
340    */
341   void SetVerticalAlignment( VerticalAlignment::Type alignment );
342
343   /**
344    * @copydoc ModelInterface::GetVerticalAlignment()
345    */
346   VerticalAlignment::Type GetVerticalAlignment() const;
347
348   /**
349    * @brief Sets the text's wrap mode
350    * @param[in] text wrap mode The unit of wrapping
351    */
352   void SetLineWrapMode( Text::LineWrap::Mode textWarpMode );
353
354   /**
355    * @brief Retrieve text wrap mode previously set.
356    * @return text wrap mode
357    */
358   Text::LineWrap::Mode GetLineWrapMode() const;
359
360   /**
361    * @brief Enable or disable the text elide.
362    *
363    * @param[in] enabled Whether to enable the text elide.
364    */
365   void SetTextElideEnabled( bool enabled );
366
367   /**
368    * @copydoc ModelInterface::IsTextElideEnabled()
369    */
370   bool IsTextElideEnabled() const;
371
372   /**
373    * @brief Enable or disable the placeholder text elide.
374    * @param enabled Whether to enable the placeholder text elide.
375    */
376   void SetPlaceholderTextElideEnabled( bool enabled );
377
378   /**
379    * @brief Whether the placeholder text elide property is enabled.
380    * @return True if the placeholder text elide property is enabled, false otherwise.
381    */
382   bool IsPlaceholderTextElideEnabled() const;
383
384   /**
385    * @brief Enable or disable the text selection.
386    * @param[in] enabled Whether to enable the text selection.
387    */
388   void SetSelectionEnabled( bool enabled );
389
390   /**
391    * @brief Whether the text selection is enabled or not.
392    * @return True if the text selection is enabled
393    */
394   bool IsSelectionEnabled() const;
395
396   /**
397    * @brief Sets input type to password
398    *
399    * @note The string is displayed hidden character
400    *
401    * @param[in] passwordInput True if password input is enabled.
402    */
403   void SetInputModePassword( bool passwordInput );
404
405   /**
406    * @brief Returns whether the input mode type is set as password.
407    *
408    * @return True if input mode type is password
409    */
410   bool IsInputModePassword();
411
412   /**
413    * @brief Sets the action when there is a double tap event on top of a text area with no text.
414    *
415    * @param[in] action The action to do.
416    */
417   void SetNoTextDoubleTapAction( NoTextTap::Action action );
418
419   /**
420    * @brief Retrieves the action when there is a double tap event on top of a text area with no text.
421    *
422    * @return The action to do.
423    */
424   NoTextTap::Action GetNoTextDoubleTapAction() const;
425
426   /**
427    * @briefSets the action when there is a long press event on top of a text area with no text.
428    *
429    * @param[in] action The action to do.
430    */
431   void SetNoTextLongPressAction( NoTextTap::Action action );
432
433   /**
434    * @brief Retrieves the action when there is a long press event on top of a text area with no text.
435    *
436    * @return The action to do.
437    */
438   NoTextTap::Action GetNoTextLongPressAction() const;
439
440   /**
441    * @brief Query if Underline settings were provided by string or map
442    * @return bool true if set by string
443    */
444   bool IsUnderlineSetByString();
445
446   /**
447    * Set method underline setting were set by
448    * @param[in] bool, true if set by string
449    */
450   void UnderlineSetByString( bool setByString );
451
452   /**
453    * @brief Query if shadow settings were provided by string or map
454    * @return bool true if set by string
455    */
456   bool IsShadowSetByString();
457
458   /**
459    * Set method shadow setting were set by
460    * @param[in] bool, true if set by string
461    */
462   void ShadowSetByString( bool setByString );
463
464   /**
465    * @brief Query if outline settings were provided by string or map
466    * @return bool true if set by string
467    */
468   bool IsOutlineSetByString();
469
470   /**
471    * Set method outline setting were set by
472    * @param[in] bool, true if set by string
473    */
474   void OutlineSetByString( bool setByString );
475
476   /**
477    * @brief Query if font style settings were provided by string or map
478    * @return bool true if set by string
479    */
480   bool IsFontStyleSetByString();
481
482   /**
483    * Set method font style setting were set by
484    * @param[in] bool, true if set by string
485    */
486   void FontStyleSetByString( bool setByString );
487
488 public: // Update.
489
490   /**
491    * @brief Replaces any text previously set.
492    *
493    * @note This will be converted into UTF-32 when stored in the text model.
494    * @param[in] text A string of UTF-8 characters.
495    */
496   void SetText( const std::string& text );
497
498   /**
499    * @brief Retrieve any text previously set.
500    *
501    * @param[out] text A string of UTF-8 characters.
502    */
503   void GetText( std::string& text ) const;
504
505   /**
506    * @brief Replaces any placeholder text previously set.
507    *
508    * @param[in] type Different placeholder-text can be shown when the control is active/inactive.
509    * @param[in] text A string of UTF-8 characters.
510    */
511   void SetPlaceholderText( PlaceholderType type, const std::string& text );
512
513   /**
514    * @brief Retrieve any placeholder text previously set.
515    *
516    * @param[in] type Different placeholder-text can be shown when the control is active/inactive.
517    * @param[out] A string of UTF-8 characters.
518    */
519   void GetPlaceholderText( PlaceholderType type, std::string& text ) const;
520
521   /**
522    * @ brief Update the text after a font change
523    * @param[in] newDefaultFont The new font to change to
524    */
525   void UpdateAfterFontChange( const std::string& newDefaultFont );
526
527 public: // Default style & Input style
528
529   /**
530    * @brief Set the default font family.
531    *
532    * @param[in] defaultFontFamily The default font family.
533    */
534   void SetDefaultFontFamily( const std::string& defaultFontFamily );
535
536   /**
537    * @brief Retrieve the default font family.
538    *
539    * @return The default font family.
540    */
541   const std::string& GetDefaultFontFamily() const;
542
543   /**
544    * @brief Sets the placeholder text font family.
545    * @param[in] placeholderTextFontFamily The placeholder text font family.
546    */
547   void SetPlaceholderFontFamily( const std::string& placeholderTextFontFamily );
548
549   /**
550    * @brief Retrieves the placeholder text font family.
551    *
552    * @return The placeholder text font family
553    */
554   const std::string& GetPlaceholderFontFamily() const;
555
556   /**
557    * @brief Sets the default font weight.
558    *
559    * @param[in] weight The font weight.
560    */
561   void SetDefaultFontWeight( FontWeight weight );
562
563   /**
564    * @brief Whether the font's weight has been defined.
565    */
566   bool IsDefaultFontWeightDefined() const;
567
568   /**
569    * @brief Retrieves the default font weight.
570    *
571    * @return The default font weight.
572    */
573   FontWeight GetDefaultFontWeight() const;
574
575   /**
576    * @brief Sets the placeholder text font weight.
577    *
578    * @param[in] weight The font weight
579    */
580   void SetPlaceholderTextFontWeight( FontWeight weight );
581
582   /**
583    * @brief Whether the font's weight has been defined.
584    *
585    * @return True if the placeholder text font weight is defined
586    */
587   bool IsPlaceholderTextFontWeightDefined() const;
588
589   /**
590    * @brief Retrieves the placeholder text font weight.
591    *
592    * @return The placeholder text font weight
593    */
594   FontWeight GetPlaceholderTextFontWeight() const;
595
596   /**
597    * @brief Sets the default font width.
598    *
599    * @param[in] width The font width.
600    */
601   void SetDefaultFontWidth( FontWidth width );
602
603   /**
604    * @brief Whether the font's width has been defined.
605    */
606   bool IsDefaultFontWidthDefined() const;
607
608   /**
609    * @brief Retrieves the default font width.
610    *
611    * @return The default font width.
612    */
613   FontWidth GetDefaultFontWidth() const;
614
615   /**
616    * @brief Sets the placeholder text font width.
617    *
618    * @param[in] width The font width
619    */
620   void SetPlaceholderTextFontWidth( FontWidth width );
621
622   /**
623    * @brief Whether the font's width has been defined.
624    *
625    * @return True if the placeholder text font width is defined
626    */
627   bool IsPlaceholderTextFontWidthDefined() const;
628
629   /**
630    * @brief Retrieves the placeholder text font width.
631    *
632    * @return The placeholder text font width
633    */
634   FontWidth GetPlaceholderTextFontWidth() const;
635
636   /**
637    * @brief Sets the default font slant.
638    *
639    * @param[in] slant The font slant.
640    */
641   void SetDefaultFontSlant( FontSlant slant );
642
643   /**
644    * @brief Whether the font's slant has been defined.
645    */
646   bool IsDefaultFontSlantDefined() const;
647
648   /**
649    * @brief Retrieves the default font slant.
650    *
651    * @return The default font slant.
652    */
653   FontSlant GetDefaultFontSlant() const;
654
655   /**
656    * @brief Sets the placeholder text font slant.
657    *
658    * @param[in] slant The font slant
659    */
660   void SetPlaceholderTextFontSlant( FontSlant slant );
661
662   /**
663    * @brief Whether the font's slant has been defined.
664    *
665    * @return True if the placeholder text font slant is defined
666    */
667   bool IsPlaceholderTextFontSlantDefined() const;
668
669   /**
670    * @brief Retrieves the placeholder text font slant.
671    *
672    * @return The placeholder text font slant
673    */
674   FontSlant GetPlaceholderTextFontSlant() const;
675
676   /**
677    * @brief Set the default font size.
678    *
679    * @param[in] fontSize The default font size
680    * @param[in] type The font size type is point size or pixel size
681    */
682   void SetDefaultFontSize( float fontSize, FontSizeType type );
683
684   /**
685    * @brief Retrieve the default point size.
686    *
687    * @param[in] type The font size type
688    * @return The default point size.
689    */
690   float GetDefaultFontSize( FontSizeType type ) const;
691
692   /**
693    * @brief Sets the Placeholder text font size.
694    * @param[in] fontSize The placeholder text font size
695    * @param[in] type The font size type is point size or pixel size
696    */
697   void SetPlaceholderTextFontSize( float fontSize, FontSizeType type );
698
699   /**
700    * @brief Retrieves the Placeholder text font size.
701    * @param[in] type The font size type
702    * @return The placeholder font size
703    */
704   float GetPlaceholderTextFontSize( FontSizeType type ) const;
705
706   /**
707    * @brief Sets the text's default color.
708    *
709    * @param color The default color.
710    */
711   void SetDefaultColor( const Vector4& color );
712
713   /**
714    * @brief Retrieves the text's default color.
715    *
716    * @return The default color.
717    */
718   const Vector4& GetDefaultColor() const;
719
720   /**
721    * @brief Set the text color
722    *
723    * @param textColor The text color
724    */
725   void SetPlaceholderTextColor( const Vector4& textColor );
726
727   /**
728    * @brief Retrieve the text color
729    *
730    * @return The text color
731    */
732   const Vector4& GetPlaceholderTextColor() const;
733
734   /**
735    * @brief Set the shadow offset.
736    *
737    * @param[in] shadowOffset The shadow offset, 0,0 indicates no shadow.
738    */
739   void SetShadowOffset( const Vector2& shadowOffset );
740
741   /**
742    * @brief Retrieve the shadow offset.
743    *
744    * @return The shadow offset.
745    */
746   const Vector2& GetShadowOffset() const;
747
748   /**
749    * @brief Set the shadow color.
750    *
751    * @param[in] shadowColor The shadow color.
752    */
753   void SetShadowColor( const Vector4& shadowColor );
754
755   /**
756    * @brief Retrieve the shadow color.
757    *
758    * @return The shadow color.
759    */
760   const Vector4& GetShadowColor() const;
761
762   /**
763    * @brief Set the shadow blur radius.
764    *
765    * @param[in] shadowBlurRadius The shadow blur radius, 0,0 indicates no blur.
766    */
767   void SetShadowBlurRadius( const float& shadowBlurRadius );
768
769   /**
770    * @brief Retrieve the shadow blur radius.
771    *
772    * @return The shadow blur radius.
773    */
774   const float& GetShadowBlurRadius() const;
775
776   /**
777    * @brief Set the underline color.
778    *
779    * @param[in] color color of underline.
780    */
781   void SetUnderlineColor( const Vector4& color );
782
783   /**
784    * @brief Retrieve the underline color.
785    *
786    * @return The underline color.
787    */
788   const Vector4& GetUnderlineColor() const;
789
790   /**
791    * @brief Set the underline enabled flag.
792    *
793    * @param[in] enabled The underline enabled flag.
794    */
795   void SetUnderlineEnabled( bool enabled );
796
797   /**
798    * @brief Returns whether the text is underlined or not.
799    *
800    * @return The underline state.
801    */
802   bool IsUnderlineEnabled() const;
803
804   /**
805    * @brief Set the override used for underline height, 0 indicates height will be supplied by font metrics
806    *
807    * @param[in] height The height in pixels of the underline
808    */
809   void SetUnderlineHeight( float height );
810
811   /**
812    * @brief Retrieves the override height of an underline, 0 indicates height is supplied by font metrics
813    *
814    * @return The height of the underline, or 0 if height is not overrided.
815    */
816   float GetUnderlineHeight() const;
817
818   /**
819    * @brief Set the outline color.
820    *
821    * @param[in] color color of outline.
822    */
823   void SetOutlineColor( const Vector4& color );
824
825   /**
826    * @brief Retrieve the outline color.
827    *
828    * @return The outline color.
829    */
830   const Vector4& GetOutlineColor() const;
831
832   /**
833    * @brief Set the outline width
834    *
835    * @param[in] width The width in pixels of the outline, 0 indicates no outline
836    */
837   void SetOutlineWidth( unsigned int width );
838
839   /**
840    * @brief Retrieves the width of an outline
841    *
842    * @return The width of the outline.
843    */
844   unsigned int GetOutlineWidth() const;
845
846   /**
847    * @brief Sets the emboss's properties string.
848    *
849    * @note The string is stored to be recovered.
850    *
851    * @param[in] embossProperties The emboss's properties string.
852    */
853   void SetDefaultEmbossProperties( const std::string& embossProperties );
854
855   /**
856    * @brief Retrieves the emboss's properties string.
857    *
858    * @return The emboss's properties string.
859    */
860   const std::string& GetDefaultEmbossProperties() const;
861
862   /**
863    * @brief Sets the outline's properties string.
864    *
865    * @note The string is stored to be recovered.
866    *
867    * @param[in] outlineProperties The outline's properties string.
868    */
869   void SetDefaultOutlineProperties( const std::string& outlineProperties );
870
871   /**
872    * @brief Retrieves the outline's properties string.
873    *
874    * @return The outline's properties string.
875    */
876   const std::string& GetDefaultOutlineProperties() const;
877
878   /**
879    * @brief Sets the default line spacing.
880    *
881    * @param[in] lineSpacing The line spacing.
882    */
883   void SetDefaultLineSpacing( float lineSpacing );
884
885   /**
886    * @brief Retrieves the default line spacing.
887    *
888    * @return The line spacing.
889    */
890   float GetDefaultLineSpacing() const;
891
892   /**
893    * @brief Sets the input text's color.
894    *
895    * @param[in] color The input text's color.
896    */
897   void SetInputColor( const Vector4& color );
898
899   /**
900    * @brief Retrieves the input text's color.
901    *
902    * @return The input text's color.
903    */
904   const Vector4& GetInputColor() const;
905
906   /**
907    * @brief Sets the input text's font family name.
908    *
909    * @param[in] fontFamily The text's font family name.
910    */
911   void SetInputFontFamily( const std::string& fontFamily );
912
913   /**
914    * @brief Retrieves the input text's font family name.
915    *
916    * @return The input text's font family name.
917    */
918   const std::string& GetInputFontFamily() const;
919
920   /**
921    * @brief Sets the input font's weight.
922    *
923    * @param[in] weight The input font's weight.
924    */
925   void SetInputFontWeight( FontWeight weight );
926
927   /**
928    * @return Whether the font's weight has been defined.
929    */
930   bool IsInputFontWeightDefined() const;
931
932   /**
933    * @brief Retrieves the input font's weight.
934    *
935    * @return The input font's weight.
936    */
937   FontWeight GetInputFontWeight() const;
938
939   /**
940    * @brief Sets the input font's width.
941    *
942    * @param[in] width The input font's width.
943    */
944   void SetInputFontWidth( FontWidth width );
945
946   /**
947    * @return Whether the font's width has been defined.
948    */
949   bool IsInputFontWidthDefined() const;
950
951   /**
952    * @brief Retrieves the input font's width.
953    *
954    * @return The input font's width.
955    */
956   FontWidth GetInputFontWidth() const;
957
958   /**
959    * @brief Sets the input font's slant.
960    *
961    * @param[in] slant The input font's slant.
962    */
963   void SetInputFontSlant( FontSlant slant );
964
965   /**
966    * @return Whether the font's slant has been defined.
967    */
968   bool IsInputFontSlantDefined() const;
969
970   /**
971    * @brief Retrieves the input font's slant.
972    *
973    * @return The input font's slant.
974    */
975   FontSlant GetInputFontSlant() const;
976
977   /**
978    * @brief Sets the input font's point size.
979    *
980    * @param[in] size The input font's point size.
981    */
982   void SetInputFontPointSize( float size );
983
984   /**
985    * @brief Retrieves the input font's point size.
986    *
987    * @return The input font's point size.
988    */
989   float GetInputFontPointSize() const;
990
991   /**
992    * @brief Sets the input line spacing.
993    *
994    * @param[in] lineSpacing The line spacing.
995    */
996   void SetInputLineSpacing( float lineSpacing );
997
998   /**
999    * @brief Retrieves the input line spacing.
1000    *
1001    * @return The line spacing.
1002    */
1003   float GetInputLineSpacing() const;
1004
1005   /**
1006    * @brief Sets the input shadow's properties string.
1007    *
1008    * @note The string is stored to be recovered.
1009    *
1010    * @param[in] shadowProperties The shadow's properties string.
1011    */
1012   void SetInputShadowProperties( const std::string& shadowProperties );
1013
1014   /**
1015    * @brief Retrieves the input shadow's properties string.
1016    *
1017    * @return The shadow's properties string.
1018    */
1019   const std::string& GetInputShadowProperties() const;
1020
1021   /**
1022    * @brief Sets the input underline's properties string.
1023    *
1024    * @note The string is stored to be recovered.
1025    *
1026    * @param[in] underlineProperties The underline's properties string.
1027    */
1028   void SetInputUnderlineProperties( const std::string& underlineProperties );
1029
1030   /**
1031    * @brief Retrieves the input underline's properties string.
1032    *
1033    * @return The underline's properties string.
1034    */
1035   const std::string& GetInputUnderlineProperties() const;
1036
1037   /**
1038    * @brief Sets the input emboss's properties string.
1039    *
1040    * @note The string is stored to be recovered.
1041    *
1042    * @param[in] embossProperties The emboss's properties string.
1043    */
1044   void SetInputEmbossProperties( const std::string& embossProperties );
1045
1046   /**
1047    * @brief Retrieves the input emboss's properties string.
1048    *
1049    * @return The emboss's properties string.
1050    */
1051   const std::string& GetInputEmbossProperties() const;
1052
1053   /**
1054    * @brief Sets input the outline's properties string.
1055    *
1056    * @note The string is stored to be recovered.
1057    *
1058    * @param[in] outlineProperties The outline's properties string.
1059    */
1060   void SetInputOutlineProperties( const std::string& outlineProperties );
1061
1062   /**
1063    * @brief Retrieves the input outline's properties string.
1064    *
1065    * @return The outline's properties string.
1066    */
1067   const std::string& GetInputOutlineProperties() const;
1068
1069   /**
1070    * @brief Set the control's interface.
1071    *
1072    * @param[in] controlInterface The control's interface.
1073    */
1074   void SetControlInterface( ControlInterface* controlInterface );
1075
1076 public: // Queries & retrieves.
1077
1078   /**
1079    * @brief Return the layout engine.
1080    *
1081    * @return A reference to the layout engine.
1082    */
1083   Layout::Engine& GetLayoutEngine();
1084
1085   /**
1086    * @brief Return a view of the text.
1087    *
1088    * @return A reference to the view.
1089    */
1090   View& GetView();
1091
1092   /**
1093    * @copydoc Control::GetNaturalSize()
1094    */
1095   Vector3 GetNaturalSize();
1096
1097   /**
1098    * @copydoc Control::GetHeightForWidth()
1099    */
1100   float GetHeightForWidth( float width );
1101
1102   /**
1103    * @brief Retrieves the text's number of lines for a given width.
1104    * @param[in] width The width of the text's area.
1105    * @ return The number of lines.
1106    */
1107   int GetLineCount( float width );
1108
1109   /**
1110    * @brief Retrieves the text's model.
1111    *
1112    * @return A pointer to the text's model.
1113    */
1114   const ModelInterface* const GetTextModel() const;
1115
1116   /**
1117    * @brief Used to get scrolled distance by user input
1118    *
1119    * @return Distance from last scroll offset to new scroll offset
1120    */
1121   float GetScrollAmountByUserInput();
1122
1123   /**
1124    * @brief Get latest scroll amount, control size and layout size
1125    *
1126    * This method is used to get information of control's scroll
1127    * @param[out] scrollPosition The current scrolled position
1128    * @param[out] controlHeight The size of a UI control
1129    * @param[out] layoutHeight The size of a bounding box to layout text within.
1130    *
1131    * @return Whether the text scroll position is changed or not after last update.
1132    */
1133   bool GetTextScrollInfo( float& scrollPosition, float& controlHeight, float& layoutHeight );
1134
1135   /**
1136    * @brief Used to set the hidden input option
1137    */
1138   void SetHiddenInputOption( const Property::Map& options );
1139
1140   /**
1141    * @brief Used to get the hidden input option
1142    */
1143   void GetHiddenInputOption( Property::Map& options );
1144
1145   /**
1146    * @brief Sets the Placeholder Properties.
1147    *
1148    * @param[in] map The placeholder property map
1149    */
1150   void SetPlaceholderProperty( const Property::Map& map );
1151
1152   /**
1153    * @brief Retrieves the Placeholder Property map.
1154    *
1155    * @param[out] map The property map
1156    */
1157   void GetPlaceholderProperty( Property::Map& map );
1158
1159   /**
1160    * @brief Checks text direction.
1161    * @return The text direction.
1162    */
1163   Toolkit::DevelText::TextDirection::Type GetTextDirection();
1164
1165 public: // Relayout.
1166
1167   /**
1168    * @brief Triggers a relayout which updates View (if necessary).
1169    *
1170    * @note UI Controls are expected to minimize calls to this method e.g. call once after size negotiation.
1171    * @param[in] size A the size of a bounding box to layout text within.
1172    *
1173    * @return Whether the text model or decorations were updated.
1174    */
1175   UpdateTextType Relayout( const Size& size );
1176
1177   /**
1178    * @brief Request a relayout using the ControlInterface.
1179    */
1180   void RequestRelayout();
1181
1182 public: // Input style change signals.
1183
1184   /**
1185    * @return Whether the queue of input style changed signals is empty.
1186    */
1187   bool IsInputStyleChangedSignalsQueueEmpty();
1188
1189   /**
1190    * @brief Process all pending input style changed signals.
1191    *
1192    * Calls the Text::ControlInterface::InputStyleChanged() method which is overriden by the
1193    * text controls. Text controls may send signals to state the input style has changed.
1194    */
1195   void ProcessInputStyleChangedSignals();
1196
1197 public: // Text-input Event Queuing.
1198
1199   /**
1200    * @brief Called by editable UI controls when keyboard focus is gained.
1201    */
1202   void KeyboardFocusGainEvent();
1203
1204   /**
1205    * @brief Called by editable UI controls when focus is lost.
1206    */
1207   void KeyboardFocusLostEvent();
1208
1209   /**
1210    * @brief Called by editable UI controls when key events are received.
1211    *
1212    * @param[in] event The key event.
1213    * @param[in] type Used to distinguish between regular key events and IMF events.
1214    */
1215   bool KeyEvent( const Dali::KeyEvent& event );
1216
1217   /**
1218    * @brief Called by editable UI controls when a tap gesture occurs.
1219    * @param[in] tapCount The number of taps.
1220    * @param[in] x The x position relative to the top-left of the parent control.
1221    * @param[in] y The y position relative to the top-left of the parent control.
1222    */
1223   void TapEvent( unsigned int tapCount, float x, float y );
1224
1225   /**
1226    * @brief Called by editable UI controls when a pan gesture occurs.
1227    *
1228    * @param[in] state The state of the gesture.
1229    * @param[in] displacement This distance panned since the last pan gesture.
1230    */
1231   void PanEvent( Gesture::State state, const Vector2& displacement );
1232
1233   /**
1234    * @brief Called by editable UI controls when a long press gesture occurs.
1235    *
1236    * @param[in] state The state of the gesture.
1237    * @param[in] x The x position relative to the top-left of the parent control.
1238    * @param[in] y The y position relative to the top-left of the parent control.
1239    */
1240   void LongPressEvent( Gesture::State state, float x, float y );
1241
1242   /**
1243    * @brief Event received from IMF manager
1244    *
1245    * @param[in] imfManager The IMF manager.
1246    * @param[in] imfEvent The event received.
1247    * @return A data struture indicating if update is needed, cursor position and current text.
1248    */
1249   ImfManager::ImfCallbackData OnImfEvent( ImfManager& imfManager, const ImfManager::ImfEventData& imfEvent );
1250
1251   /**
1252    * @brief Event from Clipboard notifying an Item has been selected for pasting
1253    */
1254   void PasteClipboardItemEvent();
1255
1256   /**
1257    * @brief Return true when text control should clear key input focus when escape key is pressed.
1258    *
1259    * @return Whether text control should clear key input focus or not when escape key is pressed.
1260    */
1261   bool ShouldClearFocusOnEscape() const;
1262
1263 protected: // Inherit from Text::Decorator::ControllerInterface.
1264
1265   /**
1266    * @copydoc Dali::Toolkit::Text::Decorator::ControllerInterface::GetTargetSize()
1267    */
1268   virtual void GetTargetSize( Vector2& targetSize );
1269
1270   /**
1271    * @copydoc Dali::Toolkit::Text::Decorator::ControllerInterface::AddDecoration()
1272    */
1273   virtual void AddDecoration( Actor& actor, bool needsClipping );
1274
1275   /**
1276    * @copydoc Dali::Toolkit::Text::Decorator::ControllerInterface::DecorationEvent()
1277    */
1278   virtual void DecorationEvent( HandleType handle, HandleState state, float x, float y );
1279
1280 protected: // Inherit from TextSelectionPopup::TextPopupButtonCallbackInterface.
1281
1282   /**
1283    * @copydoc Dali::Toolkit::TextSelectionPopup::TextPopupButtonCallbackInterface::TextPopupButtonTouched()
1284    */
1285   virtual void TextPopupButtonTouched( Dali::Toolkit::TextSelectionPopup::Buttons button );
1286
1287 protected: // Inherit from HiddenText.
1288
1289   /**
1290    * @brief Invoked from HiddenText when showing time of the last character was expired
1291    */
1292   virtual void DisplayTimeExpired();
1293
1294 private: // Update.
1295
1296   /**
1297    * @brief Called by editable UI controls when key events are received.
1298    *
1299    * @param[in] text The text to insert.
1300    * @param[in] type Used to distinguish between regular key events and IMF events.
1301    */
1302   void InsertText( const std::string& text, InsertType type );
1303
1304   /**
1305    * @brief Paste given string into Text model
1306    * @param[in] stringToPaste this string will be inserted into the text model
1307    */
1308   void PasteText( const std::string& stringToPaste );
1309
1310   /**
1311    * @brief Remove a given number of characters
1312    *
1313    * When predictve text is used the pre-edit text is removed and inserted again with the new characters.
1314    * The UpdateInputStyleType @type parameter if set to DONT_UPDATE_INPUT_STYLE avoids to update the input
1315    * style when pre-edit text is removed.
1316    *
1317    * @param[in] cursorOffset Start position from the current cursor position to start deleting characters.
1318    * @param[in] numberOfCharacters The number of characters to delete from the cursorOffset.
1319    * @param[in] type Whether to update the input style.
1320    * @return True if the remove was successful.
1321    */
1322   bool RemoveText( int cursorOffset,
1323                    int numberOfCharacters,
1324                    UpdateInputStyleType type  );
1325
1326   /**
1327    * @brief Checks if text is selected and if so removes it.
1328    * @return true if text was removed
1329    */
1330   bool RemoveSelectedText();
1331
1332 private: // Relayout.
1333
1334   /**
1335    * @brief Lays-out the text.
1336    *
1337    * GetNaturalSize(), GetHeightForWidth() and Relayout() calls this method.
1338    *
1339    * @param[in] size A the size of a bounding box to layout text within.
1340    * @param[in] operations The layout operations which need to be done.
1341    * @param[out] layoutSize The size of the laid-out text.
1342    */
1343   bool DoRelayout( const Size& size,
1344                    OperationsMask operations,
1345                    Size& layoutSize );
1346
1347   /**
1348    * @brief Calulates the vertical offset to align the text inside the bounding box.
1349    *
1350    * @param[in] size The size of the bounding box.
1351    */
1352   void CalculateVerticalOffset( const Size& size );
1353
1354 private: // Events.
1355
1356   /**
1357    * @brief Process queued events which modify the model.
1358    */
1359   void ProcessModifyEvents();
1360
1361   /**
1362    * @brief Used to process an event queued from SetText()
1363    */
1364   void TextReplacedEvent();
1365
1366   /**
1367    * @brief Used to process an event queued from key events etc.
1368    */
1369   void TextInsertedEvent();
1370
1371   /**
1372    * @brief Used to process an event queued from backspace key etc.
1373    */
1374   void TextDeletedEvent();
1375
1376   /**
1377    * @brief Creates a selection event.
1378    *
1379    * It could be called from the TapEvent (double tap) or when the text selection popup's sellect all button is pressed.
1380    *
1381    * @param[in] x The x position relative to the top-left of the parent control.
1382    * @param[in] y The y position relative to the top-left of the parent control.
1383    * @param[in] selectAll Whether the whole text is selected.
1384    */
1385   void SelectEvent( float x, float y, bool selectAll );
1386
1387   /**
1388    * @brief Helper to KeyEvent() to handle the backspace or delete key case.
1389    *
1390    * @param[in] keyCode The keycode for the key pressed
1391    * @return True if a character was deleted.
1392    */
1393   bool DeleteEvent( int keyCode );
1394
1395 private: // Helpers.
1396
1397   /**
1398    * @brief Used to remove the text included the placeholder text.
1399    */
1400   void ResetText();
1401
1402   /**
1403    * @brief Helper to show the place holder text..
1404    */
1405   void ShowPlaceholderText();
1406
1407   /**
1408    * @brief Helper to clear font-specific data (only).
1409    */
1410   void ClearFontData();
1411
1412   /**
1413    * @brief Helper to clear text's style data.
1414    */
1415   void ClearStyleData();
1416
1417   /**
1418    * @brief Used to reset the cursor position after setting a new text.
1419    *
1420    * @param[in] cursorIndex Where to place the cursor.
1421    */
1422   void ResetCursorPosition( CharacterIndex cursorIndex );
1423
1424   /**
1425    * @brief Used to reset the scroll position after setting a new text.
1426    */
1427   void ResetScrollPosition();
1428
1429 private: // Private contructors & copy operator.
1430
1431   /**
1432    * @brief Private constructor.
1433    */
1434   Controller();
1435
1436   /**
1437    * @brief Private constructor.
1438    */
1439   Controller( ControlInterface* controlInterface );
1440
1441   /**
1442    * @brief Private constructor.
1443    */
1444   Controller( ControlInterface* controlInterface,
1445               EditableControlInterface* editableControlInterface );
1446
1447   // Undefined
1448   Controller( const Controller& handle );
1449
1450   // Undefined
1451   Controller& operator=( const Controller& handle );
1452
1453 protected: // Destructor.
1454
1455   /**
1456    * @brief A reference counted object may only be deleted by calling Unreference().
1457    */
1458   virtual ~Controller();
1459
1460 private:
1461
1462   struct Impl;
1463   Impl* mImpl;
1464 };
1465
1466 } // namespace Text
1467
1468 } // namespace Toolkit
1469
1470 } // namespace Dali
1471
1472 #endif // DALI_TOOLKIT_TEXT_CONTROLLER_H