1 #ifndef __DALI_TOOLKIT_INTERNAL_TEXT_INPUT_H__
2 #define __DALI_TOOLKIT_INTERNAL_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 #include <dali-toolkit/public-api/controls/control-impl.h>
22 #include <dali-toolkit/public-api/controls/text-input/text-input.h>
23 #include <dali-toolkit/public-api/controls/text-view/text-view.h>
24 #include <dali-toolkit/public-api/controls/buttons/push-button.h>
25 #include <dali-toolkit/internal/controls/text-input/text-input-popup-impl.h>
27 #include <dali/public-api/common/dali-vector.h>
28 #include <dali/public-api/adaptor-framework/common/imf-manager.h>
29 #include <dali/public-api/geometry/mesh.h>
43 typedef IntrusivePtr<TextInput> TextInputPtr;
45 class TextInput : public ControlImpl
50 * Create a new TextInput
51 * @return instrusive ptr to a TextInput
53 static Dali::Toolkit::TextInput New();
56 * @copydoc Toolkit::TextInput::GetText
58 std::string GetText() const;
61 * @copydoc Toolkit::TextInput::GetMarkupText()
63 std::string GetMarkupText() const;
66 * @copydoc Toolkit::TextInput::SetPlaceholderText
68 void SetPlaceholderText( const std::string& placeHolderText );
71 * @copydoc Toolkit::TextInput::SetPlaceholderText
73 std::string GetPlaceholderText();
76 * @copydoc Toolkit::TextInput::SetInitialText
78 void SetInitialText(const std::string& initialText);
81 * set the text to be displayed in text-input, will overwrite any existing text.
82 * can be used to clear the text-input by passing an empty string.
83 * @param [in] initialText text to be initially displayed
85 void SetText(const std::string& initialText);
88 * @copydoc Toolkit::TextInput::SetMaxCharacterLength
90 void SetMaxCharacterLength(std::size_t maxChars);
93 * @copydoc Toolkit::TextInput::SetNumberOfLinesLimit
95 void SetNumberOfLinesLimit(std::size_t maxLines);
98 * @copydoc Toolkit::TextInput::GetNumberOfLinesLimit
100 std::size_t GetNumberOfLinesLimit() const;
103 * @copydoc Toolkit::TextInput::GetFont
105 Font GetFont() const;
108 * @copydoc Toolkit::TextInput::SetFont
110 void SetFont(Font font);
113 * @copydoc Toolkit::TextInput::InputStartedSignal()
115 Toolkit::TextInput::InputSignalV2& InputStartedSignal();
118 * @copydoc Toolkit::TextInput::InputFinishedSignal()
120 Toolkit::TextInput::InputSignalV2& InputFinishedSignal();
123 * @copydoc Toolkit::TextInput::CutAndPasteToolBarDisplayedSignal()
125 Toolkit::TextInput::InputSignalV2& CutAndPasteToolBarDisplayedSignal();
128 * @copydoc Toolkit::TextInput::StyleChangedSignal()
130 Toolkit::TextInput::StyleChangedSignalV2& StyleChangedSignal();
133 * @copydoc Toolkit::TextInput::MaxInputCharactersReachedSignal()
135 Toolkit::TextInput::MaxInputCharactersReachedSignalV2& MaxInputCharactersReachedSignal();
138 * @copydoc Toolkit::TextInput::InputTextExceedBoundariesSignal()
140 Toolkit::TextInput::InputTextExceedBoundariesSignalV2& InputTextExceedBoundariesSignal();
143 * Connects a callback function with the object's signals.
144 * @param[in] object The object providing the signal.
145 * @param[in] tracker Used to disconnect the signal.
146 * @param[in] signalName The signal to connect to.
147 * @param[in] functor A newly allocated FunctorDelegate.
148 * @return True if the signal was connected.
149 * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
151 static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
154 * @see Toolkit::TextInput::SetEditMode(bool editMode)
155 * @see Toolkit::TextInput::SetEditMode(bool editMode, const Vector2& touchPoint)
157 * @param[in] editMode true or false to indicate editMode on or off.
158 * @param[in] setCursorOnTouchPoint Whether to use the touch point to set the cursor position.
159 * @param[in] touchPoint A position in actor coordinates within the text-input.
161 void SetEditable(bool editMode, bool setCursorOnTouchPoint, const Vector2& touchPoint = Vector2::ZERO);
164 * @copydoc Toolkit::TextInput::GetEditMode
166 bool IsEditable() const;
169 * @copydoc Toolkit::TextInput::SetTextSelectable
171 void SetTextSelectable(bool textSelectable = true);
174 * @copydoc Toolkit::TextInput::IsTextSelectable
176 bool IsTextSelectable() const;
179 * @copydoc Toolkit::TextInput::IsTextSelected
181 bool IsTextSelected() const;
184 * @copydoc Toolkit::TextInput::DeSelectText
189 * @copydoc Toolkit::TextInput::SetEditOnTouch
191 void SetEditOnTouch(bool editOnTouch);
194 * @copydoc Toolkit::TextInput::IsEditOnTouch
196 bool IsEditOnTouch() const;
199 * @copydoc Toolkit::TextInput::SetGrabHandleImage
201 void SetGrabHandleImage(Dali::Image image);
204 * @copydoc Toolkit::TextInput::SetCursorImage
206 void SetCursorImage(Dali::Image image, const Vector4& border );
209 * @copydoc Toolkit::TextInput::GetSelectionHandleSize
211 Vector3 GetSelectionHandleSize();
214 * @copydoc Toolkit::TextInput::SetRTLCursorImage
216 void SetRTLCursorImage(Dali::Image image, const Vector4& border );
219 * @copydoc Toolkit::TextInput::EnableGrabHandle
221 void EnableGrabHandle(bool toggle);
224 * @copydoc Toolkit::TextInput::IsGrabHandleEnabled
226 bool IsGrabHandleEnabled();
229 * @copydoc Toolkit::TextInput::EnableSelectionHandleFlip
231 void EnableSelectionHandleFlip( bool toggle );
234 * @copydoc Toolkit::TextInput::IsSelectionHandleFlipEnabled
236 bool IsSelectionHandleFlipEnabled();
239 * @copydoc Toolkit::TextInput::SetSelectionHandleFlipMargin
241 void SetSelectionHandleFlipMargin( const Vector4& margin );
244 * @copydoc Toolkit::TextInput::SetBoundingRectangle
246 void SetBoundingRectangle( const Rect<float>& boundingRectangle );
249 * @copydoc Toolkit::TextInput::GetBoundingRectangle
251 const Rect<float> GetBoundingRectangle() const;
254 * @copydoc Toolkit::TextInput::GetSelectionHandleFlipMargin
256 const Vector4& GetSelectionHandleFlipMargin();
259 * @copydoc Toolkit::TextInput::SetTextColor
261 void SetTextColor( const Vector4& color );
264 * @copydoc Toolkit::TextInput::SetActiveStyle
266 void SetActiveStyle( const TextStyle& style, const TextStyle::Mask mask );
269 * @copydoc Toolkit::TextInput::ApplyStyle
271 void ApplyStyle( const TextStyle& style, const TextStyle::Mask mask );
274 * @copydoc Toolkit::TextInput::ApplyStyleToAll
276 void ApplyStyleToAll( const TextStyle& style, const TextStyle::Mask mask );
279 * @copydoc Toolkit::TextInput::GetStyleAtCursor
281 TextStyle GetStyleAtCursor() const;
284 * Retrieves the character style for the given position.
285 * @param[in] position The character position which style is required.
286 * @return The style for the given position.
288 TextStyle GetStyleAt( std::size_t position ) const;
291 * @copydoc Toolkit::TextInput::SetTextAlignment()
293 void SetTextAlignment( Toolkit::Alignment::Type align );
296 * @copydoc Toolkit::TextInput::SetTextLineJustification()
298 void SetTextLineJustification( Toolkit::TextView::LineJustification justification );
301 * @copydoc Toolkit::TextInput::SetFadeBoundary()
303 void SetFadeBoundary( const Toolkit::TextView::FadeBoundary& fadeBoundary );
306 * @copydoc Toolkit::TextInput::GetFadeBoundary()
308 const Toolkit::TextView::FadeBoundary& GetFadeBoundary() const;
311 * @copydoc Toolkit::TextInput::GetTextAlignment()
313 Toolkit::Alignment::Type GetTextAlignment() const;
316 * @copydoc Toolkit::TextInput::SetMultilinePolicy()
318 void SetMultilinePolicy( Toolkit::TextView::MultilinePolicy policy );
321 * @copydoc Toolkit::TextInput::GetMultilinePolicy()
323 Toolkit::TextView::MultilinePolicy GetMultilinePolicy() const;
326 * @copydoc Toolkit::TextInput::SetWidthExceedPolicy()
328 void SetWidthExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
331 * @copydoc Toolkit::TextInput::GetWidthExceedPolicy()
333 Toolkit::TextView::ExceedPolicy GetWidthExceedPolicy() const;
336 * @copydoc Toolkit::TextInput::SetHeightExceedPolicy()
338 void SetHeightExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
341 * @copydoc Toolkit::TextInput::GetHeightExceedPolicy()
343 Toolkit::TextView::ExceedPolicy GetHeightExceedPolicy() const;
346 * @copydoc Toolkit::TextInput::SetExceedEnabled()
348 void SetExceedEnabled( bool enable );
351 * @copydoc Toolkit::TextInput::GetExceedEnabled()
353 bool GetExceedEnabled() const;
356 * @copydoc Toolkit::TextInput::SetBackground
358 void SetBackground(Dali::Image image );
361 * @copydoc Toolkit::TextInput::SetNumberOfLines
363 void SetNumberOfLines(std::size_t lines);
366 * @copydoc Toolkit::TextInput::GetNumberOfLines
368 std::size_t GetNumberOfLines();
371 * @copydoc Toolkit::TextInput::GetNumberOfCharacters
373 std::size_t GetNumberOfCharacters() const;
378 * structure to hold each highlight box needed for text selection
382 Vector3 size; ///< size of the highlight box
383 Vector3 position; ///< position of highlight box
384 ImageActor highlightBoxActor; ///< as actor that is the highlight box
388 * structure to hold each character in displayed string and its position from the left
392 char character; ///< todo change to UTF to aid multi-language support
398 * structure to hold coordinates of each quad, which will make up the mesh.
400 struct QuadCoordinates
403 * Default constructor
411 * @param[in] x1 left co-ordinate
412 * @param[in] y1 top co-ordinate
413 * @param[in] x2 right co-ordinate
414 * @param[in] y2 bottom co-ordinate
416 QuadCoordinates(float x1, float y1, float x2, float y2)
422 Vector2 min; ///< top-left (minimum) position of quad
423 Vector2 max; ///< bottom-right (maximum) position of quad
426 typedef std::vector<QuadCoordinates> QuadContainer;
429 * structure for information required to build the highlight mesh
434 * Adds a Quad (2D rectangular sub-selection)
435 * @param[in] x1 left co-ordinate
436 * @param[in] y1 top co-ordinate
437 * @param[in] x2 right co-ordinate
438 * @param[in] y2 bottom co-ordinate
440 void AddQuad( float x1, float y1, float x2, float y2 );
443 * Clamps all quads to fit within a min -> max 2D boundary.
445 void Clamp2D(const Vector2& min, const Vector2& max);
447 QuadContainer mQuadList; ///< List of quads (sub-selections that form to create complete selection)
451 * Holds requested selection start and end points for highlighted text.
453 struct SelectionParameters
455 SelectionParameters( size_t start, size_t end )
456 : mStartOfSelection( start ), mEndOfSelection( end )
461 size_t mStartOfSelection;
462 size_t mEndOfSelection;
471 enum SelectionHandleId
473 HandleOne, ///< Selection handle one which is on the left
474 HandleTwo ///< Selection handle two which is on the right
478 * Two different behaviours are needed to convert a touch point into a character index.
479 * When a tap is received and the touch point doesn't hit any character, the final character selected might
480 * be different than the one selected if the event is a pan.
481 * i.e. If a tap is received and the touch point doesn't hit any character the expected position of the cursor
482 * would be the end or the beginning of a line. However, this behaviour would be weird while panning.
486 TapMode, ///< Touch point to character index conversion mode used for Tap events.
487 DragMode ///< Touch point to character index conversion mode used for Pan events.
491 * Used to set the direction when find the next visible character.
493 enum FindVisibleCharacterDirection
495 Left, ///< Find visible characters on the left.
496 Right, ///< Find visible characters on the right.
497 ByEnd ///< Start finding visible characters by the end.
503 virtual bool OnTouchEvent(const TouchEvent& event);
506 * From CustomActorImpl; called after the Text Input actor is touched
507 * @param[in] event The KeyEvent event.
508 * @return True if the event should be consumed.
510 virtual bool OnKeyEvent(const KeyEvent& event);
513 * From CustomActorImpl; called when this actor gains keyboard focus.
515 virtual void OnKeyInputFocusGained();
518 * From CustomActorImpl; called when this actor loses keyboard focus.
520 virtual void OnKeyInputFocusLost();
523 * From ControlImpl; called whenever the control is added to the stage.
525 virtual void OnControlStageConnection();
527 private: // From ControlImpl
530 * Creation of the layer that is used by top level active parts of the TextInput like handles
532 void CreateActiveLayer();
535 * @copydoc Toolkit::ControlImpl::OnInitialize()
537 virtual void OnInitialize();
540 * @copydoc Toolkit::ControlImpl::OnControlSizeSet()
542 virtual void OnControlSizeSet(const Vector3& targetSize);
545 * @copydoc Toolkit::ControlImpl::OnRelaidOut()
547 virtual void OnRelaidOut( Vector2 size, ActorSizeContainer& container );
550 * Retrieves the text-input's natural size by calling TextView::GetNaturalSize().
552 * @return The natural size.
554 virtual Vector3 GetNaturalSize();
557 * Retrieves the text-input's \e height for a given \e width by calling TextView::GetHeightForWidth().
559 * @param[in] width The given \e width.
561 * @return The \e height for the given \e width.
563 virtual float GetHeightForWidth( float width );
568 * Construct a new TextInput.
573 * A reference counted object may only be deleted by calling Unreference()
575 virtual ~TextInput();
580 TextInput(const TextInput&);
583 TextInput& operator=(const TextInput& rhs);
586 * Callback when a handle is panned/moved, either selection handles or grab handle
587 * @param actor Handle of the selection or grab handle.
588 * @param gesture Data structure with the parameters of the gesture.
590 void OnHandlePan(Actor actor, PanGesture gesture);
593 * Callback for touch down on Grab handle
594 * @param[in] actor touched
595 * @param[in] touch touch event
597 bool OnPressDown(Dali::Actor actor, const TouchEvent& touch);
600 * Callback for touch down on Selection handle one
601 * @param[in] actor touched
602 * @param[in] touch touch event, used to determine if down or up event
604 bool OnHandleOneTouched(Dali::Actor actor, const TouchEvent& touch);
607 * Callback for touch down on Selection handle two
608 * @param[in] actor touched
609 * @param[in] touch touch event, used to determine if down or up event
611 bool OnHandleTwoTouched(Dali::Actor actor, const TouchEvent& touch);
614 * Callback for tap on TextInput
616 * @param[in] tap touch event
618 void OnTextTap(Dali::Actor actor, Dali::TapGesture tap);
621 * Callback for double tap on TextInput
623 * @param[in] tap touch event
625 void OnDoubleTap(Dali::Actor actor, Dali::TapGesture tap);
628 * Callback for long press on TextInput
630 * @param[in] longPress long press event
632 void OnLongPress(Dali::Actor actor, Dali::LongPressGesture longPress);
635 * Callback for the ClipboardEventNotifier when text is selected in the clipboard window.
636 * @param[in] notifier The Clipboard Event Notifier.
638 void OnClipboardTextSelected( ClipboardEventNotifier& notifier );
641 * Callback for when a button is pressed in popup panel
642 * @param[in] button handle to the button pressed.
644 bool OnPopupButtonPressed( Toolkit::Button button );
647 * Callback when handle timer ticks.
649 * Cursor should become visible/invisible to simulate blinking.
651 * @return True if the timer should be keep running.
653 bool OnCursorBlinkTimerTick();
656 * Invoked upon popup Hide animation completing.
657 * @note Only called for animating hide, not called for instantaneous (animate = false)
658 * @param[in] popup The popup which was hidden.
660 void OnPopupHideFinished(TextInputPopup& popup);
663 * Called in OnKeyEvent to handle key down events.
664 * @param[in] event The KeyEvent event.
665 * @return True if the event should be consumed.
667 bool OnKeyDownEvent(const KeyEvent& event);
670 * Called in OnKeyEvent to handle key up events.
671 * @param[in] event The KeyEvent event.
672 * @return True if the event should be consumed.
674 bool OnKeyUpEvent(const KeyEvent& event);
677 * Callback called when the text-view is scrolled.
679 * Updates the selection and grab handles, and the highlighted text.
681 * @param[in] textView Handle of the text-view.
682 * @param[in] scrollPosition The difference with the previous scroll position.
684 void OnTextViewScrolled( Toolkit::TextView textView, Vector2 scrollPosition );
687 * Scrolls the text-view to make the cursor visible.
689 * @param[in] cursorPosition The actual cursor position in actor coordinates.
691 void ScrollTextViewToMakeCursorVisible( const Vector3& cursorPosition );
694 * Creates and starts a timer to scroll the text when handles are close to the edges of the text-input.
696 * It only starts the timer if it's already created.
698 void StartScrollTimer();
701 * Stops the timer used to scroll the text.
703 void StopScrollTimer();
706 * Callback called by the timer used to scroll the text.
708 * It calculates and sets a new scroll position.
710 bool OnScrollTimerTick();
712 public: // Public to allow internal testing.
715 * Register for touch events
717 void SetUpTouchEvents();
720 * Sets up TextView Actor
722 void CreateTextViewActor();
725 * Set Styled Text for text input.
726 * @param[in] styleText The new styled text for the text input.
728 void SetText( const MarkupProcessor::StyledTextArray& styleText );
731 * Start a timer to signal cursor to blink.
733 void StartCursorBlinkTimer();
736 * Stop the timer signalling the cursor to blink.
738 void StopCursorBlinkTimer();
741 * Starts input, setting focus and showing keyboard..
743 void StartEditMode();
746 * Called when End of input and focus no longer required, keyboard is hidden.
751 * Applies a style to the current pre-edit / predicted word to show it is being edited.
752 * @param[in] preEditStartPosition position in text array that the predicted word starts at
753 * @param[in] preEditStringLength used to calculate how many characters need their style changed.
755 void ApplyPreEditStyle( std::size_t preEditStartPosition, std::size_t preEditStringLength );
758 * Restores style to value before applying Pre-Edit style.
760 void RemovePreEditStyle();
763 * Event received from IMF manager
764 * @return ImfCallbackData data struture undicating if update is needed, cursor position and current text
766 ImfManager::ImfCallbackData ImfEventReceived( Dali::ImfManager& imfManager, const ImfManager::ImfEventData& test );
769 * Called when the OnKey event is a Pre-edit string
770 * @param[in] keyString String received in Pre-edit
771 * @param[in] cursorOffset the cursor offset from where the pre-edit word starts
772 * @return bool true if preedit reset is required.
774 bool PreEditReceived( const std::string& keyString, std::size_t cursorOffset );
777 * Called when the OnKey event is a Commit string
778 * @param[in] keyString String received in Comment
779 * @return update flag to trigger cursor update of TextInput only when needed.
781 bool CommitReceived( const std::string& keyString );
784 * Deletes Pre-edit string
785 * By default it doesn't update the character's size and position table, which is a costly
786 * operation. As in many cases deletion and insertion (InsertAt) of text
787 * occurs in the same action i.e. preedit/commit. It makes sense to
788 * delete without updating, and then insert with updating.
790 * @return The number of characters to be deleted.
792 std::size_t DeletePreEdit();
795 * Reset all pre-edit flag and signal IMF keyboard that the current pre-edit word has been comitted.
796 * This may be due to the cursor being moved by user or reached the max character limit.
797 * @param[in] preserveCursorPosition Set true to keep cursor in current position, eg. touch event caused cursor to move.
799 void PreEditReset( bool preserveCursorPosition );
802 * Called after cursor position needs updating.
803 * Redraws cursor and notifies VirtualKeyboard
808 * Delete highlighted characters
809 * @param[in] inheritStyle Whether style from previous character in the string should be inherited.
811 void DeleteHighlightedText( bool inheritStyle );
814 * Delete range of characters
815 * @param[in] start position of characters to delete
816 * @param[in] ncharacters number of characters to delete
818 void DeleteRange(std::size_t start, std::size_t ncharacters);
821 * Delete character at current cursor position and redisplay
822 * @param[in] positionToDelete position of character to delete
824 void DeleteCharacter( std::size_t positionToDelete );
827 * Add or replaces characters to currently displayed string at cursor position
828 * By default it doesn't update the character's size and position table, which is a costly
829 * operation. As in many cases deletion and insertion (InsertAt) of text
830 * occurs in the same action i.e. preedit/commit. It makes sense to
831 * delete without updating, and then insert with updating.
832 * @param[in] newText string to add to TextInput display string.
833 * @param[in] insertionPosition position to insert at.
834 * @param[in] numberOfCharactersToReplace The number of characters to replace.
835 * @return number of characters to offset the cursor by.
837 std::size_t InsertAt( const Text& newText, const std::size_t insertionPosition, const std::size_t numberOfCharactersToReplace );
840 * Creates a cursor from the supplied image
841 * @param[in] cursorImage the image to be used for the cursor.
842 * @param[in] border the nine patch border corresponding to the supplied image.
843 * @return the image actor to be used as the cursor.
845 ImageActor CreateCursor( Image cursorImage, const Vector4& border );
848 * Moves cursor to the right
849 * param[in] reverse if true then cursor moves in the reverse direction (to the left)
850 * param[in] places number of character cursor should move.
852 void AdvanceCursor(bool reverse = false, std::size_t places = 1);
855 * Draw a cursor / caret at position where new text should appear
856 * @param[in] nthChar the position along the text string in which new text should appear.
858 void DrawCursor(const std::size_t nthChar = 0);
861 * Sets cursor visibility
862 * This sets visibility of the cursor. Which is comprised of 2
863 * cursors. The conventional cursor, and the alternate (RTL) cursor,
864 * which only appears when the cursor is at a character that can have
865 * a character appended to different visual positions depending on whether that
866 * character to be appended is RTL or LTR.
867 * @param[in] visible true - enable visibility for cursor, false - disable visiblity for cursor
869 void SetCursorVisibility( bool visible );
872 * Sets alternate cursor enable state
873 * @see SetCursorVisibility
874 * alternate cursor will only be visible if both SetCursorVisiblity
875 * and cursor enabled have been set to true.
877 void SetAltCursorEnabled( bool enabled );
880 * Create the grab handle that positions the cursor
881 * @param[in] image to be used for grab handle
884 void CreateGrabHandle(Image image=Image());
887 * Create Grab area to be used by Grab Handle
889 void CreateGrabArea( Actor& parent);
892 * Move grab handle to the required character position
894 * @param[in] displacement Displacement of the grab handle in actor coordinates.
896 * @return The new actual position the handle has been set to.
898 Vector3 MoveGrabHandle( const Vector2& displacement );
901 * Show or hide the grab handle without baking the visibility flag.
902 * Used when the Grab handle needs to be invisible due to text-view scrolling making it out of view
904 * @param[in] visible bool flag to set as true is grab handle should be shown, else false to hide.
906 void ShowGrabHandle( bool visible );
909 * Show or hide the grab handle and bake the visibility flag.
910 * Used when the state of text-input changes to a state which the grabhandle is not required. E.g. Selection mode starts or edit mode ends.
911 * Calls ShowGrabHandle.
913 * @param[in] visible bool flag to set as true is grab handle should be shown, else false to hide.
915 void ShowGrabHandleAndSetVisibility( bool visible );
917 /* Boundary Property Notifications when handle exceed bounding box*/
920 * PropertyNotification Callback when left boundary exceeded so handle can be flipped.
921 * @param[in] source PropertyNotification
923 void OnLeftBoundaryExceeded( PropertyNotification& source );
925 * PropertyNotification Callback when within left boundary so handle can be flipped back.
926 * @param[in] source PropertyNotification
928 void OnReturnToLeftBoundary( PropertyNotification& source );
930 * PropertyNotification Callback when right boundary exceeded so handle can be flipped.
931 * @param[in] source PropertyNotification
933 void OnRightBoundaryExceeded( PropertyNotification& source );
935 * * PropertyNotification Callback when within right boundary so handle can be flipped back.
936 * @param[in] source PropertyNotification
938 void OnReturnToRightBoundary( PropertyNotification& source );
941 * PropertyNotification Callbacks for hiding handle one when it exceeds boundary.
942 * @param[in] source PropertyNotification
944 void OnHandleOneLeavesBoundary( PropertyNotification& source );
946 * PropertyNotification Callbacks for showing hidden handle one when returns within boundary
947 * @param[in] source PropertyNotification
949 void OnHandleOneWithinBoundary( PropertyNotification& source );
951 * PropertyNotification Callbacks for hiding handle two it when exceeds boundary.
952 * @param[in] source PropertyNotification
954 void OnHandleTwoLeavesBoundary( PropertyNotification& source );
956 * PropertyNotification Callbacks for showing hidden handle two when returns within boundary
957 * * @param[in] source PropertyNotification
959 void OnHandleTwoWithinBoundary( PropertyNotification& source );
962 * Set up property notifications on the position of the handles to facilitate flipping and hiding when at screen boundary.
964 void SetUpHandlePropertyNotifications();
967 * Create the selection handles that bound text to be selected for copy/cut.
968 * @param[in] start initial position of start selection handle.
969 * @param[in] end initial position of end selection handle.
970 * @param[in] handleOneImage (optional) to be used for selection handle
971 * @param[in] handleTwoImage (optional) to be used for selection handle
973 void CreateSelectionHandles( std::size_t start = 0, std::size_t end = std::numeric_limits<std::size_t>::max(), Dali::Image handleOneImage = Dali::Image(), Dali::Image handleTwoImage = Dali::Image() );
976 * Move the selection handles to required positions in text.
978 * @param[in] handleId the handle to position
979 * @param[in] displacement Displacement of the selection handle in actor coordinates.
981 * @return The new actual position the handle has been set to.
983 Vector3 MoveSelectionHandle(SelectionHandleId handleId, const Vector2& displacement);
986 * Calculate and position the specified selection handle the given index position
988 * @param[in] handleId the handle to position
990 void SetSelectionHandlePosition(SelectionHandleId handleId);
993 * Gets the visual position of a logical position.
994 * @note This is preferred over directly accessing the Map, as it resolves visual
995 * positions outside of the character map range.
996 * @param[in] logicalPosition The logical position
997 * @return Visual position is returned.
999 std::size_t GetVisualPosition(std::size_t logicalPosition) const;
1002 * Gets a table of the visual text positions which has a flag
1003 * for each Character. The flag is either true (character selected)
1004 * or false (character deselected)
1005 * @note startSelection can be greater or less than endSelection
1007 * @param[in,out] selectedVisualText The vector to be resized and populated with the selected flags
1008 * @param[in] startSelection The start selection point for the text
1009 * @param[in] endSelection The end selection point for the text
1011 void GetVisualTextSelection(std::vector<bool>& selectedVisualText, std::size_t startSelection, std::size_t endSelection);
1014 * Iterates between selection handles and computes the info required to build the highlight mesh
1016 HighlightInfo CalculateHighlightInfo();
1019 * Calculates new Mesh data so highlight moves with selection handles.
1021 void UpdateHighlight();
1024 * Removes popup, and its options.
1029 * Adds a popup option.
1030 * @note Creates popup frame if not already created.
1031 * @param[in] name The unique name for this option.
1032 * @param[in] caption The caption (label) for this option
1033 * @param[in] icon the image icon to be displayed for this option
1034 * @param[in] finalOption Flag to indicate that this is the final option.
1035 * (set to true on the last option you add)
1037 void AddPopupOption(const std::string& name, const std::string& caption, const Image icon, bool finalOption = false);
1040 * Sets popup position
1041 * @param[in] position The actual position for this popup.
1043 void SetPopupPosition(const Vector3& position);
1047 * @param[in] animate (optional) whether to animate popup to hide state over time (i.e. tween).
1048 * @param[in] signalFinished (optional) whether to perform an animation finish operation after the hide animation completes. Requires animate to be true.
1050 void HidePopup( bool animate = true, bool signalFinished = true );
1054 * @param[in] animate (optional) whether to animate popup to show state over time (i.e. tween).
1056 void ShowPopup(bool animate = true);
1059 * Shows the cut-copy-paste popup
1061 void ShowPopupCutCopyPaste();
1064 * Setup the selection popup and clipboard if relevant so the correct options are shown when ShowPopup is called.
1066 void SetUpPopUpSelection();
1069 * Return the logical index containing the character position closest to the source.
1070 * Used for positioning the grab handle at characters when dragged along.
1071 * Two different behaviours are needed in case the source point doesn't actually touch a
1072 * character. @see TouchToIndex.
1073 * @param[in] source float to match against
1074 * @param[out] closestIndex index to the vector of character's size and position.
1075 * @return \e true if the source point is actually inside the geometry provided by TextView.
1077 bool ReturnClosestIndex(const Vector2& source, std::size_t& closestIndex );
1080 * Returns the X-position of the current line justification
1081 * (relative to left of text-view container)
1082 * @return X position for line justification
1084 float GetLineJustificationPosition() const;
1087 * Currently the cursor is positioned at the previous characters position plus it's width.
1088 * If the previous character is on a different line then this function returns the correct position.
1089 * @param[in] characterPosition the character position index that the cursor should be at
1090 * @return position of cursor/handle
1092 Vector3 PositionCursorAfterWordWrap( std::size_t characterPosition ) const;
1096 * Return a vector which is the actual position for the given character position
1097 * The character position is where a cursor would be position for that character.
1098 * @param[in] characterPosition the logical (input) position in the 'string' of characters.
1100 * @return Vector3 the actual x,y,z position
1102 Vector3 GetActualPositionFromCharacterPosition(std::size_t characterPosition ) const;
1105 * Return a vector which is the actual position for the given character position
1106 * The character position is where a cursor would be positioned for that character to be inserted.
1107 * An additional alternatePosition is also set in circumstances where the possible writing
1108 * of characters would be in the opposite direction.
1109 * e.g. "HelloشقشلاهؤEnglish"
1112 * [*] - Primary actual position for cursor i.e. continuing writing LTR (English)
1113 * [+] - Alternate actual position for cursor i.e. writing RTL (Arabic)
1115 * @param[in] characterPosition the logical (input) position in the 'string' of characters.
1116 * @param[out] directionRTL Whether the actual x,y,z position is after LTR (false) or RTL (true) text.
1117 * @param[out] alternatePosition the actual x,y,z position of the cursor if user types
1118 * in alternate direction to current flow of text.
1119 * @param[out] alternatePositionValid whether this alternate position is valid.
1120 * @return Vector3 the actual x,y,z position
1122 Vector3 GetActualPositionFromCharacterPosition(std::size_t characterPosition, bool& directionRTL, Vector3& alternatePosition, bool& alternatePositionValid ) const;
1125 * Retrieve the character position of the first character on the row of text
1126 * that this character resides on.
1127 * @param[in] logicalPosition the position in the 'string' of characters.
1128 * @return logical character position of start of row.
1130 std::size_t GetRowStartFromCharacterPosition(std::size_t logicalPosition) const;
1133 * Retrieve the dimensions of this row of text that the character resides on.
1134 * @param[in] characterPosition the position in the 'string' of characters.
1135 * @return The size of the rectangle representing this row
1137 Size GetRowRectFromCharacterPosition(std::size_t characterPosition) const;
1140 * Retrieve the dimensions (and min-max) of this row of text that the character resides on.
1141 * @param[in] characterPosition the position in the 'string' of characters.
1142 * @param[out] min the top-left position of the rectangle representing this row
1143 * @param[out] max the bottom-right position of the rectangle representing this row
1144 * @return The size of the rectangle representing this row (max - min)
1146 Size GetRowRectFromCharacterPosition(std::size_t characterPosition, Vector2& min, Vector2& max) const;
1149 * Checks if the provided touchedActor was this text-input
1150 * @param[in] touchedActor the touched actor that will be checked against this text-input
1151 * @return true if the touchActor was the text-input or one of its children
1153 bool WasTouchedCheck( const Actor& touchedActor ) const;
1156 * Connect to the stage touch event
1158 void StartMonitoringStageForTouch();
1161 * Disconnect from the stage touch event
1163 void EndMonitoringStageForTouch();
1166 * Callback for when the screen is touched, this will be connected when selection starts and disconnected when it ends.
1167 * @param[in] event The touch event
1169 void OnStageTouched(const TouchEvent& event);
1173 * Select the text between the given values
1174 * @param[in] start position within array to start selection
1175 * @param[in] end position within array to end selection
1177 void SelectText(std::size_t start, std::size_t end);
1180 * Gets selected text and returns it as a StyleText vector
1181 * @return StyledText vector that is selected.
1183 MarkupProcessor::StyledTextArray GetSelectedText();
1186 * Applies the given style to all text, selected or not selected.
1187 * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
1189 void ApplyStyleToRange(const TextStyle& style, const TextStyle::Mask mask, const std::size_t begin, const std::size_t end);
1192 * Callback for when the keyboard status changes
1193 * @param[in] keyboardShown Whether the keyboard has just been shown or not.
1195 void KeyboardStatusChanged(bool keyboardShown);
1198 * Hide highlight shown between selection handles.
1200 void RemoveHighlight();
1203 * Highlights text that has been selected
1205 void CreateHighlight();
1208 * Copies selected text to clipboard
1209 * @return bool true if copy was successful.
1211 bool CopySelectedTextToClipboard();
1214 * Pastes the given text to currently displayed string at the current cursor position
1215 * @param[in] text Text to be pasted
1217 void PasteText( const Text& text );
1220 * Sets the direction of the text if it is empty.
1222 void SetTextDirection();
1225 * Updates the line height accordingly with the current text input style.
1227 void UpdateLineHeight();
1230 * Finds a visible character.
1232 * The \e direction parameters specifies from where to start to look for a visible character. \e Left means start by characters in lower
1233 * positions than \e cursorPosition, \e Right means start by characters in greater positions than \e cursorPosition and \e ByEnd starts
1234 * by the last characters.
1236 * If \e Left or \e Right is provided and any character is found, then looks in the other direction.
1238 * @param[in] direction Direction used to find a visible character.
1239 * @param[in] cursorPosition Starting position.
1241 * @return The found visible character.
1243 std::size_t FindVisibleCharacter( const FindVisibleCharacterDirection direction , const std::size_t cursorPosition ) const;
1246 * @copydoc SetSortModifier()
1248 void SetSortModifier( float depthOffset );
1251 * @copydoc SetSnapshotModeEnabled()
1253 void SetSnapshotModeEnabled( bool enable );
1256 * @copydoc IsSnapshotModeEnabled()
1258 bool IsSnapshotModeEnabled() const;
1261 * @copydoc SetScrollEnabled()
1263 void SetScrollEnabled( bool enable );
1266 * @copydoc IsScrollEnabled()
1268 bool IsScrollEnabled() const;
1271 * @copydoc SetScrollPosition()
1273 void SetScrollPosition( const Vector2& position );
1276 * @copydoc GetScrollPosition()
1278 Vector2 GetScrollPosition() const;
1281 * @brief Sets whether markup processing should be carried out.
1283 * @param[in] enable whether markup processing is carried out or not.
1285 void SetMarkupProcessingEnabled( bool enable );
1288 * @brief Returns whether markup processing is enabled or not
1290 * @return true is markup processing is enabled
1292 bool IsMarkupProcessingEnabled() const;
1295 * Insert or replaces the given text in the given position. It checks if the text exceeds the maximum allowed number of characters
1296 * and if it fits in the text-input's boundaries.
1298 * @param[in] text Text to be inserted.
1299 * @param[in] position Position where the text is inserted.
1300 * @param[in] numberOfCharactersToReplace The number of characters to replace.
1301 * @param[out] textExceedsMaximunNumberOfCharacters The number of characters that have been inserted.
1302 * @param[out] textExceedsBoundary Whether the inserted text has exceeded the boundaries of the text-input.
1304 * @return The number of characters that have been inserted.
1306 std::size_t DoInsertAt( const Text& text, std::size_t position, std::size_t numberOfCharactersToReplace, bool& textExceedsMaximunNumberOfCharacters, bool& textExceedsBoundary );
1309 * Retrieve Text-view's layout info.
1311 void GetTextLayoutInfo();
1314 * Emits the style changed signal.
1316 void EmitStyleChangedSignal();
1319 * Emits max input characters reached signal.
1321 void EmitMaxInputCharactersReachedSignal();
1324 * Emits a signal when the input text exceeds the boundaries of the text-input.
1326 void EmitInputTextExceedsBoundariesSignal();
1330 State mState; ///< Current State of Text input.
1331 MarkupProcessor::StyledTextArray mStyledText; ///< String currently displayed by TextView with style info.
1332 TextStyle mInputStyle; ///< Stores the current input style.
1333 float mLineHeight; ///< Stores the current line height accordingly with the input style.
1334 Toolkit::TextView mDisplayedTextView; ///< Actor which actually display text
1336 MarkupProcessor::StyledTextArray mStyledPlaceHolderText; ///< Text used as place holder with style info.
1338 std::size_t mMaxStringLength; ///< Max number of characters for string
1339 std::size_t mNumberOflinesLimit; ///< Limit on the number of lines this TextInput will display.
1341 ImageActor mCursor; ///< Cursor overlayed on Text to show where new text will be inserted
1342 ImageActor mCursorRTL; ///< Right To Left Cursor overlayed on Text (where new RTL text would be inserted)
1343 Animation mCursorAnimation; ///< animator for cursor blinking.
1344 std::size_t mCursorPosition; ///< position along string cursor is at.
1345 Timer mCursorBlinkTimer; ///< Timer to signal cursor to blink
1347 Layer mActiveLayer; ///< Layer for active handles and alike that ensures they are above all else.
1349 Image mGrabHandleImage; ///< image to be used for grab handle
1350 ImageActor mGrabHandle; ///< Handle used to move cursor for editing
1352 Actor mGrabArea; ///< invisible actor that receives pans events for the grab handle.
1353 PanGestureDetector mPanGestureDetector; ///< Pan gesture for handles
1354 TapGestureDetector mTapDetector; ///< used to start editing
1355 TapGestureDetector mDoubleTapDetector; ///< double tap detector
1357 Vector3 mActualGrabHandlePosition; ///< actual position of grab handle, this might not be snapped to a character
1359 LongPressGestureDetector mLongPressDetector; ///< Gesture to start selection
1361 /*Selection handles*/
1362 Image mSelectionHandleOneImage; ///< image used for selection handle one
1363 Image mSelectionHandleOneImagePressed; ///< image used for selection handle one pressed state
1364 Image mSelectionHandleTwoImage; ///< image used for selection handle two
1365 Image mSelectionHandleTwoImagePressed; ///< image used for selection handle two pressed state
1367 bool mIsSelectionHandleOneFlipped:1; ///< Flag to know whether the handle one is flipped or not.
1368 bool mIsSelectionHandleTwoFlipped:1; ///< Flag to know whether the handle two is flipped or not.
1369 Vector3 mSelectionHandleOneOffset; ///< Handle One's Offset
1370 Vector3 mSelectionHandleTwoOffset; ///< Handle Two's Offset
1371 Vector3 mSelectionHandleOneActualPosition; ///< Actual x y position of handle
1372 Vector3 mSelectionHandleTwoActualPosition; ///< Actual x y position of handle
1373 std::size_t mSelectionHandleOnePosition; ///< Position of handle along the string of text
1374 std::size_t mSelectionHandleTwoPosition; ///< Position of handle along the string of text
1375 ImageActor mSelectionHandleOne; ///< First selection handle used for selecting text to cut&paste
1376 ImageActor mSelectionHandleTwo; ///< Second selection handle used for selecting text to cut&paste
1377 Actor mHandleOneGrabArea; ///< invisible actor that receives pans events for the selection handle.
1378 Actor mHandleTwoGrabArea; ///< invisible actor that receives pans events for the selection handle.
1380 Mesh mHighlightMesh; ///< Mesh Data for highlight
1381 MeshActor mHighlightMeshActor; ///< Mesh Actor to display highlight
1382 MeshData mMeshData; ///< Container to hold meshData for highlight
1383 Material mCustomMaterial; ///< Custom material used for highlight
1384 HighlightInfo mNewHighlightInfo; ///< Geometry info to create highlight.
1386 Text mPreEditString; ///< Holds current input string prior to it being committed.
1387 std::size_t mPreEditStartPosition; ///< Cursor position for start of pre-edit string
1388 std::size_t mPreEditLength; ///< Cursor position for length of current pre-edit string after purging characters that do not fit.
1389 std::size_t mNumberOfSurroundingCharactersDeleted; ///< Stores the number of surrounding characters deleted.
1390 unsigned long mTouchStartTime; ///< Touch Start time (time in ms when down press began)
1392 Toolkit::TextView::TextLayoutInfo mTextLayoutInfo; ///< It contains a table layout info per character sorted by the character's visual index (retrieved from TextView),
1393 ///< a reorder map that stores each character's visual (output) index according to its logical (input) index,
1394 ///< a reorder map that stores each character's logical (input) index according to its visual (output) index,
1395 ///< the text size after layout and the scroll offset.
1397 MarkupProcessor::StyledTextArray mCurrentCopySelecton; ///< Array to store copied text.
1398 TextInputPopup mPopUpPanel; ///< Panel to house cut and paste, select all buttons.
1401 Vector2 mScrollDisplacement;
1402 Vector3 mCurrentHandlePosition;
1403 SelectionHandleId mCurrentSelectionId;
1404 Vector3 mCurrentSelectionHandlePosition;
1405 SelectionParameters mRequestedSelection;
1406 Vector4 mSelectionHandleFlipMargin;
1407 Vector4 mBoundingRectangleWorldCoordinates;
1409 Clipboard mClipboard; ///< Handle to clipboard
1411 bool mOverrideAutomaticAlignment:1; ///< Whether to override the alignment automatically set by the text content (e.g. european LTR or arabic RTL)
1412 bool mCursorRTLEnabled:1; ///< Enable state of Alternate RTL Cursor (need to keep track of this as it's not always enabled)
1413 bool mClosestCursorPositionEOL:1; ///< closest cursor position is end of line.
1414 bool mCursorBlinkStatus:1; ///< \e true shows the cursor, \e false hiddes it.
1416 bool mCursorVisibility:1; ///< Visibility status of Cursor
1417 bool mGrabHandleVisibility:1; ///< Visibility status of the grab handle.
1419 bool mIsCursorInScrollArea:1; ///< Whether the cursor is inside the boundaries of the text-input.
1420 bool mIsGrabHandleInScrollArea:1; ///< Whether the grab handle is inside the boundaries of the text-input.
1422 bool mEditModeActive:1; ///< true to indicate TextInput is in edit mode.
1423 bool mEditOnTouch:1; ///< true indicates edit mode starts by touching/tapping the TextInput
1424 bool mTextSelection:1; ///< true indicates text selection is enabled.
1425 bool mExceedEnabled:1; ///< Whether text-input editing text beyond its boundary is enabled or not. By default is enabled.
1426 bool mGrabHandleEnabled:1; ///< Flag to enable the grab handle instead of the default magnifier.
1427 bool mIsSelectionHandleFlipEnabled:1; ///< Flag to enable the selection handle flip
1429 bool mPreEditFlag:1; ///< Flag to indicate if key string received is still in pre-edit mode (Ecore IMF keyboard)
1430 bool mIgnoreCommitFlag:1; ///< Flag to indicate if the commit string should be ignored, maybe due to a keyboard reset.
1431 bool mIgnoreFirstCommitFlag:1; ///< Whether to ignore the first commit.
1432 bool mSelectingText:1; ///< Ignore surrounding text as selecting text
1434 bool mPreserveCursorPosition:1; ///< Indicates that the commit message is from a reset and does not require the cursor to be moved
1436 bool mSelectTextOnCommit:1;
1438 bool mUnderlinedPriorToPreEdit:1; ///< As predictive text adds underline style this flag enables us to revert back or keep underline.
1440 bool mCommitByKeyInput:1; ///< Set if a commit is done by key input rather than automatically (usually when a space bar or enter is pressed).
1442 bool mPlaceHolderSet:1; ///< Whether the place holder text is set.
1443 bool mMarkUpEnabled:1; ///< enable to scan for mark-up
1445 Toolkit::TextInput::InputSignalV2 mInputStartedSignalV2; ///< Signal emitted when input starts
1446 Toolkit::TextInput::InputSignalV2 mInputFinishedSignalV2; ///< Signal emitted when input ends
1447 Toolkit::TextInput::StyleChangedSignalV2 mStyleChangedSignalV2; ///< Signal emitted when style changes.
1448 Toolkit::TextInput::MaxInputCharactersReachedSignalV2 mMaxInputCharactersReachedSignalV2; ///< Signal emitted when max input characters is reached.
1449 Toolkit::TextInput::InputSignalV2 mCutAndPasteToolBarDisplayedV2; ///< Signal emitted when toolbar displayed
1450 Toolkit::TextInput::InputTextExceedBoundariesSignalV2 mInputTextExceedBoundariesSignalV2; ///< Signal emitted when input text exceeds the boundaries of the text-input.
1453 } // namespace Internal
1455 // Helpers for public-api forwarding methods
1457 inline Toolkit::Internal::TextInput& GetImpl(Toolkit::TextInput& textInput)
1459 DALI_ASSERT_ALWAYS(textInput);
1461 Dali::RefObject& handle = textInput.GetImplementation();
1463 return static_cast<Toolkit::Internal::TextInput&>(handle);
1466 inline const Toolkit::Internal::TextInput& GetImpl(const Toolkit::TextInput& textInput)
1468 DALI_ASSERT_ALWAYS(textInput);
1470 const Dali::RefObject& handle = textInput.GetImplementation();
1472 return static_cast<const Toolkit::Internal::TextInput&>(handle);
1475 } // namespace Toolkit
1479 #endif // __DALI_TOOLKIT_INTERNAL_TEXT_INPUT_H__