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_TOOLKIT_TEXT_INPUT_MODULE
26 #include <dali-toolkit/public-api/controls/text-view/text-view.h>
28 namespace Dali DALI_IMPORT_API
34 namespace Internal DALI_INTERNAL
40 * @brief 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; ///< name "start-input"
51 static const char* const SIGNAL_END_INPUT; ///< name "end-input"
52 static const char* const SIGNAL_STYLE_CHANGED; ///< name "style-changed"
53 static const char* const SIGNAL_MAX_INPUT_CHARACTERS_REACHED; ///< name "max-input-characters-reached"
54 static const char* const SIGNAL_TOOLBAR_DISPLAYED; ///< name "toolbar-displayed"
55 static const char* const SIGNAL_TEXT_EXCEED_BOUNDARIES; ///< name "text-exceed-boundaries"
60 * @brief Create an uninitialized TextInput; this can be initialized with TextView::New().
62 * Calling member functions with an uninitialized Dali::Object is not allowed.
67 * @brief Copy constructor.
69 * @param handle to be copied
71 TextInput( const TextInput& handle );
74 * @brief Assignment operator.
76 * @param handle to object we want to point to
77 * @return handle to the TextInput
79 TextInput& operator=( const TextInput& handle );
82 * @brief Create an initialised TextInput.
84 * @return A handle to a newly allocated Dali resource.
86 static TextInput New();
89 * @brief Downcast an Object handle to TextInput.
91 * If handle points to a TextInput the downcast produces valid
92 * handle. If not the returned handle is left uninitialized.
94 * @param[in] handle Handle to an object
95 * @return handle to a TextInput or an uninitialized handle
97 static TextInput DownCast( BaseHandle handle );
100 * @brief Virtual destructor.
102 * Dali::Object derived classes typically do not contain member data.
104 virtual ~TextInput();
107 * @brief Get the inputed text currently being displayed.
109 * @return string, the currently displayed string.
111 std::string GetText() const;
114 * @brief Get the inputed text currently being displayed together with mark-up tags.
116 * @return string, the currently displayed string with mark-up.
118 std::string GetMarkupText() const;
121 * @brief Set the maximum number of characters for the Text Input.
123 * @param [in] maxChars the max number of characters
125 void SetMaxCharacterLength(std::size_t maxChars);
128 * @brief Limits the number of lines of text Text Input will display.
130 * @param [in] maxLines the max number of lines to display, must be greater than 0.
131 * Currently the only valid limit is 1. Which turns TextInput into Single line mode. Any number higher than 1 results in no limit.
133 void SetNumberOfLinesLimit(std::size_t maxLines);
136 * @brief Returns the limit of lines Text Input is allowed to display.
138 * @return max line number limit
140 std::size_t GetNumberOfLinesLimit() const;
143 * @brief Returns the number of characters TextInput is displaying.
145 * @return number of characters
147 std::size_t GetNumberOfCharacters() const;
150 * @brief Sets a place holder text to be displayed when the text-input is empty.
152 * If not set or set to an empty string then no place holder will be shown.
153 * @param [in] placeHolderText text to be used as place holder.
155 void SetPlaceholderText( const std::string& placeHolderText );
158 * @return the current set place holder text, empty string returned if not set.
160 std::string GetPlaceholderText();
163 * @brief set initial text to be displayed in text-input.
165 * Can be used to edit a pre-existing string.
166 * @param [in] initialText text to be initially displayed
168 void SetInitialText(const std::string& initialText);
171 * @brief Manual method to set the focus on the TextInput so it starts or stops edit state.
173 * @pre The text input actor has been initialised.
174 * @param[in] editMode true or false to indicate editMode on or off
176 void SetEditable(bool editMode);
179 * @see SetEditable(bool editMode).
181 * It sets the cursor in the closest character to the given touch point.
183 * @param[in] editMode true or false to indicate editMode on or off
184 * @param[in] touchPoint A position in actor coordinates within the text-input.
186 void SetEditable(bool editMode, const Vector2& touchPoint);
189 * @brief Check if TextInput is in edit state.
191 * @pre The text input actor has been initialised.
192 * @return True or False to indicate editMode on or off
194 bool IsEditable() const;
197 * @brief Method to enable or disable edit on touch/tap.
199 * If not enabled (set to false) then SetEditable(true) will be used to start edit mode.
200 * @pre The text input actor has been initialised.
201 * @param[in] editOnTouch true or false to indicate if editing should start on touch
202 * default is for editing to start on touching textinput
204 void SetEditOnTouch(bool editOnTouch = true);
207 * @brief Check if TextInput starts edit mode on touch.
209 * @pre The text input actor has been initialised.
210 * @return True or False to indicate editOnTouch on or off
212 bool IsEditOnTouch() const;
215 * @brief Check if Text Selection is enabled so required text can be highlighted.
217 * @pre The text input actor has been initialised.
218 * @param[in] textSelectable true or false to indicate if text can be selected or not
219 * default is for text to be select-able when in edit mode
221 void SetTextSelectable(bool textSelectable = true);
224 * @brief Check if Text can be selected.
226 * @pre The text input actor has been initialised.
227 * @return True or False to indicate if text can be selected or not
229 bool IsTextSelectable() const;
232 * @brief Check if any text is currently selected, can be used to determine if ApplyStyle or SetActiveStyle should be used.
234 * @pre The text input actor has been initialised.
235 * @return True if text selected else False
237 bool IsTextSelected() const;
240 * @brief Selects text between the given positions.
242 * @pre TextInput should be in edit mode.
243 * @param start position to start selection
244 * @param end position to end selection, inclusive of this character.
245 * Providing 0 and result from GetNumberOfCharacters() will select all text.
247 void SelectText(std::size_t start, std::size_t end);
250 * @brief If any text is selected then de-select it and hide highlight.
252 * @pre The text input actor has been initialised.
257 * @brief Set the image to be used as the cursor grab hander.
259 * @pre The text input actor has been initialised.
260 * @param[in] image The image to be used.
262 void SetGrabHandleImage( Image image );
265 * @brief Set the image to be used for the regular left to right cursor.
267 * @pre The text input actor has been initialised.
268 * @param[in] image The image to be used.
269 * @param[in] border The nine patch border for the image.
271 void SetCursorImage(Dali::Image image, const Vector4& border );
274 * @brief Retrieve the selection handle size.
276 * Both handles have same size.
277 * @return Vector3 the selection handle size.
279 Vector3 GetSelectionHandleSize();
282 * @brief Set the image to be used for the Right to Left cursor.
284 * @pre The text input actor has been initialised.
285 * @param[in] image The image to be used.
286 * @param[in] border The nine patch border for the image.
288 void SetRTLCursorImage(Dali::Image image, const Vector4& border );
291 * @brief Toggle to enable the grab handle, used to position cursor when magnifier not being used.
293 * Default behaviour is to use the magnifier to position the cursor, enabling this prevents the magnifier from being shown.
294 * @param[in] toggle true to enable, false to disable grab handle
296 void EnableGrabHandle(bool toggle);
299 * @brief Method to check if grab handle is enabled, if false then the magnifier will be used to position cursor.
301 * @return bool returns true is grab handle enabled.
303 bool IsGrabHandleEnabled();
306 * @brief Set the bounding rectangle which handles, popup and similar decorations will not exceed.
308 * The default value is the width and height of the stage from the top left origin.
309 * If a title bar for example is on the top of the screen then the y should be the title's height and
310 * the boundary height the stage height minus the title's height.
311 * Restrictions - The boundary box should be set up with a fixed z position for the text-input and the default camera.
312 * @param[in] boundingOriginAndSize Rect( x coordinate, y coordinate, width, height )
313 * ------------------------------------------
315 * |o---------------------------------------|
317 * || Bounding Box || boundary height
319 * |----------------------------------------|
320 * ------------------------------------------
323 void SetBoundingRectangle( const Rect<float>& boundingOriginAndSize );
326 * @brief Retrieve the bounding box origin and dimensions.
328 * default is set once control is added to stage, before this the return vector will be Vector4:ZERO
329 * @return Rect the bounding rectangle
331 const Rect<float> GetBoundingRectangle() const;
334 * @brief Sets the style for new text being typed.
336 * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
337 * @pre The text input actor has been initialised.
338 * @param[in] style The style for the new text.
339 * @param[in] mask The bit mask.
341 void SetActiveStyle( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
344 * @brief Applies the given style to the selected text.
346 * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
347 * Introduced text after this call uses the new style.
348 * @param[in] style The given style.
349 * @param[in] mask The bit mask.
351 void ApplyStyle( const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
354 * @brief 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 * @brief Get the style of the Text character before the cursor.
365 * If no character before then return the InputStyle.
366 * @return TextStyle, the style of the character before the cursor
368 TextStyle GetStyleAtCursor() const;
371 * @brief Set the current text alignment (overrides default setting).
373 * The default alignment is dependent on the current text in the text field.
374 * If the text begins using LTR characters (e.g. European text) then the
375 * alignment is HorizontalLeft. If the text begins using RTL characters
376 * (e.g. Hebrew/Arabic text) then the alignment is HorizontalRight.
377 * If there is no text, then the alignment defaults to:
378 * (HorizontalLeft | VerticalCenter)
379 * @param[in] align The new alignment option.
381 void SetTextAlignment( Toolkit::Alignment::Type align );
384 * @brief Set the current line justification. (overrides default setting).
386 * The default justification is dependent on the current text in the text field.
387 * If the text begins using LTR characters (e.g. European text) then the
388 * justification is HorizontalLeft. If the text begins using RTL characters
389 * (e.g. Hebrew/Arabic text) then the justification is HorizontalRight.
390 * If there is no text, then the justification defaults to:
391 * (HorizontalLeft | VerticalCenter)
392 * @param[in] justification The new line justification.
394 void SetTextLineJustification( Toolkit::TextView::LineJustification justification );
397 * @brief Sets a fade boundary.
399 * @see TextView::FadeBoundary.
401 * @param[in] fadeBoundary The given fade boundary.
403 void SetFadeBoundary( const Toolkit::TextView::FadeBoundary& fadeBoundary );
406 * @brief Retrieves the fade boundary.
408 * @see TextView::FadeBoundary.
410 * @return The fade boundary.
412 const Toolkit::TextView::FadeBoundary& GetFadeBoundary() const;
415 * @brief Get the current text alignment combined into a single value.
417 * The values can be tested by using the & operator
418 * and the desired flag. e.g. if (GetTextAlignment() & HorizontalCentre) ...
419 * @return The combined text alignment
421 Toolkit::Alignment::Type GetTextAlignment() const;
424 * @brief Sets how to split the text in lines policy.
426 * @param policy The multi-line policy.
428 void SetMultilinePolicy( Toolkit::TextView::MultilinePolicy policy );
431 * @brief Gets the split in lines policy.
433 * @return The multi-line policy.
435 Toolkit::TextView::MultilinePolicy GetMultilinePolicy() const;
438 * @brief Sets how to display the text inside the TextView when it exceeds the text-view's width.
440 * @param policy The exceed policy.
442 void SetWidthExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
445 * @brief Gets the width exceed policy.
447 * @return The exceed policy.
449 TextView::ExceedPolicy GetWidthExceedPolicy() const;
452 * @brief Sets how to display the text inside the TextView when it exceeds the text-view's height.
454 * @param policy The exceed policy.
456 void SetHeightExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
459 * @brief Gets the height exceed policy.
461 * @return The exceed policy.
463 TextView::ExceedPolicy GetHeightExceedPolicy() const;
466 * @brief Sets if the inputed text can exceed the text-input boundary.
468 * By default is enabled.
470 * @param[in] enable Whether the inputed text can exceed its boundary.
472 void SetExceedEnabled( bool enable );
475 * @brief Retrieves whether inputed text can exceed the text-input boundary.
477 * @return \e true if text inputed can exceed the boundary, otherwise \e false.
479 bool GetExceedEnabled() const;
482 * @brief Allows modification of text-actor's position in the depth sort algorithm.
484 * @see Dali::RenderableActor::SetSortModifier()
485 * @param [in] depthOffset the offset to be given to the internal text-actors. Positive values pushing it further back.
487 void SetSortModifier( float depthOffset );
490 * @brief Sets whether text-view renders text using a previously generated snapshot.
492 * @see TextView::SetSnapshotModeEnabled()
494 * @param[in] enable Whether text-view is using or not a snapshot to render text.
496 void SetSnapshotModeEnabled( bool enable );
499 * @brief Retrieves whether text-view is using a snapshot to render text.
501 * @see TextView::IsSnapshotModeEnabled()
503 * @return \e true if text-view is using a snapshot to render text, otherwhise it returns \e false.
505 bool IsSnapshotModeEnabled() const;
508 * @copydoc TextView::SetScrollEnabled()
510 void SetScrollEnabled( bool enable );
513 * @copydoc TextView::IsScrollEnabled()
515 bool IsScrollEnabled() const;
518 * @copydoc TextView::SetScrollPosition()
520 void SetScrollPosition( const Vector2& position );
523 * @copydoc TextView::GetScrollPosition()
525 Vector2 GetScrollPosition() const;
528 * @brief Sets whether markup processing should be carried out.
530 * @param[in] enable whether markup processing is carried out or not.
532 void SetMarkupProcessingEnabled( bool enable );
535 * @brief Returns whether markup processing is enabled or not
537 * @return true is markup processing is enabled
539 bool IsMarkupProcessingEnabled() const;
542 public: /* Signals */
544 /// @brief Input Signal.
545 typedef SignalV2< void ( TextInput textInput ) > InputSignalV2;
547 /// @brief Input style changed signal.
548 typedef SignalV2< void ( TextInput textInput, const TextStyle& style ) > StyleChangedSignalV2;
550 /// @brief Text modified signal.
551 typedef SignalV2< void ( TextInput textInput ) > TextModifiedSignalType;
553 /// @brief Max input characters reached signal.
554 typedef SignalV2< void ( TextInput textInput ) > MaxInputCharactersReachedSignalV2;
556 /// @brief Input text exceeds boundaries signal.
557 typedef SignalV2< void ( TextInput textInput ) > InputTextExceedBoundariesSignalV2;
560 * @brief Signal emitted when the Text-Input starts receiving input.
562 InputSignalV2& InputStartedSignal();
565 * @brief Signal emitted when the Text-Input is finished receiving input.
567 * TextInput::GetText() can be called to get current text string.
568 * @return The signal to connect to
570 InputSignalV2& InputFinishedSignal();
573 * @brief Signal emitted when the cut and paste toolbar is displayed.
575 * @return The signal to connect to
577 InputSignalV2& CutAndPasteToolBarDisplayedSignal();
580 * @brief Signal emitted when style changes.
582 * @return The signal to connect to
584 StyleChangedSignalV2& StyleChangedSignal();
587 * @brief Signal emitted when text changes.
589 * @return The signal to connect to.
591 TextModifiedSignalType& TextModifiedSignal();
594 * @brief Signal emitted when max input characters are reached during text input.
596 * @return The signal to connect to
598 MaxInputCharactersReachedSignalV2& MaxInputCharactersReachedSignal();
601 * @brief Signal emitted when input text exceeds the boundaries of the text-input.
603 * @return The signal to connect to
605 InputTextExceedBoundariesSignalV2& InputTextExceedBoundariesSignal();
607 public: // Not intended for application developers
610 * @brief Creates a handle using the Toolkit::Internal implementation.
612 * @param[in] implementation The Control implementation.
614 TextInput(Internal::TextInput& implementation);
617 * @brief Allows the creation of this Control from an Internal::CustomActor pointer.
619 * @param[in] internal A pointer to the internal CustomActor.
621 TextInput(Dali::Internal::CustomActor* internal );
624 } // namespace Toolkit
631 #endif // __DALI_TOOLKIT_TEXT_INPUT_H__