1 #ifndef __DALI_TOOLKIT_INTERNAL_TEXT_VIEW_H__
2 #define __DALI_TOOLKIT_INTERNAL_TEXT_VIEW_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/public-api/common/dali-vector.h>
23 #include <dali/public-api/actors/text-actor.h>
24 #include <dali-toolkit/public-api/controls/control-impl.h>
25 #include <dali-toolkit/public-api/controls/text-view/text-view.h>
26 #include "text-actor-cache.h"
27 #include "text-view-processor-types.h"
39 * TextView is a custom control for text aligning and multiline support
41 class TextView : public ControlImpl
46 * Internal exceed policy with the valid combinations.
50 Original, ///< Original size (even if it exceeds the witdh or the height).
51 OriginalFade, ///< Original size if it exceeds the width but faded if it exceeds the height.
52 OriginalShrink, ///< Shrunk if it exceeds the height.
53 SplitOriginal, ///< Split if it exceeds the width but no action if it exceeds the height.
54 SplitFade, ///< Split if it exceeds the width and faded if it exceeds the height.
55 SplitShrink, ///< Split if it exceeds the width and shrunk if it exceeds the height.
56 Fade, ///< Faded if it exceeds any boundary.
57 FadeOriginal, ///< Faded if it exceeds the width but no action if it exceeds the height.
58 ShrinkOriginal, ///< Shrunk if it exceeds the width but no action if it exceeds the height.
59 ShrinkFade, ///< Shrunk if it exceeds the width and faded if it exceeds the height.
60 Shrink, ///< Shrunk if it exceeds any boundary.
61 EllipsizeEndOriginal, ///< Ellipsized by the end if it exceeds the width but no action if it exceeds the height.
62 EllipsizeEnd ///< Ellipsized by the end if it exceeds the width and/or the height.
65 // Between two OnRelaidOut methods, several calls to InsertTextAt, RemoveTextFrom or SetText can happen.
66 // TextViewProcessorMetadata stores the type of operation. A vector stores all operations between two OnRelaidOut calls.
68 enum TextViewProcessorMetadataType
70 TextSet, ///< Sets new text.
71 TextInserted, ///< Inserts text into current text.
72 TextReplaced, ///< Replaces some text from current text.
73 TextRemoved, ///< Removes some text from current text.
74 NewLineHeight, ///< Sets a new line height offset.
75 NewStyle ///< Sets a new style to the whole text.
79 * Stores info about which data structures need to be modified when the OnRelaidOut() method is called
81 struct TextViewProcessorMetadata
83 TextViewProcessorMetadata();
85 TextViewProcessorMetadataType mType; ///< Stores the type of operation.
86 std::size_t mPosition; ///< Character position within the text.
87 std::size_t mNumberOfCharacters; ///< Number of characters to be removed/ replaced.
88 MarkupProcessor::StyledTextArray mText; ///< The new text.
89 TextStyle::Mask mStyleMask; ///< The style mask.
93 * Defines which operations have to be done in the relayout process.
95 enum RelayoutOperationMask
97 NO_RELAYOUT = 0x0, ///< Does nothing.
98 RELAYOUT_REMOVE_TEXT_ACTORS = 0x1, ///< Removes current text-actors from the text-view.
99 RELAYOUT_SIZE_POSITION = 0x2, ///< Calculates size and position of the text but it doesn't calculate alignment.
100 RELAYOUT_ALIGNMENT = 0x4, ///< Aligns the whole text.
101 RELAYOUT_VISIBILITY = 0x8, ///< Calculates the visibility.
102 RELAYOUT_INITIALIZE_TEXT_ACTORS = 0x10, ///< Initialize text-actors (create handles).
103 RELAYOUT_TEXT_ACTOR_UPDATE = 0x20, ///< Updates text-actors (set size, position, style, ...)
104 RELAYOUT_INSERT_TO_TEXT_VIEW = 0x40, ///< Adds the text-actors to the text-view.
105 RELAYOUT_INSERT_TO_TEXT_ACTOR_LIST = 0x80, ///< Inserts the text-actors to the text-actor list.
106 RELAYOUT_ALL = 0xFF ///< Does all operations.
109 //////////////////////////////////////////////
112 * Create a new TextView.
113 * @return A smart-pointer to the newly allocated TextView.
115 static Toolkit::TextView New();
118 * @copydoc SetText( const std::string& text )
120 void SetText( const std::string& text );
123 * @copydoc SetText( const StyledTextArray& text )
125 void SetText( const MarkupProcessor::StyledTextArray& text );
128 * @copydoc InsertTextAt( std::size_t position, const std::string& text )
130 void InsertTextAt( std::size_t position, const std::string& text );
133 * @copydoc InsertTextAt( std::size_t position, const std::string& text )
135 void InsertTextAt( std::size_t position, const MarkupProcessor::StyledTextArray& text );
138 * @copydoc RemoveTextFrom( std::size_t position, std::size_t numberOfCharacters )
140 void RemoveTextFrom( std::size_t position, std::size_t numberOfCharacters );
143 * @copydoc ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text )
145 void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text );
148 * @copydoc ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text )
150 void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const MarkupProcessor::StyledTextArray& text );
155 std::string GetText() const;
158 * @copydoc SetFont( const Font newFont )
160 void SetFont( const Font newFont );
163 * @copydoc SetLineHeightOffset()
165 void SetLineHeightOffset( PointSize offset );
168 * @copydoc GetLineHeightOffset()
170 PointSize GetLineHeightOffset() const;
173 * @copydoc SetStyleToCurrentText()
175 void SetStyleToCurrentText( const TextStyle& style, TextStyle::Mask mask );
178 * @copydoc SetTextAlignment( Toolkit::Alignment::Type align )
180 void SetTextAlignment( Toolkit::Alignment::Type align );
183 * @copydoc GetTextAlignment()
185 Toolkit::Alignment::Type GetTextAlignment() const;
188 * @copydoc SetMultilinePolicy()
190 void SetMultilinePolicy( Toolkit::TextView::MultilinePolicy policy );
193 * @copydoc GetMultilinePolicy()
195 Toolkit::TextView::MultilinePolicy GetMultilinePolicy() const;
198 * @copydoc SetWidthExceedPolicy()
200 void SetWidthExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
203 * @copydoc GetWidthExceedPolicy()
205 Toolkit::TextView::ExceedPolicy GetWidthExceedPolicy() const;
208 * @copydoc SetHeightExceedPolicy()
210 void SetHeightExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
213 * @copydoc GetHeightExceedPolicy()
215 Toolkit::TextView::ExceedPolicy GetHeightExceedPolicy() const;
218 * @copydoc SetLineJustification()
220 void SetLineJustification( Toolkit::TextView::LineJustification justification );
223 * @copydoc GetLineJustification()
225 Toolkit::TextView::LineJustification GetLineJustification() const;
228 * @copydoc SetFadeBoundary()
230 void SetFadeBoundary( const Toolkit::TextView::FadeBoundary& fadeBoundary );
233 * @copydoc GetFadeBoundary()
235 const Toolkit::TextView::FadeBoundary& GetFadeBoundary() const;
238 * @copydoc SetEllipsizeText()
240 void SetEllipsizeText( const std::string& ellipsizeText );
243 * @copydoc SetEllipsizeText()
245 void SetEllipsizeText( const MarkupProcessor::StyledTextArray& ellipsizeText );
248 * @copydoc GetEllipsizeText()
250 std::string GetEllipsizeText() const;
253 * Checks if relayout the text is needed. If it is, it relais out the text
254 * by calling DoRelayOut().
256 void GetTextLayoutInfo();
259 * Calls GetTextLayoutInfo() and fills the given data structure.
261 * @see GetTextLayoutInfo()
263 void GetTextLayoutInfo( Toolkit::TextView::TextLayoutInfo& textLayoutInfo );
266 * @copydoc SetSortModifier()
268 void SetSortModifier( float depthOffset );
271 * @copydoc SetSnapshotModeEnabled()
273 void SetSnapshotModeEnabled( bool enable );
276 * @copydoc IsSnapshotModeEnabled()
278 bool IsSnapshotModeEnabled() const;
281 * @copydoc SetScrollEnabled()
283 void SetScrollEnabled( bool enable );
286 * @copydoc IsScrollEnabled()
288 bool IsScrollEnabled() const;
291 * @copydoc SetScrollPosition()
292 * @see DoSetScrollPosition()
294 void SetScrollPosition( const Vector2& position );
297 * @copydoc GetScrollPosition()
299 const Vector2& GetScrollPosition() const;
302 * @copydoc IsScrollPositionTrimmed()
304 bool IsScrollPositionTrimmed() const;
307 * @copydoc ScrolledSignal()
309 Toolkit::TextView::ScrolledSignalV2& ScrolledSignal();
312 * Connects a callback function with the object's signals.
313 * @param[in] object The object providing the signal.
314 * @param[in] tracker Used to disconnect the signal.
315 * @param[in] signalName The signal to connect to.
316 * @param[in] functor A newly allocated FunctorDelegate.
317 * @return True if the signal was connected.
318 * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
320 static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
322 private: // From ControlImpl
325 * @copydoc Toolkit::Control::OnInitialize()
327 virtual void OnInitialize();
330 * @copydoc Toolkit::Control::OnStyleChange()
332 virtual void OnStyleChange( StyleChange change );
335 * @copydoc Toolkit::Control::OnControlSizeSet()
337 virtual void OnControlSizeSet( const Vector3& size );
340 * @copydoc Toolkit::Control::OnRelaidOut()
342 * Removes text-actor and calls DoRelayOut()..
344 virtual void OnRelaidOut( Vector2 size, ActorSizeContainer& container );
347 * Retrieves the text-view's natural size.
349 * @return The natural size.
351 virtual Vector3 GetNaturalSize();
354 * Retrieves the text-view's \e height for a given \e width.
356 * @param[in] width The given \e width.
358 * @return The \e height for the given \e width.
360 virtual float GetHeightForWidth( float width );
363 * Retrieves the text-view's \e width for a given \e height.
365 * @param[in] height The given \e height.
367 * @return The \e width for the given \e height.
369 virtual float GetWidthForHeight( float height );
372 * @copydoc Dali::CustomActorImpl::OnPropertySet()
374 virtual void OnPropertySet( Property::Index index, Property::Value propertyValue );
379 * Construct a new TextView.
384 * A reference counted object may only be deleted by calling Unreference()
391 TextView( const TextView& );
394 TextView& operator=( const TextView& rhs );
397 * Executes synchronously relayout operations such as set, insert, remove or replace text, or
398 * split groups of characters, etc.
400 void PerformTextViewProcessorOperations();
403 * Optimizes some text-view processor operations.
405 void OptimizeTextViewProcessorOperations();
408 * Synchronously relays-out all text-actors.
410 * Perform text-view-processor operations, sets the new size and position of text-actors and adds them to the text-view.
412 * @param[in] textViewSize The new text-view's size.
413 * @param[in] relayoutOperationMask Defines which operations need to be done in the relayout process.
415 void DoRelayOut( const Size& textViewSize, RelayoutOperationMask relayoutOperationMask );
418 * Process Snapshot. It refresh the render-task in order to generate a new snapshot image.
420 * ProcessSnapshot is called from OnRelaidOut() only if text has been relaid out.
421 * It creates a new image buffer only if the size of the text has changed.
423 * @param[in] textViewSize The new text-view's size.
425 void ProcessSnapshot( const Size& textViewSize );
428 * Aligns the offscreen rendering camera actor to cover the whole text and the resulting image actor accordingly with the text view's alignment.
430 * @param[in] textViewSize The text view's size.
431 * @param[in] offscreenSize The offscreen's frame buffer's size.
433 void AlignOffscreenCameraActor( const Size& textViewSize, const Size& offscreenSize );
436 * Callback called when the render task has processed.
438 * It makes the root actor invisible.
440 * @param[in] renderTask The processed render task.
442 void RenderTaskFinished( Dali::RenderTask& renderTask );
445 * Destroys offscreen rendering resources.
447 * It disconects the render task finished signal from the TextView::RenderTaskFinished() method,
448 * removes the render task from the render task list and resets the offscreen camera actor, root actor,
449 * image actor and the frame buffer.
451 void DestroyOffscreenRenderingResources();
454 * Called when text-view is scrolled.
456 * Sets the new scroll position. @see DoSetScrollPosition()
458 * @param[in] actor Handle of the text-view.
459 * @param[in] gesture Data structure with the parameters of the gesture.
461 void OnTextPan( Actor actor, PanGesture gesture );
464 * Ensures the text-view's boundaries are fully covered of text.
466 * i.e. if the text-view's size is 100x100 and the text's size is 150x100, the scroll position
467 * can be in the range -50,0 and 50,0.
469 void TrimScrollPosition();
472 * Called from SetScrollPosition() and OnTextPan()
474 * Updates the stored scroll position ensuring the text-view is always covered with text by calling
475 * TrimScrollPosition(), calculates the difference with the previous one and emits the Toolkit::TextView::SignalScrolled() signal.
477 * @param[in] position The new scroll position.
479 void DoSetScrollPosition( const Vector2& position );
482 * Combines width and height exceed policies.
484 * This method is a big switch() which combines two exceed policies into one.
485 * The aim is avoid this switch inside the relayout code.
487 * i.e. Width policy = Split. Height policy = Original. Internally the policy is SplitOriginal.
489 void CombineExceedPolicies();
492 * Retrieves the text-view's root actor which stores all text-actors.
493 * It could be the text-view itself or an actor used in the snapshot mode.
495 * @return the root actor.
497 Actor GetRootActor() const;
500 * Handles SetProperty for multiline policy.
501 * @param[in] propertyValue The new property value.
503 void OnMultilinePolicyPropertySet( Property::Value propertyValue );
506 * Handles SetProperty for width exceed policy.
507 * @param[in] propertyValue The new property value.
509 void OnWidthExceedPolicyPropertySet( Property::Value propertyValue );
512 * Handles SetProperty for height exceed policy.
513 * @param[in] propertyValue The new property value.
515 void OnHeightExceedPolicyPropertySet( Property::Value propertyValue );
518 * Handles SetProperty for line justification.
519 * @param[in] propertyValue The new property value.
521 void OnLineJustificationPropertySet( Property::Value propertyValue );
524 * Handles SetProperty for fade boundary.
525 * @param[in] propertyIndex The property index.
526 * @param[in] propertyValue The new property value.
528 void OnFadeBoundaryPropertySet( Property::Index propertyIndex, Property::Value propertyValue );
531 * Handles SetProperty for alignment property.
532 * @param[in] propertyIndex The property index.
533 * @param[in] propertyValue The new property value.
535 void OnAlignmentPropertySet( Property::Index propertyIndex, Property::Value propertyValue );
540 * The parameters which affects the layout of the text.
542 struct LayoutParameters
545 * Default constructor.
552 LayoutParameters( Toolkit::TextView::MultilinePolicy multilinePolicy,
553 Toolkit::TextView::ExceedPolicy widthExceedPolicy,
554 Toolkit::TextView::ExceedPolicy heightExceedPolicy,
555 Toolkit::Alignment::Type alignment,
556 Toolkit::TextView::LineJustification lineJustification,
557 float lineHeightOffset,
558 const std::string& ellipsizeText );
563 LayoutParameters( const LayoutParameters& layoutParameters );
566 * Assignment operator.
568 LayoutParameters& operator=( const LayoutParameters& layoutParameters );
570 Toolkit::TextView::MultilinePolicy mMultilinePolicy; ///< Stores the multiline policy.
571 TextView::ExceedPolicy mExceedPolicy; ///< Stores a combination of both policies;
572 Toolkit::TextView::ExceedPolicy mWidthExceedPolicy; ///< Stores the text width exceed policy.
573 Toolkit::TextView::ExceedPolicy mHeightExceedPolicy; ///< Stores the text height exceed policy.
574 Toolkit::Alignment::Type mHorizontalAlignment; ///< Stores the horizontal alignment for the whole text.
575 Toolkit::Alignment::Type mVerticalAlignment; ///< Stores the vertical alignment for the whole text.
576 Toolkit::TextView::LineJustification mLineJustification; ///< Stores the line justification.
577 float mLineHeightOffset; ///< Line height offset to be addded to the font line height (measured in PointSize).
578 MarkupProcessor::StyledTextArray mEllipsizeText; ///< Stores the ellipsize text.
582 * Some parameters which affects the text view visualization.
584 struct VisualParameters
587 * Default constructor.
594 VisualParameters( const VisualParameters& visualParameters );
597 * Assignment operator.
599 VisualParameters& operator=( const VisualParameters& visualParameters );
601 Toolkit::TextView::FadeBoundary mFadeBoundary; ///< Fade boundary used in fade mode.
602 float mSortModifier; ///< Stores the sort modifier for all text-actors.
603 Vector2 mCameraScrollPosition; ///< The scroll offset.
604 bool mSnapshotModeEnabled:1; ///< Whether text-view is rendered offscreen.
605 bool mScrollEnabled:1; ///< Whether the text scroll is enabled.
606 bool mScrollPositionTrimmed:1; ///< Whether the last scroll position set was trimmed.
610 * Temporary data used to calculate line justification.
612 struct LineJustificationInfo
614 TextViewProcessor::TextInfoIndices mIndices; ///< Indices to the first character of the new line.
615 float mLineLength; ///< Length of the line (or portion of line).
619 * The results of the relayout process.
624 * Default constructor.
631 RelayoutData( const RelayoutData& relayoutData );
634 * Assignment operator.
636 RelayoutData& operator=( const RelayoutData& relayoutData );
638 Size mTextViewSize; ///< The text-view's size used to relaid-out the text.
639 float mShrinkFactor; ///< Shrink factor used when the exceed policy contains ShrinkToFit.
640 TextViewProcessor::TextLayoutInfo mTextLayoutInfo; ///< Stores metrics, layout info (size, direction, type of word) and text-actor info for the whole text.
641 std::vector<int> mCharacterLogicalToVisualMap; ///< Reorder map that stores each character's visual (output) index according to its logical (input) index
642 std::vector<int> mCharacterVisualToLogicalMap; ///< Reorder map that stores each character's logical (input) index according to its visual (output) index
643 std::vector<RenderableActor> mGlyphActors; ///< Stores handles of those text-actors which are currently added to the text-view.
644 std::vector<RenderableActor> mEllipsizedGlyphActors; ///< Stores handles of those text-actors which are used to ellipsize the text.
645 Toolkit::TextView::CharacterLayoutInfoContainer mCharacterLayoutInfoTable; ///< Stores layout info per character sorted by the character's visual index.
646 Toolkit::TextView::LineLayoutInfoContainer mLines; ///< Stores an index to the first character of each line.
647 Size mTextSizeForRelayoutOption; ///< Stores the text size after relayout.
648 std::vector<LineJustificationInfo> mLineJustificationInfo; ///< Stores justification info per line.
649 TextActorCache mTextActorCache; ///< Stores previously created text-actors to be reused.
654 MarkupProcessor::StyledTextArray mCurrentStyledText; ///< text currently displayed by the view
655 std::vector<TextViewProcessorMetadata> mTextViewProcessorOperations; ///< Stores all relayout operations which arrive between two consecutive OnRelaidOut() calls.
657 LayoutParameters mLayoutParameters; ///< Stores some layout parameters in a struct. To be passed in layout functions.
658 VisualParameters mVisualParameters; ///< Some parameters which afects text-view visualization.
659 RelayoutData mRelayoutData; ///< struct with text-view's data structures used to pass all of them in one parameter.
660 RelayoutOperationMask mRelayoutOperations; ///< Which relayout operations have to be done.
662 Layer mOffscreenRootActor; ///< Root actor for offscreen rendering.
663 ImageActor mOffscreenImageActor; ///< Image actor for offscreen rendering.
664 CameraActor mOffscreenCameraActor; ///< Camera actor for offscreen rendering.
665 Size mCurrentOffscreenSize; ///< Current used ofscreen size.
666 FrameBufferImage mFrameBufferImage; ///< Frame buffer used for offscreen rendering.
667 RenderTask mRenderTask; ///< Used to generate an offscreen rendering.
669 PanGestureDetector mPanGestureDetector; ///< Pan gesture for text scrolling.
672 * Helper class used to prevent the modification of some members.
690 bool mLockPreviousSnapshotMode; ///< Whether previous stored snapshot mode should be modified.
691 bool mPreviousSnapshotModeEnabled:1; ///< Stores the previous snapshot mode value.
693 Toolkit::TextView::ScrolledSignalV2 mScrolledSignalV2; ///< Signal emitted when text is scrolled.
695 Property::Index mPropertyText; ///< Property index for text.
696 Property::Index mPropertyMultilinePolicy; ///< Property index for multiline policy.
697 Property::Index mPropertyWidthExceedPolicy; ///< Property index for width exceed policy.
698 Property::Index mPropertyHeightExceedPolicy; ///< Property index for height exceed policy.
699 Property::Index mPropertyLineJustification; ///< Property index for line justification policy.
700 Property::Index mPropertyFadeBoundaryLeft; ///< Property index for Left fade boundary.
701 Property::Index mPropertyFadeBoundaryRight; ///< Property index for Right fade boundary.
702 Property::Index mPropertyFadeBoundaryTop; ///< Property index for Top fade boundary.
703 Property::Index mPropertyFadeBoundaryBottom; ///< Property index for Bottom fade boundary.
704 Property::Index mPropertyLineHeightOffset; ///< Property index for Line height offset.
705 Property::Index mPropertyHorizontalAlignment; ///< Property index for Horizontal alignment.
706 Property::Index mPropertyVerticalAlignment; ///< Property index for Vertical alignment.
709 } // namespace Internal
711 // Helpers for public-api forwarding methods
713 inline Internal::TextView& GetImpl( TextView& textView )
715 DALI_ASSERT_ALWAYS( textView );
717 RefObject& handle = textView.GetImplementation();
719 return static_cast< Internal::TextView& >( handle );
722 inline const Internal::TextView& GetImpl( const TextView& textView )
724 DALI_ASSERT_ALWAYS( textView );
726 const RefObject& handle = textView.GetImplementation();
728 return static_cast< const Internal::TextView& >( handle );
731 } // namespace Toolkit
735 #endif // __DALI_TOOLKIT_INTERNAL_ITEM_VIEW_H__