1 #ifndef __DALI_TOOLKIT_TEXT_INPUT_H__
2 #define __DALI_TOOLKIT_TEXT_INPUT_H__
5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
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
11 // http://floralicense.org/license/
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.
21 * @addtogroup CAPI_DALI_FRAMEWORK
26 #include <dali-toolkit/public-api/controls/text-view/text-view.h>
28 namespace Dali DALI_IMPORT_API
34 namespace Internal DALI_INTERNAL
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
44 class TextInput : public Control
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;
60 * Create an uninitialized TextInput; this can be initialized with TextView::New()
61 * Calling member functions with an uninitialized Dali::Object is not allowed.
67 * @param handle to be copied
69 TextInput( const TextInput& handle );
72 * Assignment operator.
73 * @param handle to object we want to point to
74 * @return handle to the TextInput
76 TextInput& operator=( const TextInput& handle );
79 * Create an initialised TextInput.
80 * @return A handle to a newly allocated Dali resource.
82 static TextInput New();
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
90 static TextInput DownCast( BaseHandle handle );
94 * Dali::Object derived classes typically do not contain member data.
99 * Get the inputed text currently being displayed.
100 * @return string, the currently displayed string.
102 std::string GetText() const;
105 * Get the inputed text currently being displayed together with mark-up tags.
106 * @return string, the currently displayed string with mark-up.
108 std::string GetMarkupText() const;
111 * Set the maximum number of characters for the Text Input
112 * @param [in] maxChars the max number of characters
114 void SetMaxCharacterLength(std::size_t maxChars);
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.
121 void SetNumberOfLinesLimit(std::size_t maxLines);
124 * Returns the limit of lines Text Input is allowed to display.
125 * @return max line number limit
127 std::size_t GetNumberOfLinesLimit() const;
130 * Returns the number of characters TextInput is displaying.
131 * @return number of characters
133 std::size_t GetNumberOfCharacters() const;
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.
140 void SetPlaceholderText( const std::string& placeHolderText );
143 * @return the current set place holder text, empty string returned if not set.
145 std::string GetPlaceholderText();
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
152 void SetInitialText(const std::string& initialText);
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
159 void SetEditable(bool editMode);
162 * @see SetEditable(bool editMode).
164 * It sets the cursor in the closest character to the given touch point.
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.
169 void SetEditable(bool editMode, const Vector2& touchPoint);
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
176 bool IsEditable() const;
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
185 void SetEditOnTouch(bool editOnTouch = true);
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
192 bool IsEditOnTouch() const;
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
200 void SetTextSelectable(bool textSelectable = true);
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
207 bool IsTextSelectable() const;
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
214 bool IsTextSelected() const;
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.
223 void SelectText(std::size_t start, std::size_t end);
226 * If any text is selected then de-select it and hide highlight.
227 * @pre The text input actor has been initialised.
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.
236 void SetGrabHandleImage( Image image );
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.
244 void SetCursorImage(Dali::Image image, const Vector4& border );
247 * Retrieve the selection handle size. Both handles have same size.
248 * @return Vector3 the selection handle size.
250 Vector3 GetSelectionHandleSize();
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.
258 void SetRTLCursorImage(Dali::Image image, const Vector4& border );
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
265 void EnableGrabHandle(bool toggle);
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.
271 bool IsGrabHandleEnabled();
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.
277 /* @deprecated, handles always flip. Use SetBoundingRectangle */
278 void EnableSelectionHandleFlip( bool toggle );
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.
284 /* @deprecated, handles always flip. Use SetBoundingRectangle */
285 bool IsSelectionHandleFlipEnabled();
288 * Set the selection handle filp margin.
289 * The default value is Vector4(0, 0, 0, 0)
290 * ------------------------------------------
292 * | ---------------------------------- |
294 * | x | Text Input | z |
296 * | ---------------------------------- |
298 * ------------------------------------------
300 /* @deprecated, use SetBoundingRectangle instead. */
301 void SetSelectionHandleFlipMargin( const Vector4& margin );
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 * ------------------------------------------
312 * |o---------------------------------------|
314 * || Bounding Box || boundary height
316 * |----------------------------------------|
317 * ------------------------------------------
320 void SetBoundingRectangle( const Rect<float>& boundingOriginAndSize );
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
327 const Rect<float> GetBoundingRectangle() const;
330 * Retrieve the selection handle filp margin.
331 * @return Vector4 the selection handle flip margin.
333 /* @deprecated, use GetBoundingRectangle instead. */
334 const Vector4& GetSelectionHandleFlipMargin();
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.
343 void SetActiveStyle( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
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.
352 void ApplyStyle( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
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.
360 void ApplyStyleToAll( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
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
367 TextStyle GetStyleAtCursor() const;
370 * Set the current text alignment (overrides default setting)
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.
380 void SetTextAlignment( Toolkit::Alignment::Type align );
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.
392 void SetTextLineJustification( Toolkit::TextView::LineJustification justification );
395 * Sets a fade boundary.
397 * @see TextView::FadeBoundary.
399 * @param[in] fadeBoundary The given fade boundary.
401 void SetFadeBoundary( const Toolkit::TextView::FadeBoundary& fadeBoundary );
404 * Retrieves the fade boundary.
406 * @see TextView::FadeBoundary.
408 * @return The fade boundary.
410 const Toolkit::TextView::FadeBoundary& GetFadeBoundary() const;
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) ...
417 Toolkit::Alignment::Type GetTextAlignment() const;
420 * Sets how to split the text in lines policy.
421 * @param policy The multi-line policy.
423 void SetMultilinePolicy( Toolkit::TextView::MultilinePolicy policy );
426 * Gets the split in lines policy.
427 * @return The multi-line policy.
429 Toolkit::TextView::MultilinePolicy GetMultilinePolicy() const;
432 * Sets how to display the text inside the TextView when it exceeds the text-view's width.
433 * @param policy The exceed policy.
435 void SetWidthExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
438 * Gets the width exceed policy.
439 * @return The exceed policy.
441 TextView::ExceedPolicy GetWidthExceedPolicy() const;
444 * Sets how to display the text inside the TextView when it exceeds the text-view's height.
445 * @param policy The exceed policy.
447 void SetHeightExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
450 * Gets the height exceed policy.
451 * @return The exceed policy.
453 TextView::ExceedPolicy GetHeightExceedPolicy() const;
456 * Sets if the inputed text can exceed the text-input boundary.
458 * By default is enabled.
460 * @param[in] enable Whether the inputed text can exceed its boundary.
462 void SetExceedEnabled( bool enable );
465 * Retrieves whether inputed text can exceed the text-input boundary.
467 * @return \e true if text inputed can exceed the boundary, otherwise \e false.
469 bool GetExceedEnabled() const;
472 * Allows modification of text-actor's position in the depth sort algorithm.
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.
477 void SetSortModifier( float depthOffset );
480 * Sets whether text-view renders text using a previously generated snapshot.
482 * @see TextView::SetSnapshotModeEnabled()
484 * @param[in] enable Whether text-view is using or not a snapshot to render text.
486 void SetSnapshotModeEnabled( bool enable );
489 * Retrieves whether text-view is using a snapshot to render text
491 * @see TextView::IsSnapshotModeEnabled()
493 * @return \e true if text-view is using a snapshot to render text, otherwhise it returns \e false.
495 bool IsSnapshotModeEnabled() const;
498 * @copydoc TextView::SetScrollEnabled()
500 void SetScrollEnabled( bool enable );
503 * @copydoc TextView::IsScrollEnabled()
505 bool IsScrollEnabled() const;
508 * @copydoc TextView::SetScrollPosition()
510 void SetScrollPosition( const Vector2& position );
513 * @copydoc TextView::GetScrollPosition()
515 Vector2 GetScrollPosition() const;
517 public: /* Signals */
520 typedef SignalV2< void ( TextInput textInput ) > InputSignalV2;
522 // Input style changed signal
523 typedef SignalV2< void ( TextInput textInput, const TextStyle& style ) > StyleChangedSignalV2;
525 // Max input characters reached signal
526 typedef SignalV2< void ( TextInput textInput ) > MaxInputCharactersReachedSignalV2;
528 // Input text exceeds boundaries signal
529 typedef SignalV2< void ( TextInput textInput ) > InputTextExceedBoundariesSignalV2;
532 * Signal emitted when the Text-Input starts receiving input.
534 InputSignalV2& InputStartedSignal();
537 * Signal emitted when the Text-Input is finished receiving input.
538 * TextInput::GetText() can be called to get current text string.
540 InputSignalV2& InputFinishedSignal();
543 * Signal emitted when the cut and paste toolbar is displayed.
545 InputSignalV2& CutAndPasteToolBarDisplayedSignal();
548 * Signal emitted when style changes.
550 StyleChangedSignalV2& StyleChangedSignal();
553 * Signal emitted when max input characters are reached during text input.
555 MaxInputCharactersReachedSignalV2& MaxInputCharactersReachedSignal();
558 * Signal emitted when input text exceeds the boundaries of the text-input.
560 InputTextExceedBoundariesSignalV2& InputTextExceedBoundariesSignal();
562 public: // Not intended for application developers
565 * Creates a handle using the Toolkit::Internal implementation.
566 * @param[in] implementation The Control implementation.
568 TextInput(Internal::TextInput& implementation);
571 * Allows the creation of this Control from an Internal::CustomActor pointer.
572 * @param[in] internal A pointer to the internal CustomActor.
574 TextInput(Dali::Internal::CustomActor* internal );
577 } // namespace Toolkit
584 #endif // __DALI_TOOLKIT_TEXT_INPUT_H__