1 #ifndef __DALI_TOOLKIT_INTERNAL_RELAYOUT_UTILITIES_H__
2 #define __DALI_TOOLKIT_INTERNAL_RELAYOUT_UTILITIES_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/alignment/alignment.h>
23 #include <dali-toolkit/public-api/controls/text-view/text-view.h>
24 #include <dali-toolkit/internal/controls/text-view/text-view-impl.h>
35 //Forward declarations.
38 namespace TextViewRelayout
41 extern const float MINIMUM_FADE_BOUNDARY; // When the fade boundary is the same as the text-view boundary, this constant reduces it in order to avoid a zero division.
44 * Define how to wrap a paragraph in lines.
46 enum HorizontalWrapType
48 WrapByCharacter, ///< Wrap the paragraph per character (It may split a word in two).
49 WrapByWord, ///< Wrap the paragraph by word.
50 WrapByWordAndSplit, ///< Wrap the paragraph by word and split a word if it doesn't fit.
51 WrapByParagraphCharacter, ///< Wrap the paragraph when a '\n' is found.
52 WrapByParagraphCharacterAndSplit ///< Wrap the paragraph when a '\n' is found and split if it doesn't fit.
56 * Different types of visibility tests (text-actor - text-view).
58 enum VisibilityTestType
60 FULLY_VISIBLE, ///< The text-actor is completely inside the text-view.
61 FULLY_VISIBLE_WIDTH, ///< The text-actor is completely between the right and the left boundaries of the text-view.
62 FULLY_VISIBLE_HEIGHT, ///< The text-actor is completely between the top and the bottom boundaries of the text-view.
63 PARTIALLY_VISIBLE, ///< The text-actor is partially inside the text-view.
64 PARTIALLY_VISIBLE_WIDTH, ///< The text-actor is partially inside the width of the text-view. It may be completely above and bellow the top and bottom boundaries of the text-view.
65 PARTIALLY_VISIBLE_HEIGHT ///< The text-actor is partially inside the height of the text-view. It may be completely on the left and on the right the left and right boundaries of the text-view.
69 * Temporary parameters used in the relayout process.
71 struct RelayoutParameters
74 * Default constructor.
76 * Initializes all members to their defaults.
83 * @note Added to increase coverage.
85 ~RelayoutParameters();
87 Vector3 mPositionOffset; ///< Offset (position.x + size.width, position.y, position.z) of the previous text-actor.
88 Size mParagraphSize; ///< Current paragraphs's size.
89 Size mWordSize; ///< Current word's size.
90 Size mCharacterSize; ///< Current character's size.
91 TextViewProcessor::TextInfoIndices mIndices; ///< Current indices to paragraph, word and character.
92 std::size_t mCharacterGlobalIndex; ///< Index to a single character within the whole text.
93 bool mIsFirstCharacter:1; ///< Whether is the first character of the whole text.
94 bool mIsFirstCharacterOfWord:1; ///< Whether is the first character of the word.
95 bool mIsNewLine:1; ///< Whether the current character is the first character of a new line.
96 bool mIsNewParagraphCharacter:1; ///< Whether the current character is a new paragraph character.
97 bool mIsWhiteSpace:1; ///< Whether the current character is a white space.
98 bool mIsVisible:1; ///< Whether the current character is visible.
102 * Parameters used to calculate the gradient of text-actors when fading is enabled.
104 struct FadeParameters
107 * Default constructor.
109 * Initializes all members to their defaults.
116 * @note Added to increase coverage.
120 float mRightFadeBoundary; ///< Distance from the right edge of the text-view to the right edge of the fade boundary.
121 float mRightFadeThreshold; ///< Point from where fade out starts (by right edge).
122 float mRightFadeBoundaryOffset; ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
123 float mRightFadeThresholdOffset; ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
124 Vector2 mRightAlphaCoeficients; ///< The fade out rect coeficients for the right side of the text-view.
125 float mLeftFadeBoundary; ///< Distance from the left edge of the text-view to the left edge of the fade boundary.
126 float mLeftFadeThreshold; ///< Point from where fade out starts (by left edge).
127 float mLeftFadeBoundaryOffset; ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
128 float mLeftFadeThresholdOffset; ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
129 Vector2 mLeftAlphaCoeficients; ///< The fade out rect coeficients for the left side of the text-view.
130 float mTopFadeBoundary; ///< Distance from the top edge of the text-view to the top edge of the fade boundary.
131 float mTopFadeThreshold; ///< Point from where fade out starts (by top edge).
132 float mTopFadeBoundaryOffset; ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
133 float mTopFadeThresholdOffset; ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
134 Vector2 mTopAlphaCoeficients; ///< The fade out rect coeficients for the top side of the text-view.
135 float mBottomFadeBoundary; ///< Distance from the bottom edge of the text-view to the bottom edge of the fade boundary.
136 float mBottomFadeThreshold; ///< Point from where fade out starts (by bottom edge).
137 float mBottomFadeBoundaryOffset; ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
138 float mBottomFadeThresholdOffset; ///< Same as above plus an offset if the value is zero. Used to avoid a zero division.
139 Vector2 mBottomAlphaCoeficients; ///< The fade out rect coeficients for the bottom side of the text-view.
140 bool mIsPartiallyVisible:1; ///< Whether the current character is partially visible.
144 * Parameters used to calculate the ellipsize.
146 struct EllipsizeParameters
149 * Default constructor.
151 * Initializes all members to their defaults.
153 EllipsizeParameters();
158 * @note Added to increase coverage.
160 ~EllipsizeParameters();
162 Vector3 mPosition; ///< Position of the first character of the ellipsize text.
163 float mLineDescender; ///< Distance from the base line to the bottom.
164 float mLineWidth; ///< Current line's width.
165 Size mEllipsizeBoundary; ///< Where to start to ellipsize a line.
166 std::size_t mFirstIndex; ///< Global index within the whole text of the first character of the line.
167 std::size_t mLastIndex; ///< Global index within the whole text of the last character of the line.
168 bool mEllipsizeLine:1; ///< Whether current line must be ellipsized.
169 bool mIsLineWidthFullyVisible:1; ///< Whether current line fits in text-view's width.
170 bool mIsLineHeightFullyVisible:1; ///< Whether current line fits in text-view's height.
171 bool mIsNextLineFullyVisibleHeight:1; ///< Whether next line fits in text-view's height.
172 bool mCreateEllipsizedTextActors:1; ///< Whether to create text-actors for the ellipsized text.
173 bool mLineFits:1; ///< Whether the current line fits in the boundary of the text-view.
174 bool mWordFits:1; ///< Whether the current word fits in the boundary of the text-view.
178 * Stores underline info for a group of consecutive characters in the same line.
183 * Default constructor.
185 * Initializes all members to their defaults.
192 * @note Added to increase coverage.
196 float mMaxHeight; ///< The maximum height.
197 float mMaxThickness; ///< The maximum underline's thickness.
198 float mPosition; ///< The underline's position of the character with the maximum underline's thickness.
202 * Stores underline info for each group of consecutive underlined characters.
203 * It also stores some status used when traversing the whole text.
205 struct TextUnderlineStatus
208 * Default constructor.
210 * Initializes each member to its default.
212 TextUnderlineStatus();
217 * @note Added to increase coverage.
219 ~TextUnderlineStatus();
221 std::vector<UnderlineInfo> mUnderlineInfo; ///< Underline info for each group of consecutive underlined characters.
222 std::size_t mCharacterGlobalIndex; ///< Global index (within the whole text) to current character.
223 std::size_t mLineGlobalIndex; ///< Index to current line. It takes into account the current layout configuration (is not the number of \n)
224 bool mCurrentUnderlineStatus:1; ///< Whether current character is underlined.
228 * Stores layout information of a line.
230 struct LineLayoutInfo
233 * Default constructor.
235 * Initializes each member to its default.
242 * @note Added to increase coverage.
246 float mLineLength; ///< The length of the portion of the paragraph which fits on the text-view width.
247 float mMaxCharHeight; ///< The maximum height of all characters of the portion of the paragraph which fits on the text-view width.
248 float mMaxAscender; ///< The maximum ascender of all characters of the portion of the paragraph which fits on the text-view width.
252 * Calculates the layout info of the portion of the paragraph which fits on the text-view width.
254 * @param[in] parentWidth Text-view width
255 * @param[in] indices Indices to the word and character.
256 * @param[in] paragraphLayoutInfo Layout info for the paragraph.
257 * @param[in] splitPolicy Whether a paragraph is wraped by word, by character or by word and character.
258 * @param[in] shrinkFactor Shrink factor used.
259 * @param[out] layoutInfo Layout information of the part of the paragraph which fits in the text-view width.
261 void CalculateLineLayout( float parentWidth,
262 const TextViewProcessor::TextInfoIndices& indices,
263 const TextViewProcessor::ParagraphLayoutInfo& paragraphLayoutInfo,
264 HorizontalWrapType splitPolicy,
266 LineLayoutInfo& layoutInfo );
269 * Reorders the text layout of each line of each paragraph of the text.
271 * @param[in,out] relayoutData The text-view's data structures.
273 void ReorderRightToLeftLayout( TextView::RelayoutData& relayoutData );
276 * Calculates the \e x offset position for the whole text.
278 * @param[in] horizontalTextAlignment The horizontal alignment type.
279 * @param[in] parentWidth The parent's width.
280 * @param[in] wholeTextWidth The whole text's width.
281 * @return The \e x position offset.
283 float CalculateXoffset( Toolkit::Alignment::Type horizontalTextAlignment, float parentWidth, float wholeTextWidth );
286 * Calculates the \e y offset position for the whole text.
288 * @param[in] verticalTextAlignment The vertical alignment type.
289 * @param[in] parentHeight The parent's height.
290 * @param[in] wholeTextHeight The whole text's height.
291 * @return The \e y position offset.
293 float CalculateYoffset( Toolkit::Alignment::Type verticalTextAlignment, float parentHeight, float wholeTextHeight );
296 * Calculates the \e x offset position for one line.
298 * @param[in] justification The line justification type.
299 * @param[in] wholeTextWidth The whole text's width.
300 * @param[in] lineLength The line's length.
301 * @return The \e x position offset.
304 float CalculateJustificationOffset( Toolkit::TextView::LineJustification justification, float wholeTextWidth, float lineLength );
307 * Whether text-actor is visible for Fade and Ellipsize exceed policies.
309 * It does different visibility tests according the given parameter \e type. @see VisibilityTestType.
311 * @param[in] position Position of the character.
312 * @param[in] size Size of the character.
313 * @param[in] parentSize Parent's size.
314 * @param[in] type One of FULLY_VISIBLE, PARTIALLY_VISIBLE, PARTIALLY_VISIBLE_WIDTH or PARTIALLI_VISIBLE_HEIGHT.
315 * @return \e true if is visible.
317 bool IsVisible( const Vector3& position, const Size& size, const Size& parentSize, VisibilityTestType type );
320 * Calculates the coeficients of the rect equation for the two given points.
322 * @param[in] p0 A point of the rect.
323 * @param[in] p1 Another point of the rect.
325 * @return The \e gradient is returned in the \e x member and the \e constant \e term is returned in the \e y value.
327 Vector2 CalculateRectParameters( const Vector2& p0, const Vector2& p1 );
330 * Aligns the whole text within the text-view.
332 * @param[in] layoutParameters The layout parameters.
333 * @param[in,out] relayoutData The text-view's data structures.
335 void UpdateAlignment( const TextView::LayoutParameters& layoutParameters,
336 TextView::RelayoutData& relayoutData );
339 * Calculates the bearing for the given character.
341 * @param[in,out] characterLayoutInfo Character layout info.
342 * @param[in,out] relayoutData The text-view's data structures.
344 void CalculateBearing( TextViewProcessor::CharacterLayoutInfo& characterLayoutInfo,
345 TextView::RelayoutData& relayoutData );
348 * Updates the character's layout info table.
350 * This table is used to pass the size, the position and other layout info to other controls/actors.
352 * @param[in,out] minMaxXY The boundary box of the whole text.
353 * @param[in,out] wordLayoutInfo Word layout info.
354 * @param[in,out] characterLayoutInfo Character layout info.
355 * @param[in,out] relayoutParameters Temporary layout parameters.
356 * @param[in,out] relayoutData The text-view's data structures.
358 void UpdateLayoutInfoTable( Vector4& minMaxXY,
359 TextViewProcessor::WordLayoutInfo& wordLayoutInfo,
360 TextViewProcessor::CharacterLayoutInfo& characterLayoutInfo,
361 RelayoutParameters& relayoutParameters,
362 TextView::RelayoutData& relayoutData );
365 * Calculates the text-actor visibility and fade parameters.
367 * @param[in] layoutParameters The layout parameters.
368 * @param[in] characterLayoutInfo Character layout info.
369 * @param[in] style The style of the character. Used to get the color (and alpha) of the character.
370 * @param[in,out] relayoutParameters Temporary layout parameters.
371 * @param[in,out] fadeParameters Temporary fade parameters.
372 * @param[in,out] relayoutData The text-view's data structures.
374 void CalculateVisibilityForFade( const Internal::TextView::LayoutParameters& layoutParameters,
375 TextViewProcessor::CharacterLayoutInfo& characterLayoutInfo,
376 const TextStyle& style,
377 RelayoutParameters& relayoutParameters,
378 FadeParameters& fadeParameters,
379 TextView::RelayoutData& relayoutData );
382 * Calculates the text-actor visibility and creates eliipsize text-actors.
384 * @param[in] layoutParameters The layout parameters.
385 * @param[in] characterLayoutInfo Character layout info.
386 * @param[in,out] ellipsizeParameters Temporary ellipsize parameters.
387 * @param[in,out] relayoutData The text-view's data structures.
389 void CalculateVisibilityForEllipsize( const Internal::TextView::LayoutParameters& layoutParameters,
390 TextViewProcessor::CharacterLayoutInfo& characterLayoutInfo,
391 EllipsizeParameters& ellipsizeParameters,
392 TextView::RelayoutData& relayoutData );
395 * Creates the actors needed for the ellipsized text.
397 * @param[in,out] ellipsizeParameters Temporary ellipsize parameters.
398 * @param[in,out] relayoutData The text-view's data structures.
400 void CreateEllipsizeTextActor( const EllipsizeParameters& ellipsizeParameters,
401 TextView::RelayoutData& relayoutData );
404 * Replace the text which exceeds the boundary by the ellipsis text.
406 * @param[in] layoutParameters The layout parameters.
407 * @param[in,out] ellipsisParameters Temporary ellipsis parameters.
408 * @param[in,out] relayoutData The text-view's data structures.
410 void EllipsizeLine( const TextView::LayoutParameters& layoutParameters,
411 EllipsizeParameters& ellipsizeParameters,
412 TextView::RelayoutData& relayoutData );
415 * Traverse all text data structure setting its visibility to true.
417 * @param[in,out] relayoutData The text-view's data structures.
419 void SetTextVisible( TextView::RelayoutData& relayoutData );
422 * Calculates the visibility and fade parameters.
424 * @param[in] layoutParameters The layout parameters.
425 * @param[in] visualParameters Some visual parameters (fade, sort modifier and blending).
426 * @param[in,out] relayoutData The text-view's data structures.
428 void UpdateVisibilityForFade( const TextView::LayoutParameters& layoutParameters,
429 const TextView::VisualParameters& visualParameters,
430 TextView::RelayoutData& relayoutData );
432 * Calculates the visibility for text ellipsize.
434 * @param[in] layoutParameters The layout parameters.
435 * @param[in] visualParameters Some visual parameters (fade, sort modifier and blending).
436 * @param[in,out] relayoutData The text-view's data structures.
438 void UpdateVisibilityForEllipsize( const TextView::LayoutParameters& layoutParameters,
439 const TextView::VisualParameters& visualParameters,
440 TextView::RelayoutData& relayoutData );
442 * Calculates the visibility and fade parameters.
444 * @param[in] layoutParameters The layout parameters.
445 * @param[in] visualParameters Some visual parameters (fade, sort modifier and blending).
446 * @param[in,out] relayoutData The text-view's data structures.
448 void UpdateVisibility( const TextView::LayoutParameters& layoutParameters,
449 const TextView::VisualParameters& visualParameters,
450 TextView::RelayoutData& relayoutData );
453 * Traverse all text initializing all non initialized text-actor handles
454 * and updating text-actor handles with new size, position, ...
456 * @param[in] visualParameters Some visual parameters (fade, sort modifier and blending).
457 * @param[in,out] relayoutData Natural size (metrics), layout, text-actor info.
458 * @param[in] createGlyphActors Whether to create RenderableActor for text-actors or emojis.
460 void UpdateTextActorInfo( const TextView::VisualParameters& visualParameters,
461 TextView::RelayoutData& relayoutData,
462 bool createGlyphActors );
465 * Traverses the whole text and for each piece of underlined text,
466 * it calculates the maximum thickness and the position of that particular piece of underlined text.
468 * @param[in,out] relayoutData Natural size (metrics), layout, text-actor info and conversion from visual to logical order and vice versa (for RTL text).
470 void CalculateUnderlineInfo( TextView::RelayoutData& relayoutData );
473 * Traverses the whole text and for each piece of underlined text,
474 * it sets the previously calculated maximum thickness and the position of that particular piece of underlined text.
476 * @param[in,out] relayoutData Natural size (metrics), layout, text-actor info and conversion from visual to logical order and vice versa (for RTL text).
478 void SetUnderlineInfo( TextView::RelayoutData& relayoutData );
481 * Remove renderable-actor from the text-view.
483 * @param[in,out] textView The text-view.
484 * @param[in] glyphActors renderable-actors to be removed from the text-view.
486 void RemoveGlyphActors( Actor textView,
487 const std::vector<RenderableActor>& glyphActors );
490 * Inserts the text-actors into the text-view and the text-actor's list.
492 * @param[in,out] textView The text-view.
493 * @param[in,out] relayoutData The text-view's data structures.
495 void InsertToTextView( Actor textView,
496 TextView::RelayoutData& relayoutData );
499 * Retrieves a new glyph-actor from the cache of text-actors or creating a new one if it's empty.
501 * @param[in] text The text-actor's text.
502 * @param[in] style The text-actor's style.
503 * @param[in] cache The cache of text-actors.
505 * @return a RenderableActor with the text's glyph.
507 RenderableActor CreateGlyphActor( const Text& text, const TextStyle& style, TextActorCache& cache );
509 } // namespace TextViewRelayout
511 } // namespace Internal
513 } // namespace Toolkit
517 #endif // __DALI_TOOLKIT_INTERNAL_RELAYOUT_UTILITIES_H__