[SRUK] Initial copy from Tizen 2.2 version
[platform/core/uifw/dali-toolkit.git] / capi / dali-toolkit / public-api / controls / text-input / text-input.h
1 #ifndef __DALI_TOOLKIT_TEXT_INPUT_H__
2 #define __DALI_TOOLKIT_TEXT_INPUT_H__
3
4 //
5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
6 //
7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
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  * @addtogroup CAPI_DALI_FRAMEWORK
22  * @{
23  */
24
25 // INTERNAL INCLUDES
26 #include <dali-toolkit/public-api/controls/text-view/text-view.h>
27
28 namespace Dali DALI_IMPORT_API
29 {
30
31 namespace Toolkit
32 {
33
34 namespace Internal DALI_INTERNAL
35 {
36 class TextInput;
37 }
38
39 /**
40  * TextInput Actor takes input one character at a time and displays it as a string within an input box.
41  * Characters can be removed from the end of the string until it is empty. A maximum length of displayed string
42  * can be set.
43  */
44 class TextInput : public Control
45 {
46
47 public:
48
49   //Signal Names
50   static const char* const SIGNAL_START_INPUT;
51   static const char* const SIGNAL_END_INPUT;
52   static const char* const SIGNAL_STYLE_CHANGED;
53   static const char* const SIGNAL_MAX_INPUT_CHARACTERS_REACHED;
54   static const char* const SIGNAL_TOOLBAR_DISPLAYED;
55   static const char* const SIGNAL_TEXT_EXCEED_BOUNDARIES;
56
57 public:
58
59   /**
60    * Create an uninitialized TextInput; this can be initialized with TextView::New()
61    * Calling member functions with an uninitialized Dali::Object is not allowed.
62    */
63   TextInput();
64
65   /**
66    * Copy constructor.
67    * @param handle to be copied
68    */
69   TextInput( const TextInput& handle );
70
71   /**
72    * Assignment operator.
73    * @param handle to object we want to point to
74    * @return handle to the TextInput
75    */
76   TextInput& operator=( const TextInput& handle );
77
78   /**
79    * Create an initialised TextInput.
80    * @return A handle to a newly allocated Dali resource.
81    */
82   static TextInput New();
83
84   /**
85    * Downcast an Object handle to TextInput. If handle points to a TextInput the
86    * downcast produces valid handle. If not the returned handle is left uninitialized.
87    * @param[in] handle Handle to an object
88    * @return handle to a TextInput or an uninitialized handle
89    */
90   static TextInput DownCast( BaseHandle handle );
91
92   /**
93    * Virtual destructor.
94    * Dali::Object derived classes typically do not contain member data.
95    */
96   virtual ~TextInput();
97
98   /**
99    * Get the inputed text currently being displayed.
100    * @return string, the currently displayed string.
101    */
102   std::string GetText() const;
103
104   /**
105    * Get the inputed text currently being displayed together with mark-up tags.
106    * @return string, the currently displayed string with mark-up.
107    */
108   std::string GetMarkupText() const;
109
110   /**
111    * Set the maximum number of characters for the Text Input
112    * @param [in] maxChars the max number of characters
113    */
114   void SetMaxCharacterLength(std::size_t maxChars);
115
116   /**
117    * Limits the number of lines of text Text Input will display
118    * @param [in] maxLines the max number of lines to display, must be greater than 0.
119    * Currently the only valid limit is 1. Which turns TextInput into Single line mode. Any number higher than 1 results in no limit.
120    */
121   void SetNumberOfLinesLimit(std::size_t maxLines);
122
123   /**
124    * Returns the limit of lines Text Input is allowed to display.
125    * @return max line number limit
126    */
127   std::size_t GetNumberOfLinesLimit() const;
128
129   /**
130    * Returns the number of characters TextInput is displaying.
131    * @return number of characters
132    */
133   std::size_t GetNumberOfCharacters() const;
134
135   /**
136    *  Sets a place holder text to be displayed when the text-input is empty.
137    *  If not set or set to an empty string then no place holder will be shown.
138    *  @param [in] placeHolderText text to be used as place holder.
139    */
140   void SetPlaceholderText( const std::string& placeHolderText );
141
142   /**
143    * @return the current set place holder text, empty string returned if not set.
144    */
145   std::string GetPlaceholderText();
146
147   /**
148    *  set initial text to be displayed in text-input
149    *  can be used to edit a pre-existing string
150    *  @param [in] initialText text to be initially displayed
151    */
152   void SetInitialText(const std::string& initialText);
153
154   /**
155    *  Manual method to set the focus on the TextInput so it starts or stops edit state
156    *  @pre The text input actor has been initialised.
157    *  @param[in] editMode true or false to indicate editMode on or off
158    */
159    void SetEditable(bool editMode);
160
161    /**
162     * @see SetEditable(bool editMode).
163     *
164     * It sets the cursor in the closest character to the given touch point.
165     *
166    *  @param[in] editMode true or false to indicate editMode on or off
167     * @param[in] touchPoint A position in actor coordinates within the text-input.
168     */
169    void SetEditable(bool editMode, const Vector2& touchPoint);
170
171    /**
172     *  Check if TextInput is in edit state
173     *  @pre The text input actor has been initialised.
174     *  @return  True or False to indicate editMode on or off
175     */
176    bool IsEditable() const;
177
178    /**
179     * Method to enable or disable edit on touch/tap.
180     * If not enabled (set to false) then SetEditable(true) will be used to start edit mode.
181     * @pre The text input actor has been initialised.
182     * @param[in] editOnTouch true or false to indicate if editing should start on touch
183     *            default is for editing to start on touching textinput
184     */
185    void SetEditOnTouch(bool editOnTouch = true);
186
187    /**
188     *  Check if TextInput starts edit mode on touch
189     *  @pre The text input actor has been initialised.
190     *  @return  True or False to indicate editOnTouch on or off
191     */
192    bool IsEditOnTouch() const;
193
194    /**
195     *  Check if Text Selection is enabled so required text can be highlighted
196     *  @pre The text input actor has been initialised.
197     *  @param[in] textSelectable true or false to indicate if text can be selected or not
198     *             default is for text to be select-able when in edit mode
199     */
200    void SetTextSelectable(bool textSelectable = true);
201
202    /**
203     *  Check if Text can be selected
204     *  @pre The text input actor has been initialised.
205     *  @return  True or False to indicate if text can be selected or not
206     */
207    bool IsTextSelectable() const;
208
209    /**
210     * Check if any text is currently selected, can be used to determine if ApplyStyle or SetActiveStyle should be used.
211     * @pre The text input actor has been initialised.
212     * @return True if text selected else False
213     */
214    bool IsTextSelected() const;
215
216    /**
217     * Selects text between the given positions
218     * @pre TextInput should be in edit mode.
219     * @param start position to start selection
220     * @param end position to end selection, inclusive of this character.
221     * Providing 0 and result from GetNumberOfCharacters() will select all text.
222     */
223    void SelectText(std::size_t start, std::size_t end);
224
225    /**
226     * If any text is selected then de-select it and hide highlight.
227     * @pre The text input actor has been initialised.
228     */
229    void DeSelectText();
230
231    /**
232     * Set the image to be used as the cursor grab hander
233     * @pre The text input actor has been initialised.
234     * @param[in] image The image to be used.
235     */
236    void SetGrabHandleImage( Image image );
237
238    /**
239     * Set the image to be used for the regular left to right cursor
240     * @pre The text input actor has been initialised.
241     * @param[in] image The image to be used.
242     * @param[in] border The nine patch border for the image.
243     */
244    void SetCursorImage(Dali::Image image, const Vector4& border );
245
246    /**
247     * Retrieve the selection handle size. Both handles have same size.
248     * @return Vector3 the selection handle size.
249     */
250    Vector3 GetSelectionHandleSize();
251
252    /**
253     * Set the image to be used for the Right to Left cursor
254     * @pre The text input actor has been initialised.
255     * @param[in] image The image to be used.
256     * @param[in] border The nine patch border for the image.
257     */
258     void SetRTLCursorImage(Dali::Image image, const Vector4& border );
259
260    /**
261     * Toggle to enable the grab handle, used to position cursor when magnifier not being used.
262     * Default behaviour is to use the magnifier to position the cursor, enabling this prevents the magnifier from being shown.
263     * @param[in] toggle true to enable, false to disable grab handle
264     */
265    void EnableGrabHandle(bool toggle);
266
267    /**
268     * Method to check if grab handle is enabled, if false then the magnifier will be used to position cursor.
269     * @return bool returns true is grab handle enabled.
270     */
271    bool IsGrabHandleEnabled();
272
273   /**
274    * Toggle to enable flipping the selection handle, when it is reached the selection handle flip border.
275    * @param[in] toggle true to enable, false to disable flipping the selection handle. DEFAULT = true.
276    */
277   /* @deprecated, handles always flip. Use SetBoundingRectangle */
278   void EnableSelectionHandleFlip( bool toggle );
279
280   /**
281    * Method to check if the selection handle flip is enabled, if true then the selection cursor will be fliped when this exceed border.
282    * @return bool return true is that the selection handle flip enable.
283    */
284   /* @deprecated, handles always flip. Use SetBoundingRectangle */
285   bool IsSelectionHandleFlipEnabled();
286
287   /**
288    * Set the selection handle filp margin.
289    * The default value is Vector4(0, 0, 0, 0)
290    * ------------------------------------------
291    * |                  y                     |
292    * |   ----------------------------------   |
293    * |   |                                |   |
294    * | x |          Text Input            | z |
295    * |   |                                |   |
296    * |  ----------------------------------    |
297    * |                  w                     |
298    * ------------------------------------------
299    */
300    /* @deprecated, use SetBoundingRectangle instead. */
301   void SetSelectionHandleFlipMargin( const Vector4& margin );
302
303   /**
304    * Set the bounding rectangle which handles, popup and similar decorations will not exceed
305    * The default value is the width and height of the stage from the top left origin.
306    * If a title bar for example is on the top of the screen then the y should be the title's height and
307    * the boundary height the stage height minus the title's height.
308    * Restrictions - The boundary box should be set up with a fixed z position for the text-input and the default camera.
309    * @param[in] boundingOriginAndSize Rect( x coordinate, y coordinate, width, height )
310    * ------------------------------------------
311    * |(x,y)                                   |
312    * |o---------------------------------------|
313    * ||                                      ||
314    * ||            Bounding Box              || boundary height
315    * ||                                      ||
316    * |----------------------------------------|
317    * ------------------------------------------
318    *               boundary width
319    */
320   void SetBoundingRectangle( const Rect<float>& boundingOriginAndSize );
321
322   /**
323    * Retrieve the bounding box origin and dimensions
324    * default is set once control is added to stage, before this the return vector will be Vector4:ZERO
325    * @return Rect the bounding rectangle
326    */
327   const Rect<float> GetBoundingRectangle() const;
328
329   /**
330    * Retrieve the selection handle filp margin.
331    * @return Vector4 the selection handle flip margin.
332    */
333   /* @deprecated, use GetBoundingRectangle instead. */
334   const Vector4& GetSelectionHandleFlipMargin();
335
336    /**
337     * Sets the style for new text being typed.
338     * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
339     * @pre The text input actor has been initialised.
340     * @param[in] style The style for the new text.
341     * @param[in] mask The bit mask.
342     */
343    void SetActiveStyle( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
344
345    /**
346     * Applies the given style to the selected text.
347     * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
348     * Introduced text after this call uses the new style.
349     * @param[in] style The given style.
350     * @param[in] mask The bit mask.
351     */
352    void ApplyStyle( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
353
354    /**
355      * Applies the given style to all text, selected or not selected.
356      * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
357      * @param[in] style The given style.
358      * @param[in] mask The bit mask.
359      */
360    void ApplyStyleToAll( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
361
362    /**
363     * Get the style of the Text character before the cursor
364     * If no character before then return the InputStyle.
365     * @return TextStyle, the style of the character before the cursor
366     */
367    TextStyle GetStyleAtCursor() const;
368
369   /**
370    * Set the current text alignment (overrides default setting)
371    *
372    * The default alignment is dependent on the current text in the text field.
373    * If the text begins using LTR characters (e.g. European text) then the
374    * alignment is HorizontalLeft. If the text begins using RTL characters
375    * (e.g. Hebrew/Arabic text) then the alignment is HorizontalRight.
376    * If there is no text, then the alignment defaults to:
377    * (HorizontalLeft | VerticalCenter)
378    * @param[in] align The new alignment option.
379    */
380   void SetTextAlignment( Toolkit::Alignment::Type align );
381
382   /**
383    * Set the current line justification. (overrides default setting)
384    * The default justification is dependent on the current text in the text field.
385    * If the text begins using LTR characters (e.g. European text) then the
386    * justification is HorizontalLeft. If the text begins using RTL characters
387    * (e.g. Hebrew/Arabic text) then the justification is HorizontalRight.
388    * If there is no text, then the justification defaults to:
389    * (HorizontalLeft | VerticalCenter)
390    * @param[in] justification The new line justification.
391    */
392   void SetTextLineJustification( Toolkit::TextView::LineJustification justification );
393
394   /**
395    * Sets a fade boundary.
396    *
397    * @see TextView::FadeBoundary.
398    *
399    * @param[in] fadeBoundary The given fade boundary.
400    */
401   void SetFadeBoundary( const Toolkit::TextView::FadeBoundary& fadeBoundary );
402
403   /**
404    * Retrieves the fade boundary.
405    *
406    * @see TextView::FadeBoundary.
407    *
408    * @return The fade boundary.
409    */
410   const Toolkit::TextView::FadeBoundary& GetFadeBoundary() const;
411
412   /**
413    * Get the current text alignment combined into a single value.
414    * The values can be tested by using the & operator
415    * and the desired flag. e.g. if (GetTextAlignment() & HorizontalCentre) ...
416    */
417   Toolkit::Alignment::Type GetTextAlignment() const;
418
419   /**
420    * Sets how to split the text in lines policy.
421    * @param policy The multi-line policy.
422    */
423    void SetMultilinePolicy( Toolkit::TextView::MultilinePolicy policy );
424
425   /**
426    * Gets the split in lines policy.
427    * @return The multi-line policy.
428    */
429   Toolkit::TextView::MultilinePolicy GetMultilinePolicy() const;
430
431   /**
432    * Sets how to display the text inside the TextView when it exceeds the text-view's width.
433    * @param policy The exceed policy.
434    */
435   void SetWidthExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
436
437   /**
438    * Gets the width exceed policy.
439    * @return The exceed policy.
440    */
441   TextView::ExceedPolicy GetWidthExceedPolicy() const;
442
443   /**
444    * Sets how to display the text inside the TextView when it exceeds the text-view's height.
445    * @param policy The exceed policy.
446    */
447   void SetHeightExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
448
449   /**
450    * Gets the height exceed policy.
451    * @return The exceed policy.
452    */
453   TextView::ExceedPolicy GetHeightExceedPolicy() const;
454
455   /**
456    * Sets if the inputed text can exceed the text-input boundary.
457    *
458    * By default is enabled.
459    *
460    * @param[in] enable Whether the inputed text can exceed its boundary.
461    */
462   void SetExceedEnabled( bool enable );
463
464   /**
465    * Retrieves whether inputed text can exceed the text-input boundary.
466    *
467    * @return \e true if text inputed can exceed the boundary, otherwise \e false.
468    */
469   bool GetExceedEnabled() const;
470
471   /**
472    * Allows modification of text-actor's position in the depth sort algorithm.
473    *
474    * @see Dali::RenderableActor::SetSortModifier()
475    * @param [in] depthOffset the offset to be given to the internal text-actors. Positive values pushing it further back.
476    */
477   void SetSortModifier( float depthOffset );
478
479   /**
480    * Sets whether text-view renders text using a previously generated snapshot.
481    *
482    * @see TextView::SetSnapshotModeEnabled()
483    *
484    * @param[in] enable Whether text-view is using or not a snapshot to render text.
485    */
486   void SetSnapshotModeEnabled( bool enable );
487
488   /**
489    * Retrieves whether text-view is using a snapshot to render text
490    *
491    * @see TextView::IsSnapshotModeEnabled()
492    *
493    * @return \e true if text-view is using a snapshot to render text, otherwhise it returns \e false.
494    */
495   bool IsSnapshotModeEnabled() const;
496
497   /**
498    * @copydoc TextView::SetScrollEnabled()
499    */
500   void SetScrollEnabled( bool enable );
501
502   /**
503    * @copydoc TextView::IsScrollEnabled()
504    */
505   bool IsScrollEnabled() const;
506
507   /**
508    * @copydoc TextView::SetScrollPosition()
509    */
510   void SetScrollPosition( const Vector2& position );
511
512   /**
513    * @copydoc TextView::GetScrollPosition()
514    */
515   Vector2 GetScrollPosition() const;
516
517 public: /* Signals */
518
519   // Input Signal
520   typedef SignalV2< void ( TextInput textInput ) > InputSignalV2;
521
522   // Input style changed signal
523   typedef SignalV2< void ( TextInput textInput, const TextStyle& style ) > StyleChangedSignalV2;
524
525   // Max input characters reached signal
526   typedef SignalV2< void ( TextInput textInput ) > MaxInputCharactersReachedSignalV2;
527
528   // Input text exceeds boundaries signal
529   typedef SignalV2< void ( TextInput textInput ) > InputTextExceedBoundariesSignalV2;
530
531   /**
532    * Signal emitted when the Text-Input starts receiving input.
533    */
534   InputSignalV2& InputStartedSignal();
535
536   /**
537    * Signal emitted when the Text-Input is finished receiving input.
538    * TextInput::GetText() can be called to get current text string.
539    */
540   InputSignalV2& InputFinishedSignal();
541
542   /**
543    * Signal emitted when the cut and paste toolbar is displayed.
544    */
545   InputSignalV2& CutAndPasteToolBarDisplayedSignal();
546
547   /**
548    * Signal emitted when style changes.
549    */
550   StyleChangedSignalV2& StyleChangedSignal();
551
552   /**
553    * Signal emitted when max input characters are reached during text input.
554    */
555   MaxInputCharactersReachedSignalV2& MaxInputCharactersReachedSignal();
556
557   /**
558    * Signal emitted when input text exceeds the boundaries of the text-input.
559    */
560   InputTextExceedBoundariesSignalV2& InputTextExceedBoundariesSignal();
561
562 public: // Not intended for application developers
563
564   /**
565    * Creates a handle using the Toolkit::Internal implementation.
566    * @param[in]  implementation  The Control implementation.
567    */
568   TextInput(Internal::TextInput& implementation);
569
570   /**
571    * Allows the creation of this Control from an Internal::CustomActor pointer.
572    * @param[in]  internal  A pointer to the internal CustomActor.
573    */
574   TextInput(Dali::Internal::CustomActor* internal );
575 };
576
577 } // namespace Toolkit
578
579 } // namespace Dali
580
581 /**
582  * @}
583  */
584 #endif // __DALI_TOOLKIT_TEXT_INPUT_H__