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 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/control-impl.h>
23 #include <dali-toolkit/public-api/controls/text-view/text-view.h>
24 #include <dali-toolkit/internal/controls/text-view/text-actor-cache.h>
25 #include <dali-toolkit/internal/controls/text-view/text-view-processor-types.h>
37 * TextView is a custom control for text aligning and multiline support
39 class TextView : public Control
46 TEXTVIEW_PROPERTY_START_INDEX = Control::CONTROL_PROPERTY_END_INDEX + 1,
47 TEXTVIEW_PROPERTY_END_INDEX = TEXTVIEW_PROPERTY_START_INDEX + 1000 ///< Reserving 1000 property indices
51 * Internal exceed policy with the valid combinations.
55 Original, ///< Original size (even if it exceeds the witdh or the height).
56 OriginalFade, ///< Original size if it exceeds the width but faded if it exceeds the height.
57 OriginalShrink, ///< Shrunk if it exceeds the height.
58 SplitOriginal, ///< Split if it exceeds the width but no action if it exceeds the height.
59 SplitFade, ///< Split if it exceeds the width and faded if it exceeds the height.
60 SplitShrink, ///< Split if it exceeds the width and shrunk if it exceeds the height.
61 SplitEllipsizeEnd, ///< Split if it exceeds the width and ellipsize if it exceeds the height.
62 Fade, ///< Faded if it exceeds any boundary.
63 FadeOriginal, ///< Faded if it exceeds the width but no action if it exceeds the height.
64 ShrinkOriginal, ///< Shrunk if it exceeds the width but no action if it exceeds the height.
65 ShrinkFade, ///< Shrunk if it exceeds the width and faded if it exceeds the height.
66 Shrink, ///< Shrunk if it exceeds any boundary.
67 EllipsizeEndOriginal, ///< Ellipsized by the end if it exceeds the width but no action if it exceeds the height.
68 EllipsizeEnd ///< Ellipsized by the end if it exceeds the width and/or the height.
71 // Between two OnRelaidOut methods, several calls to InsertTextAt, RemoveTextFrom or SetText can happen.
72 // TextViewProcessorMetadata stores the type of operation. A vector stores all operations between two OnRelaidOut calls.
74 enum TextViewProcessorMetadataType
76 TextSet, ///< Sets new text.
77 TextInserted, ///< Inserts text into current text.
78 TextReplaced, ///< Replaces some text from current text.
79 TextRemoved, ///< Removes some text from current text.
80 NewLineHeight, ///< Sets a new line height offset.
81 NewStyle ///< Sets a new style to the whole text.
85 * Stores info about which data structures need to be modified when the OnRelaidOut() method is called
87 struct TextViewProcessorMetadata
89 TextViewProcessorMetadata();
91 TextViewProcessorMetadataType mType; ///< Stores the type of operation.
92 std::size_t mPosition; ///< Character position within the text.
93 std::size_t mNumberOfCharacters; ///< Number of characters to be removed/ replaced.
94 MarkupProcessor::StyledTextArray mText; ///< The new text.
95 TextStyle::Mask mStyleMask; ///< The style mask.
99 * Defines which operations have to be done in the relayout process.
101 enum RelayoutOperationMask
103 NO_RELAYOUT = 0x0, ///< Does nothing.
104 RELAYOUT_REMOVE_TEXT_ACTORS = 0x1, ///< Removes current text-actors from the text-view.
105 RELAYOUT_SIZE_POSITION = 0x2, ///< Calculates size and position of the text but it doesn't calculate alignment.
106 RELAYOUT_ALIGNMENT = 0x4, ///< Aligns the whole text.
107 RELAYOUT_VISIBILITY = 0x8, ///< Calculates the visibility.
108 RELAYOUT_INITIALIZE_TEXT_ACTORS = 0x10, ///< Initialize text-actors (create handles).
109 RELAYOUT_TEXT_ACTOR_UPDATE = 0x20, ///< Updates text-actors (set size, position, style, ...)
110 RELAYOUT_INSERT_TO_TEXT_VIEW = 0x40, ///< Adds the text-actors to the text-view.
111 RELAYOUT_INSERT_TO_TEXT_ACTOR_LIST = 0x80, ///< Inserts the text-actors to the text-actor list.
112 RELAYOUT_ALL = 0xFF ///< Does all operations.
115 //////////////////////////////////////////////
118 * Create a new TextView.
119 * @return A smart-pointer to the newly allocated TextView.
121 static Toolkit::TextView New();
124 * @copydoc SetText( const std::string& text )
126 void SetText( const std::string& text );
129 * @copydoc SetText( const StyledTextArray& text )
131 void SetText( const MarkupProcessor::StyledTextArray& text );
134 * @copydoc InsertTextAt( std::size_t position, const std::string& text )
136 void InsertTextAt( std::size_t position, const std::string& text );
139 * @copydoc InsertTextAt( std::size_t position, const std::string& text )
141 void InsertTextAt( std::size_t position, const MarkupProcessor::StyledTextArray& text );
144 * @copydoc RemoveTextFrom( std::size_t position, std::size_t numberOfCharacters )
146 void RemoveTextFrom( std::size_t position, std::size_t numberOfCharacters );
149 * @copydoc ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text )
151 void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text );
154 * @copydoc ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const std::string& text )
156 void ReplaceTextFromTo( std::size_t position, std::size_t numberOfCharacters, const MarkupProcessor::StyledTextArray& text );
161 std::string GetText() const;
164 * @copydoc SetLineHeightOffset()
166 void SetLineHeightOffset( PointSize offset );
169 * @copydoc GetLineHeightOffset()
171 PointSize GetLineHeightOffset() const;
174 * @copydoc SetStyleToCurrentText()
176 void SetStyleToCurrentText( const TextStyle& style, TextStyle::Mask mask );
179 * @copydoc SetTextAlignment( Toolkit::Alignment::Type align )
181 void SetTextAlignment( Toolkit::Alignment::Type align );
184 * @copydoc GetTextAlignment()
186 Toolkit::Alignment::Type GetTextAlignment() const;
189 * @copydoc SetMultilinePolicy()
191 void SetMultilinePolicy( Toolkit::TextView::MultilinePolicy policy );
194 * @copydoc GetMultilinePolicy()
196 Toolkit::TextView::MultilinePolicy GetMultilinePolicy() const;
199 * @copydoc SetWidthExceedPolicy()
201 void SetWidthExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
204 * @copydoc GetWidthExceedPolicy()
206 Toolkit::TextView::ExceedPolicy GetWidthExceedPolicy() const;
209 * @copydoc SetHeightExceedPolicy()
211 void SetHeightExceedPolicy( Toolkit::TextView::ExceedPolicy policy );
214 * @copydoc GetHeightExceedPolicy()
216 Toolkit::TextView::ExceedPolicy GetHeightExceedPolicy() const;
219 * @copydoc SetLineJustification()
221 void SetLineJustification( Toolkit::TextView::LineJustification justification );
224 * @copydoc GetLineJustification()
226 Toolkit::TextView::LineJustification GetLineJustification() const;
229 * @copydoc SetFadeBoundary()
231 void SetFadeBoundary( const Toolkit::TextView::FadeBoundary& fadeBoundary );
234 * @copydoc GetFadeBoundary()
236 const Toolkit::TextView::FadeBoundary& GetFadeBoundary() const;
239 * @copydoc SetEllipsizeText()
241 void SetEllipsizeText( const std::string& ellipsizeText );
244 * @copydoc SetEllipsizeText()
246 void SetEllipsizeText( const MarkupProcessor::StyledTextArray& ellipsizeText );
249 * @copydoc GetEllipsizeText()
251 std::string GetEllipsizeText() const;
254 * Checks if relayout the text is needed. If it is, it relais out the text
255 * by calling DoRelayOut().
257 void GetTextLayoutInfo();
260 * Calls GetTextLayoutInfo() and fills the given data structure.
262 * @see GetTextLayoutInfo()
264 void GetTextLayoutInfo( Toolkit::TextView::TextLayoutInfo& textLayoutInfo );
267 * @copydoc SetSortModifier()
269 void SetSortModifier( float depthOffset );
272 * @copydoc SetSnapshotModeEnabled()
274 void SetSnapshotModeEnabled( bool enable );
277 * @copydoc IsSnapshotModeEnabled()
279 bool IsSnapshotModeEnabled() const;
282 * @brief Sets whether markup processing should be carried out.
284 * @param[in] enable whether markup processing is carried out or not.
286 void SetMarkupProcessingEnabled( bool enable );
289 * @brief Returns whether markup processing is enabled or not
291 * @return true is markup processing is enabled
293 bool IsMarkupProcessingEnabled() const;
296 * @copydoc SetScrollEnabled()
298 void SetScrollEnabled( bool enable );
301 * @copydoc IsScrollEnabled()
303 bool IsScrollEnabled() const;
306 * @copydoc SetScrollPosition()
307 * @see DoSetScrollPosition()
309 void SetScrollPosition( const Vector2& position );
312 * @copydoc GetScrollPosition()
314 const Vector2& GetScrollPosition() const;
317 * @copydoc IsScrollPositionTrimmed()
319 bool IsScrollPositionTrimmed() const;
322 * @copydoc ScrolledSignal()
324 Toolkit::TextView::ScrolledSignalV2& ScrolledSignal();
327 * Connects a callback function with the object's signals.
328 * @param[in] object The object providing the signal.
329 * @param[in] tracker Used to disconnect the signal.
330 * @param[in] signalName The signal to connect to.
331 * @param[in] functor A newly allocated FunctorDelegate.
332 * @return True if the signal was connected.
333 * @post If a signal was connected, ownership of functor was passed to CallbackBase. Otherwise the caller is responsible for deleting the unused functor.
335 static bool DoConnectSignal( BaseObject* object, ConnectionTrackerInterface* tracker, const std::string& signalName, FunctorDelegate* functor );
340 * Called when a property of an object of this type is set.
341 * @param[in] object The object whose property is set.
342 * @param[in] index The property index.
343 * @param[in] value The new property value.
345 static void SetProperty( BaseObject* object, Property::Index index, const Property::Value& value );
348 * Called to retrieve a property of an object of this type.
349 * @param[in] object The object whose property is to be retrieved.
350 * @param[in] index The property index.
351 * @return The current value of the property.
353 static Property::Value GetProperty( BaseObject* object, Property::Index index );
356 private: // From Control
359 * @copydoc Toolkit::Control::OnInitialize()
361 virtual void OnInitialize();
364 * @copydoc Toolkit::Control::OnFontChange( )
366 virtual void OnFontChange( bool defaultFontChange, bool defaultFontSizeChange );
369 * @copydoc Toolkit::Control::OnControlSizeSet()
371 virtual void OnControlSizeSet( const Vector3& size );
374 * @copydoc Toolkit::Control::OnRelaidOut()
376 * Removes text-actor and calls DoRelayOut()..
378 virtual void OnRelaidOut( Vector2 size, ActorSizeContainer& container );
381 * Retrieves the text-view's natural size.
383 * @return The natural size.
385 virtual Vector3 GetNaturalSize();
388 * Retrieves the text-view's \e height for a given \e width.
390 * @param[in] width The given \e width.
392 * @return The \e height for the given \e width.
394 virtual float GetHeightForWidth( float width );
397 * Retrieves the text-view's \e width for a given \e height.
399 * @param[in] height The given \e height.
401 * @return The \e width for the given \e height.
403 virtual float GetWidthForHeight( float height );
408 * Construct a new TextView.
413 * A reference counted object may only be deleted by calling Unreference()
420 TextView( const TextView& );
423 TextView& operator=( const TextView& rhs );
426 * Executes synchronously relayout operations such as set, insert, remove or replace text, or
427 * split groups of characters, etc.
429 void PerformTextViewProcessorOperations();
432 * Optimizes some text-view processor operations.
434 void OptimizeTextViewProcessorOperations();
437 * Synchronously relays-out all text-actors.
439 * Perform text-view-processor operations, sets the new size and position of text-actors and adds them to the text-view.
441 * @param[in] textViewSize The new text-view's size.
442 * @param[in] relayoutOperationMask Defines which operations need to be done in the relayout process.
444 void DoRelayOut( const Size& textViewSize, RelayoutOperationMask relayoutOperationMask );
447 * Process Snapshot. It refresh the render-task in order to generate a new snapshot image.
449 * ProcessSnapshot is called from OnRelaidOut() only if text has been relaid out.
450 * It creates a new image buffer only if the size of the text has changed.
452 * @param[in] textViewSize The new text-view's size.
454 void ProcessSnapshot( const Size& textViewSize );
457 * Aligns the offscreen rendering camera actor to cover the whole text and the resulting image actor accordingly with the text view's alignment.
459 * @param[in] textViewSize The text view's size.
460 * @param[in] offscreenSize The offscreen's frame buffer's size.
462 void AlignOffscreenCameraActor( const Size& textViewSize, const Size& offscreenSize );
465 * Callback called when the render task has processed.
467 * It makes the root actor invisible.
469 * @param[in] renderTask The processed render task.
471 void RenderTaskFinished( Dali::RenderTask& renderTask );
474 * Destroys offscreen rendering resources.
476 * It disconects the render task finished signal from the TextView::RenderTaskFinished() method,
477 * removes the render task from the render task list and resets the offscreen camera actor, root actor,
478 * image actor and the frame buffer.
480 void DestroyOffscreenRenderingResources();
483 * Called when text-view is scrolled.
485 * Sets the new scroll position. @see DoSetScrollPosition()
487 * @param[in] actor Handle of the text-view.
488 * @param[in] gesture Data structure with the parameters of the gesture.
490 void OnTextPan( Actor actor, PanGesture gesture );
493 * Ensures the text-view's boundaries are fully covered of text.
495 * i.e. if the text-view's size is 100x100 and the text's size is 150x100, the scroll position
496 * can be in the range -50,0 and 50,0.
498 void TrimScrollPosition();
501 * Called from SetScrollPosition() and OnTextPan()
503 * Updates the stored scroll position ensuring the text-view is always covered with text by calling
504 * TrimScrollPosition(), calculates the difference with the previous one and emits the Toolkit::TextView::SignalScrolled() signal.
506 * @param[in] position The new scroll position.
508 void DoSetScrollPosition( const Vector2& position );
511 * Combines width and height exceed policies.
513 * This method is a big switch() which combines two exceed policies into one.
514 * The aim is avoid this switch inside the relayout code.
516 * i.e. Width policy = Split. Height policy = Original. Internally the policy is SplitOriginal.
518 void CombineExceedPolicies();
521 * Retrieves the text-view's root actor which stores all text-actors.
522 * It could be the text-view itself or an actor used in the snapshot mode.
524 * @return the root actor.
526 Actor GetRootActor() const;
529 * Handle SetProperty for markup processing.
530 * @param[in] propertyValue The new property value.
532 void OnMarkupEnabledPeopertySet( Property::Value propertyValue );
535 * Handles SetProperty for multiline policy.
536 * @param[in] propertyValue The new property value.
538 void OnMultilinePolicyPropertySet( Property::Value propertyValue );
541 * Handles SetProperty for width exceed policy.
542 * @param[in] propertyValue The new property value.
544 void OnWidthExceedPolicyPropertySet( Property::Value propertyValue );
547 * Handles SetProperty for height exceed policy.
548 * @param[in] propertyValue The new property value.
550 void OnHeightExceedPolicyPropertySet( Property::Value propertyValue );
553 * Handles SetProperty for line justification.
554 * @param[in] propertyValue The new property value.
556 void OnLineJustificationPropertySet( Property::Value propertyValue );
559 * Handles SetProperty for fade boundary.
560 * @param[in] propertyValue The new property value.
562 void OnFadeBoundaryPropertySet( Property::Value propertyValue );
565 * Handles SetProperty for alignment property.
566 * @param[in] propertyIndex The property index.
567 * @param[in] propertyValue The new property value.
569 void OnAlignmentPropertySet( Property::Index propertyIndex, Property::Value propertyValue );
572 * Handles GetProperty for horizontal alignment property.
573 * @return The property value of horizontal alignment.
575 std::string OnHorizontalAlignmentPropertyGet();
578 * Handles GetProperty for vertical alignment property.
579 * @return The property value of vertical alignment.
581 std::string OnVerticalAlignmentPropertyGet();
586 * The parameters which affects the layout of the text.
588 struct LayoutParameters
591 * Default constructor.
598 LayoutParameters( Toolkit::TextView::MultilinePolicy multilinePolicy,
599 Toolkit::TextView::ExceedPolicy widthExceedPolicy,
600 Toolkit::TextView::ExceedPolicy heightExceedPolicy,
601 Toolkit::Alignment::Type alignment,
602 Toolkit::TextView::LineJustification lineJustification,
603 float lineHeightOffset,
604 const std::string& ellipsizeText,
605 bool markUpEnabled );
610 LayoutParameters( const LayoutParameters& layoutParameters );
613 * Assignment operator.
615 LayoutParameters& operator=( const LayoutParameters& layoutParameters );
617 Toolkit::TextView::MultilinePolicy mMultilinePolicy; ///< Stores the multiline policy.
618 TextView::ExceedPolicy mExceedPolicy; ///< Stores a combination of both policies;
619 Toolkit::TextView::ExceedPolicy mWidthExceedPolicy; ///< Stores the text width exceed policy.
620 Toolkit::TextView::ExceedPolicy mHeightExceedPolicy; ///< Stores the text height exceed policy.
621 Toolkit::Alignment::Type mHorizontalAlignment; ///< Stores the horizontal alignment for the whole text.
622 Toolkit::Alignment::Type mVerticalAlignment; ///< Stores the vertical alignment for the whole text.
623 Toolkit::TextView::LineJustification mLineJustification; ///< Stores the line justification.
624 float mLineHeightOffset; ///< Line height offset to be addded to the font line height (measured in PointSize).
625 MarkupProcessor::StyledTextArray mEllipsizeText; ///< Stores the ellipsize text
626 bool mMarkUpEnabled:1; ///< Is markup string scanning enabled
630 * Some parameters which affects the text view visualization.
632 struct VisualParameters
635 * Default constructor.
642 VisualParameters( const VisualParameters& visualParameters );
645 * Assignment operator.
647 VisualParameters& operator=( const VisualParameters& visualParameters );
649 Toolkit::TextView::FadeBoundary mFadeBoundary; ///< Fade boundary used in fade mode.
650 float mSortModifier; ///< Stores the sort modifier for all text-actors.
651 Vector2 mCameraScrollPosition; ///< The scroll offset.
652 bool mSnapshotModeEnabled:1; ///< Whether text-view is rendered offscreen.
653 bool mScrollEnabled:1; ///< Whether the text scroll is enabled.
654 bool mScrollPositionTrimmed:1; ///< Whether the last scroll position set was trimmed.
658 * Temporary data used to calculate line justification.
660 struct LineJustificationInfo
662 TextViewProcessor::TextInfoIndices mIndices; ///< Indices to the first character of the new line.
663 float mLineLength; ///< Length of the line (or portion of line).
667 * The results of the relayout process.
672 * Default constructor.
679 RelayoutData( const RelayoutData& relayoutData );
682 * Assignment operator.
684 RelayoutData& operator=( const RelayoutData& relayoutData );
686 Size mTextViewSize; ///< The text-view's size used to relaid-out the text.
687 float mShrinkFactor; ///< Shrink factor used when the exceed policy contains ShrinkToFit.
688 TextViewProcessor::TextLayoutInfo mTextLayoutInfo; ///< Stores metrics, layout info (size, direction, type of word) and text-actor info for the whole text.
689 std::vector<int> mCharacterLogicalToVisualMap; ///< Reorder map that stores each character's visual (output) index according to its logical (input) index
690 std::vector<int> mCharacterVisualToLogicalMap; ///< Reorder map that stores each character's logical (input) index according to its visual (output) index
691 std::vector<RenderableActor> mGlyphActors; ///< Stores handles of those text-actors which are currently added to the text-view.
692 std::vector<RenderableActor> mEllipsizedGlyphActors; ///< Stores handles of those text-actors which are used to ellipsize the text.
693 Toolkit::TextView::CharacterLayoutInfoContainer mCharacterLayoutInfoTable; ///< Stores layout info per character sorted by the character's visual index.
694 Toolkit::TextView::LineLayoutInfoContainer mLines; ///< Stores an index to the first character of each line.
695 Size mTextSizeForRelayoutOption; ///< Stores the text size after relayout.
696 std::vector<LineJustificationInfo> mLineJustificationInfo; ///< Stores justification info per line.
697 TextActorCache mTextActorCache; ///< Stores previously created text-actors to be reused.
702 MarkupProcessor::StyledTextArray mCurrentStyledText; ///< text currently displayed by the view
703 std::vector<TextViewProcessorMetadata> mTextViewProcessorOperations; ///< Stores all relayout operations which arrive between two consecutive OnRelaidOut() calls.
705 LayoutParameters mLayoutParameters; ///< Stores some layout parameters in a struct. To be passed in layout functions.
706 VisualParameters mVisualParameters; ///< Some parameters which afects text-view visualization.
707 RelayoutData mRelayoutData; ///< struct with text-view's data structures used to pass all of them in one parameter.
708 RelayoutOperationMask mRelayoutOperations; ///< Which relayout operations have to be done.
710 Layer mOffscreenRootActor; ///< Root actor for offscreen rendering.
711 ImageActor mOffscreenImageActor; ///< Image actor for offscreen rendering.
712 CameraActor mOffscreenCameraActor; ///< Camera actor for offscreen rendering.
713 Size mCurrentOffscreenSize; ///< Current used ofscreen size.
714 FrameBufferImage mFrameBufferImage; ///< Frame buffer used for offscreen rendering.
715 RenderTask mRenderTask; ///< Used to generate an offscreen rendering.
717 PanGestureDetector mPanGestureDetector; ///< Pan gesture for text scrolling.
720 * Helper class used to prevent the modification of some members.
738 bool mLockPreviousSnapshotMode; ///< Whether previous stored snapshot mode should be modified.
739 bool mPreviousSnapshotModeEnabled:1; ///< Stores the previous snapshot mode value.
740 bool mMarkUpEnabled:1; ///< enable to scan for mark-up
742 Toolkit::TextView::ScrolledSignalV2 mScrolledSignalV2; ///< Signal emitted when text is scrolled.
745 } // namespace Internal
747 // Helpers for public-api forwarding methods
749 inline Internal::TextView& GetImpl( TextView& textView )
751 DALI_ASSERT_ALWAYS( textView );
753 RefObject& handle = textView.GetImplementation();
755 return static_cast< Internal::TextView& >( handle );
758 inline const Internal::TextView& GetImpl( const TextView& textView )
760 DALI_ASSERT_ALWAYS( textView );
762 const RefObject& handle = textView.GetImplementation();
764 return static_cast< const Internal::TextView& >( handle );
767 } // namespace Toolkit
771 #endif // __DALI_TOOLKIT_INTERNAL_ITEM_VIEW_H__