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 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
11 * http://www.apache.org/licenses/LICENSE-2.0
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.
22 #include <dali-toolkit/public-api/controls/text-view/text-view.h>
30 namespace Internal DALI_INTERNAL
36 * @brief TextInput Actor takes input one character at a time and displays it as a string within an input box.
37 * Characters can be removed from the end of the string until it is empty. A maximum length of displayed string
40 class DALI_IMPORT_API TextInput : public Control
46 * @brief The start and end property ranges for this control.
50 PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
51 PROPERTY_END_INDEX = PROPERTY_START_INDEX + 512 ///< Reserve property indices
55 * @brief An enumeration of properties belonging to the TextInput class.
61 HIGHLIGHT_COLOR = PROPERTY_START_INDEX, // Property, name "highlight-color", type Vector4
62 CUT_AND_PASTE_COLOR, // Property, name "cut-and-paste-bg-color", type Vector4
63 CUT_AND_PASTE_PRESSED_COLOR, // Property, name "cut-and-paste-pressed-color", type Vector4
64 CUT_AND_PASTE_BORDER_COLOR, // Property, name "cut-and-paste-border-color", type Vector4
65 CUT_AND_PASTE_ICON_COLOR, // Property, name "cut-and-paste-icon-color", type Vector4
66 CUT_AND_PASTE_ICON_PRESSED_COLOR, // Property, name "cut-and-paste-icon-pressed-color", type Vector4
67 CUT_AND_PASTE_TEXT_COLOR, // Property, name "cut-and-paste-text-color", type Vector4
68 CUT_AND_PASTE_TEXT_PRESSED_COLOR, // Property, name "cut-and-paste-text-pressed-color", type Vector4
69 CUT_BUTTON_POSITION_PRIORITY, // Property, name "cut-button-position-priority", type unsigned int
70 COPY_BUTTON_POSITION_PRIORITY, // Property, name "copy-button-position-priority", type unsigned int
71 PASTE_BUTTON_POSITION_PRIORITY, // Property, name "paste-button-position-priority", type unsigned int
72 SELECT_BUTTON_POSITION_PRIORITY, // Property, name "select-button-position-priority", type unsigned int
73 SELECT_ALL_BUTTON_POSITION_PRIORITY, // Property, name "select-all-button-position-priority", type unsigned int
74 CLIPBOARD_BUTTON_POSITION_PRIORITY, // Property, name "clipboard-button-position-priority", type unsigned int
75 POP_UP_OFFSET_FROM_TEXT, // Property, name "popup-offset-from-text", type Vector4
76 CURSOR_COLOR, // Property, name "cursor-color", type Vector4
83 * @brief Create an uninitialized TextInput; this can be initialized with TextView::New().
85 * Calling member functions with an uninitialized Dali::Object is not allowed.
90 * @brief Copy constructor.
92 * @param handle to be copied
94 TextInput( const TextInput& handle );
97 * @brief Assignment operator.
99 * @param handle to object we want to point to
100 * @return handle to the TextInput
102 TextInput& operator=( const TextInput& handle );
105 * @brief Create an initialised TextInput.
107 * @return A handle to a newly allocated Dali resource.
109 static TextInput New();
112 * @brief Downcast an Object handle to TextInput.
114 * If handle points to a TextInput the downcast produces valid
115 * handle. If not the returned handle is left uninitialized.
117 * @param[in] handle Handle to an object
118 * @return handle to a TextInput or an uninitialized handle
120 static TextInput DownCast( BaseHandle handle );
125 * This is non-virtual since derived Handle types must not contain data or virtual methods.
130 * @brief Get the inputed text currently being displayed.
132 * @return string, the currently displayed string.
134 std::string GetText() const;
137 * @brief Get the inputed text currently being displayed together with mark-up tags.
139 * @return string, the currently displayed string with mark-up.
141 std::string GetMarkupText() const;
144 * @brief Set the maximum number of characters for the Text Input.
146 * @param [in] maxChars the max number of characters
148 void SetMaxCharacterLength(std::size_t maxChars);
151 * @brief Limits the number of lines of text Text Input will display.
153 * @param [in] maxLines the max number of lines to display, must be greater than 0.
154 * Currently the only valid limit is 1. Which turns TextInput into Single line mode. Any number higher than 1 results in no limit.
156 void SetNumberOfLinesLimit(std::size_t maxLines);
159 * @brief Returns the limit of lines Text Input is allowed to display.
161 * @return max line number limit
163 std::size_t GetNumberOfLinesLimit() const;
166 * @brief Returns the number of characters TextInput is displaying.
168 * @return number of characters
170 std::size_t GetNumberOfCharacters() const;
173 * @brief Sets a place holder text to be displayed when the text-input is empty.
175 * If not set or set to an empty string then no place holder will be shown.
176 * @param [in] placeHolderText text to be used as place holder.
178 void SetPlaceholderText( const std::string& placeHolderText );
181 * @return the current set place holder text, empty string returned if not set.
183 std::string GetPlaceholderText();
186 * @brief set initial text to be displayed in text-input.
188 * Can be used to edit a pre-existing string.
189 * @param [in] initialText text to be initially displayed
191 void SetInitialText(const std::string& initialText);
194 * @brief Manual method to set the focus on the TextInput so it starts or stops edit state.
196 * @pre The text input actor has been initialised.
197 * @param[in] editMode true or false to indicate editMode on or off
199 void SetEditable(bool editMode);
202 * @see SetEditable(bool editMode).
204 * It sets the cursor in the closest character to the given touch point.
206 * @param[in] editMode true or false to indicate editMode on or off
207 * @param[in] touchPoint A position in actor coordinates within the text-input.
209 void SetEditable(bool editMode, const Vector2& touchPoint);
212 * @brief Check if TextInput is in edit state.
214 * @pre The text input actor has been initialised.
215 * @return True or False to indicate editMode on or off
217 bool IsEditable() const;
220 * @brief Method to enable or disable edit on touch/tap.
222 * If not enabled (set to false) then SetEditable(true) will be used to start edit mode.
223 * @pre The text input actor has been initialised.
224 * @param[in] editOnTouch true or false to indicate if editing should start on touch
225 * default is for editing to start on touching textinput
227 void SetEditOnTouch(bool editOnTouch = true);
230 * @brief Check if TextInput starts edit mode on touch.
232 * @pre The text input actor has been initialised.
233 * @return True or False to indicate editOnTouch on or off
235 bool IsEditOnTouch() const;
238 * @brief Check if Text Selection is enabled so required text can be highlighted.
240 * @pre The text input actor has been initialised.
241 * @param[in] textSelectable true or false to indicate if text can be selected or not
242 * default is for text to be select-able when in edit mode
244 void SetTextSelectable(bool textSelectable = true);
247 * @brief Check if Text can be selected.
249 * @pre The text input actor has been initialised.
250 * @return True or False to indicate if text can be selected or not
252 bool IsTextSelectable() const;
255 * @brief Check if any text is currently selected, can be used to determine if ApplyStyle or SetActiveStyle should be used.
257 * @pre The text input actor has been initialised.
258 * @return True if text selected else False
260 bool IsTextSelected() const;
263 * @brief Selects text between the given positions.
265 * @pre TextInput should be in edit mode.
266 * @param start position to start selection
267 * @param end position to end selection, inclusive of this character.
268 * Providing 0 and result from GetNumberOfCharacters() will select all text.
270 void SelectText(std::size_t start, std::size_t end);
273 * @brief If any text is selected then de-select it and hide highlight.
275 * @pre The text input actor has been initialised.
280 * @brief Set the image to be used as the cursor grab hander.
282 * @pre The text input actor has been initialised.
283 * @param[in] image The image to be used.
285 void SetGrabHandleImage( Image image );
289 * @brief Set the image to be used for the regular left to right cursor.
291 * @pre The text input actor has been initialised.
292 * @param[in] image The image to be used.
293 * @param[in] border The nine patch border for the image.
295 void SetCursorImage(Dali::Image image, const Vector4& border );
298 * @brief Retrieve the selection handle size.
300 * Both handles have same size.
301 * @return Vector3 the selection handle size.
303 Vector3 GetSelectionHandleSize();
306 * @brief Set the image to be used for the Right to Left cursor.
308 * @pre The text input actor has been initialised.
309 * @param[in] image The image to be used.
310 * @param[in] border The nine patch border for the image.
312 void SetRTLCursorImage(Dali::Image image, const Vector4& border );
315 * @brief Toggle to enable the grab handle, used to position cursor when magnifier not being used.
317 * Default behaviour is to use the magnifier to position the cursor, enabling this prevents the magnifier from being shown.
318 * @param[in] toggle true to enable, false to disable grab handle
320 void EnableGrabHandle(bool toggle);
323 * @brief Method to check if grab handle is enabled, if false then the magnifier will be used to position cursor.
325 * @return bool returns true is grab handle enabled.
327 bool IsGrabHandleEnabled();
330 * @brief Set the bounding rectangle which handles, popup and similar decorations will not exceed.
332 * The default value is the width and height of the stage from the top left origin.
333 * If a title bar for example is on the top of the screen then the y should be the title's height and
334 * the boundary height the stage height minus the title's height.
335 * Restrictions - The boundary box should be set up with a fixed z position for the text-input and the default camera.
336 * @param[in] boundingOriginAndSize Rect( x coordinate, y coordinate, width, height )
338 * +----------------------------------------+
340 * |+--------------------------------------+|
342 * || Bounding Box || boundary height
344 * |+--------------------------------------+|
345 * +----------------------------------------+
349 void SetBoundingRectangle( const Rect<float>& boundingOriginAndSize );
352 * @brief Retrieve the bounding box origin and dimensions.
354 * default is set once control is added to stage, before this the return vector will be Vector4:ZERO
355 * @return Rect the bounding rectangle
357 const Rect<float> GetBoundingRectangle() const;
360 * @brief Sets the style for new text being typed.
362 * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
363 * @pre The text input actor has been initialised.
364 * @param[in] style The style for the new text.
365 * @param[in] mask The bit mask.
367 void SetActiveStyle( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
370 * @brief Applies the given style to the selected text.
372 * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
373 * Introduced text after this call uses the new style.
374 * @param[in] style The given style.
375 * @param[in] mask The bit mask.
377 void ApplyStyle( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
380 * @brief Applies the given style to all text, selected or not selected.
382 * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
383 * @param[in] style The given style.
384 * @param[in] mask The bit mask.
386 void ApplyStyleToAll( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
389 * @brief Get the style of the Text character before the cursor.
391 * If no character before then return the InputStyle.
392 * @return TextStyle, the style of the character before the cursor
394 TextStyle GetStyleAtCursor() const;
397 * @brief Set the current text alignment (overrides default setting).
399 * The default alignment is dependent on the current text in the text field.
400 * If the text begins using LTR characters (e.g. European text) then the
401 * alignment is HorizontalLeft. If the text begins using RTL characters
402 * (e.g. Hebrew/Arabic text) then the alignment is HorizontalRight.
403 * If there is no text, then the alignment defaults to:
404 * (HorizontalLeft | VerticalCenter)
405 * @param[in] align The new alignment option.
407 void SetTextAlignment( Toolkit::Alignment::Type align );
410 * @brief Set the current line justification. (overrides default setting).
412 * The default justification is dependent on the current text in the text field.
413 * If the text begins using LTR characters (e.g. European text) then the
414 * justification is HorizontalLeft. If the text begins using RTL characters
415 * (e.g. Hebrew/Arabic text) then the justification is HorizontalRight.
416 * If there is no text, then the justification defaults to:
417 * (HorizontalLeft | VerticalCenter)
418 * @param[in] justification The new line justification.
420 void SetTextLineJustification( Toolkit::TextView::LineJustification justification );
423 * @brief Sets a fade boundary.
425 * @see TextView::FadeBoundary.
427 * @param[in] fadeBoundary The given fade boundary.
429 void SetFadeBoundary( const Toolkit::TextView::FadeBoundary& fadeBoundary );
432 * @brief Retrieves the fade boundary.
434 * @see TextView::FadeBoundary.
436 * @return The fade boundary.
438 const Toolkit::TextView::FadeBoundary& GetFadeBoundary() const;
441 * @brief Get the current text alignment combined into a single value.
443 * The values can be tested by using the & operator
444 * and the desired flag. e.g. if (GetTextAlignment() & HorizontalCentre) ...
445 * @return The combined text alignment
447 Toolkit::Alignment::Type GetTextAlignment() const;
450 * @brief Sets how to split the text in lines policy.
452 * @param policy The multi-line policy.
454 void SetMultilinePolicy( Toolkit::TextView::MultilinePolicy policy );
457 * @brief Gets the split in lines policy.
459 * @return The multi-line policy.
461 Toolkit::TextView::MultilinePolicy GetMultilinePolicy() const;
464 * @brief Sets how to display the text inside the TextView when it exceeds the text-view's width.
466 * @param policy The exceed policy.
468 void SetWidthExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
471 * @brief Gets the width exceed policy.
473 * @return The exceed policy.
475 TextView::ExceedPolicy GetWidthExceedPolicy() const;
478 * @brief Sets how to display the text inside the TextView when it exceeds the text-view's height.
480 * @param policy The exceed policy.
482 void SetHeightExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
485 * @brief Gets the height exceed policy.
487 * @return The exceed policy.
489 TextView::ExceedPolicy GetHeightExceedPolicy() const;
492 * @brief Sets if the inputed text can exceed the text-input boundary.
494 * By default is enabled.
496 * @param[in] enable Whether the inputed text can exceed its boundary.
498 void SetExceedEnabled( bool enable );
501 * @brief Retrieves whether inputed text can exceed the text-input boundary.
503 * @return \e true if text inputed can exceed the boundary, otherwise \e false.
505 bool GetExceedEnabled() const;
508 * @brief Allows modification of text-actor's position in the depth sort algorithm.
510 * @see Dali::RenderableActor::SetSortModifier()
511 * @param [in] depthOffset the offset to be given to the internal text-actors. Positive values pushing it further back.
513 void SetSortModifier( float depthOffset );
516 * @brief Sets whether text-view renders text using a previously generated snapshot.
518 * @see TextView::SetSnapshotModeEnabled()
520 * @param[in] enable Whether text-view is using or not a snapshot to render text.
522 void SetSnapshotModeEnabled( bool enable );
525 * @brief Retrieves whether text-view is using a snapshot to render text.
527 * @see TextView::IsSnapshotModeEnabled()
529 * @return \e true if text-view is using a snapshot to render text, otherwhise it returns \e false.
531 bool IsSnapshotModeEnabled() const;
534 * @copydoc TextView::SetScrollEnabled()
536 void SetScrollEnabled( bool enable );
539 * @copydoc TextView::IsScrollEnabled()
541 bool IsScrollEnabled() const;
544 * @copydoc TextView::SetScrollPosition()
546 void SetScrollPosition( const Vector2& position );
549 * @copydoc TextView::GetScrollPosition()
551 Vector2 GetScrollPosition() const;
554 * @brief Sets whether markup processing should be carried out.
556 * @param[in] enable whether markup processing is carried out or not.
558 void SetMarkupProcessingEnabled( bool enable );
561 * @brief Returns whether markup processing is enabled or not
563 * @return true is markup processing is enabled
565 bool IsMarkupProcessingEnabled() const;
568 public: /* Signals */
570 /// @brief Input Signal.
571 typedef Signal< void ( TextInput textInput ) > InputSignalType;
573 /// @brief Input style changed signal.
574 typedef Signal< void ( TextInput textInput, const TextStyle& style ) > StyleChangedSignalType;
576 /// @brief Text modified signal.
577 typedef Signal< void ( TextInput textInput ) > TextModifiedSignalType;
579 /// @brief Max input characters reached signal.
580 typedef Signal< void ( TextInput textInput ) > MaxInputCharactersReachedSignalType;
582 /// @brief Input text exceeds boundaries signal.
583 typedef Signal< void ( TextInput textInput ) > InputTextExceedBoundariesSignalType;
586 * @brief Signal emitted when the Text-Input starts receiving input.
588 InputSignalType& InputStartedSignal();
591 * @brief Signal emitted when the Text-Input is finished receiving input.
593 * TextInput::GetText() can be called to get current text string.
594 * @return The signal to connect to
596 InputSignalType& InputFinishedSignal();
599 * @brief Signal emitted when the cut and paste toolbar is displayed.
601 * @return The signal to connect to
603 InputSignalType& CutAndPasteToolBarDisplayedSignal();
606 * @brief Signal emitted when style changes.
608 * @return The signal to connect to
610 StyleChangedSignalType& StyleChangedSignal();
613 * @brief Signal emitted when text changes.
615 * @return The signal to connect to.
617 TextModifiedSignalType& TextModifiedSignal();
620 * @brief Signal emitted when max input characters are reached during text input.
622 * @return The signal to connect to
624 MaxInputCharactersReachedSignalType& MaxInputCharactersReachedSignal();
627 * @brief Signal emitted when input text exceeds the boundaries of the text-input.
629 * @return The signal to connect to
631 InputTextExceedBoundariesSignalType& InputTextExceedBoundariesSignal();
633 public: // Not intended for application developers
636 * @brief Creates a handle using the Toolkit::Internal implementation.
638 * @param[in] implementation The Control implementation.
640 DALI_INTERNAL TextInput(Internal::TextInput& implementation);
643 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
645 * @param[in] internal A pointer to the internal CustomActor.
647 explicit DALI_INTERNAL TextInput(Dali::Internal::CustomActor* internal );
650 } // namespace Toolkit
654 #endif // __DALI_TOOLKIT_TEXT_INPUT_H__