1 #ifndef __DALI_TOOLKIT_TEXT_VISUAL_MODEL_IMPL_H__
2 #define __DALI_TOOLKIT_TEXT_VISUAL_MODEL_IMPL_H__
5 * Copyright (c) 2015 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/public-api/common/dali-vector.h>
23 #include <dali/public-api/common/intrusive-ptr.h>
24 #include <dali/public-api/object/ref-object.h>
27 #include <dali-toolkit/internal/text/line-run.h>
42 typedef IntrusivePtr<VisualModel> VisualModelPtr;
45 * @brief A visual text model contains layout specific information.
48 * - A series of glyphs in visual order i.e. after the bidirectional reordering.
49 * - The position of each glyph within a 2D bounding box.
51 class VisualModel : public RefObject
56 * @brief Create a new instance of a VisualModel.
58 * @return A pointer to a new VisualModel.
60 static VisualModelPtr New();
65 * @brief Replaces any glyphs previously set.
67 * @note If the number of glyphs is zero, all buffers are cleared.
68 * @note If one pointer is NULL and the number of glyphs is not zero, the buffer is not touched.
70 * @param[in] glyphs An array of glyphs in the visual order.
71 * @param[in] characterIndices An array containing the first character in the logical model that each glyph relates to.
72 * @param[in] charactersPerGlyph An array containing the number of characters per glyph.
73 * @param[in] numberOfGlyphs The number of glyphs.
75 void SetGlyphs( const GlyphInfo* glyphs,
76 const CharacterIndex* characterIndices,
77 const Length* charactersPerGlyph,
78 Length numberOfGlyphs );
81 * @brief Creates the character to glyph conversion table.
83 * @param[in] numberOfCharacters The number of characters.
85 void CreateCharacterToGlyphTable( Length numberOfCharacters = 0u );
88 * @brief Creates an array containing the number of glyphs per character.
90 * @param[in] numberOfCharacters The number of characters.
92 void CreateGlyphsPerCharacterTable( Length numberOfCharacters = 0u );
95 * Retrieves the number of glyphs.
97 * @return The number of glyphs.
99 Length GetNumberOfGlyphs() const;
102 * @brief Retrieves glyphs in the given buffer.
104 * The size of the @p glyphs buffer needs to be big enough to copy the @p numberOfGlyphs.
105 * @param[out] glyphs Pointer to a buffer where the glyphs are copied.
106 * @param[in] glyphIndex Index to the first glyph.
107 * @param[in] numberOfGlyphs Number of glyphs to be copied.
109 void GetGlyphs( GlyphInfo* glyphs,
110 GlyphIndex glyphIndex,
111 Length numberOfGlyphs ) const;
116 * @param[in] glyphIndex Index to a glyph.
120 const GlyphInfo& GetGlyphInfo( GlyphIndex glyphIndex ) const;
125 * If the @p numberOfGlyphsToRemove is zero, this operation is like an insert.
126 * If the @p numberOfGlyphsToInsert is zero, this operation is like a remove.
128 * @param[in] glyphIndex Where to replace the glyphs.
129 * @param[in] numberOfGlyphsToRemove The number of glyphs to be removed.
130 * @param[in] glyphs Pointer to a buffer with the new glyphs.
131 * @param[in] numberOfCharacters Pointer to a buffer with the number of characters per glyph.
132 * @param[in] numberOfGlyphsToInsert The number of new glyphs in the buffer.
134 void ReplaceGlyphs( GlyphIndex glyphIndex,
135 Length numberOfGlyphsToRemove,
136 const GlyphInfo* const glyphs,
137 const Length* const numberOfCharacters,
138 Length numberOfGlyphsToInsert );
140 // Character <--> Glyph conversion
143 * @brief Retrieves the first character in the logical model which a glyph represents.
145 * @note After shaping several characters may be represented by the same glyph.
146 * Alternatively several glyphs may be required to display a character.
147 * @param[in] glyphIndex The glyph index.
148 * @return The character index.
150 CharacterIndex GetCharacterIndex( GlyphIndex glyphIndex ) const;
153 * @brief Query the number of characters the glyph represents.
155 * @param[in] glyphIndex The glyph index.
156 * @return The number of characters represented by the glyph.
158 Length GetCharactersPerGlyph( GlyphIndex glyphIndex ) const;
161 * Retrieves the first glyph in the visual model which represents a given character.
163 * @note After shaping several characters may be represented by the same glyph.
164 * Alternatively several glyphs may be required to display a character.
165 * @param[in] characterIndex The character index.
166 * @return The glyph index.
168 GlyphIndex GetGlyphIndex( CharacterIndex characterIndex ) const;
171 * Retrieves the whole or part of the character to glyph conversion map.
173 * The size of the buffer needs to be big enough to copy the @p numberOfCharacters.
175 * @param[out] characterToGlyphMap Pointer to a buffer where the conversion map is copied.
176 * @param[in] characterIndex Index to the first character.
177 * @param[in] numberOfCharacters The number of characters.
179 void GetCharacterToGlyphMap( GlyphIndex* characterToGlyphMap,
180 CharacterIndex characterIndex,
181 Length numberOfCharacters ) const;
184 * Retrieves the whole or part of the glyph to character conversion map.
186 * The size of the buffer needs to be big enough to copy the @p numberOfGlyphs.
188 * @param[out] glyphToCharacter Pointer to a buffer where the conversion map is copied.
189 * @param[in] glyphIndex Index to the first glyph.
190 * @param[in] numberOfGlyphs The number of glyphs.
192 void GetGlyphToCharacterMap( CharacterIndex* glyphToCharacter,
193 GlyphIndex glyphIndex,
194 Length numberOfGlyphs ) const;
197 * Retrieves for each glyph the number of characters the glyph represents.
199 * @param[out] charactersPerGlyph Pointer to a buffer where the number of characters for each glyph are copied.
200 * @param[in] glyphIndex Index to the first glyph.
201 * @param[in] numberOfGlyphs The number of glyphs.
203 void GetCharactersPerGlyphMap( Length* charactersPerGlyph,
204 GlyphIndex glyphIndex,
205 Length numberOfGlyphs ) const;
208 * Retrieves for each character the number of glyphs the character is shaped.
210 * @param[out] glyphsPerCharacter Pointer to a buffer where the number of glyphs for each character are copied.
211 * @param[in] characterIndex Index to the first character.
212 * @param[in] numberOfCharacters The number of characters.
214 void GetGlyphsPerCharacterMap( Length* glyphsPerCharacter,
215 CharacterIndex characterIndex,
216 Length numberOfCharacters ) const;
218 // Position interface
221 * @brief Replaces any glyph positions previously set.
223 * @note If the number of glyphs is zero the position buffer is cleared.
225 * @param[in] glyphPositions An array of visual positions for each glyph.
226 * @param[in] numberOfGlyphs The number of positions.
228 void SetGlyphPositions( const Vector2* glyphPositions,
229 Length numberOfGlyphs );
232 * Retrieves the number of glyph positions set.
234 * @note This may be less than the number of glyphs in the model.
235 * @return The number of glyphs.
237 Length GetNumberOfGlyphPositions() const;
240 * @brief Retrieves the glyph positions.
242 * @pre The size of the @p positions buffer needs to be big enough to copy the @p numberOfGlyphs positions.
243 * @param[out] glyphPositions Pointer to a buffer where the glyph positions are copied.
244 * @param[in] glyphIndex Index to the first glyph position.
245 * @param[in] numberOfGlyphs The number of positions to be copied.
247 void GetGlyphPositions( Vector2* glyphPositions,
248 GlyphIndex glyphIndex,
249 Length numberOfGlyphs ) const;
252 * Retrieve the glyph's position of the given glyph.
254 * @param[in] glyphIndex Index to the glyph.
256 * @return The glyph's position.
258 const Vector2& GetGlyphPosition( GlyphIndex glyphIndex ) const;
261 * Replaces glyph's positions.
263 * If the @p numberOfGlyphsToRemove is zero, this operation is like an insert.
264 * If the @p numberOfGlyphsToInsert is zero, this operation is like a remove.
266 * @param[in] glyphIndex Where to replace the glyph's positions.
267 * @param[in] numberOfGlyphsToRemove The number of glyph's positions to be removed.
268 * @param[in] positions Pointer to a buffer with the new glyph's positions.
269 * @param[in] numberOfGlyphsToInsert The number of new glyph's positions in the buffer.
271 void ReplaceGlyphPositions( GlyphIndex glyphIndex,
272 Length numberOfGlyphsToRemove,
273 const Vector2* const positions,
274 Length numberOfGlyphsToInsert );
281 * Replaces any lines previously set.
283 * Every line is an item run containing the index to the first glyph of the line and the number of glyphs.
285 * @note If the number of lines is zero or the pointer is NULL, the lines buffer is cleared.
287 * @param[in] lines Pointer to a buffer containing all the line runs.
288 * @param[in] numberOfLines The number of lines in the buffer.
290 void SetLines( const LineRun* const lines,
291 Length numberOfLines );
294 * Retrieves the number of lines of the whole text.
296 * @return The number of lines.
298 Length GetNumberOfLines() const;
303 * The size of the @p lines buffer needs to be big enough to copy the @p numberOfLines.
305 * @param[out] lines Pointer to a buffer where the lines are copied.
306 * @param[in] lineIndex Index to the first line.
307 * @param[in] numberOfLines Number of lines to be copied.
309 void GetLines( LineRun* lines,
311 Length numberOfLines ) const;
314 * Retrieves the number of lines and the index to the first line where the given range of glyphs is laid out.
316 * @param[in] glyphIndex Index to the first glyph.
317 * @param[in] numberOfGlyphs The number of glyph.
318 * @param[out] firstLine Index to the line containing the glyph index.
319 * @param[out] numberOfLines The number of lines.
321 void GetNumberOfLines( GlyphIndex glyphIndex,
322 Length numberOfGlyphs,
323 LineIndex& firstLine,
324 Length& numberOfLines ) const;
326 * Retrieves the lines where the given range of glyphs is laid out.
328 * The size of the @p lines buffer needs to be big enough to copy the @p numberOfLines.
330 * @param[out] lines Pointer to a buffer where the lines are copied.
331 * @param[in] glyphIndex Index to the first glyphs of the range.
332 * @param[in] numberOfGlyphs Number of glyphs in the range.
334 void GetLinesOfGlyphRange( LineRun* lines,
335 GlyphIndex glyphIndex,
336 Length numberOfGlyphs ) const;
339 * Replaces lines for the given range of glyphs.
341 * If the @p numberOfGlyphsToRemove is zero, this operation is like an insert.
342 * If the @p numberOfGlyphsToInsert is zero, this operation is like a remove.
344 * @param[in] glyphIndex Index of the first glyph where to replace the line info.
345 * @param[in] numberOfGlyphsToRemove The number of glyphs to be the line info removed.
346 * @param[in] lines Pointer to a buffer with the lines.
347 * @param[in] numberOfGlyphsToInsert The number of characters to be the line info inserted.
349 void ReplaceLines( GlyphIndex glyphIndex,
350 Length numberOfGlyphsToRemove,
351 const LineRun* const lines,
352 Length numberOfGlyphsToInsert );
357 * Sets the natural size.
359 * @param[in] size The text's natural size.
361 void SetNaturalSize( const Vector2& size );
364 * Retrieves the natural size.
366 * @return The text's natural size.
368 const Vector2& GetNaturalSize() const;
371 * Sets the text's actual size after it has been laid out.
373 * @param[in] size The text's size.
375 void SetActualSize( const Vector2& size );
378 * Retrieves the text's actual size after it has been laid out.
380 * @return The text's size.
382 const Vector2& GetActualSize() const;
387 * @brief A reference counted object may only be deleted by calling Unreference().
389 virtual ~VisualModel();
394 * @brief Private constructor.
399 VisualModel( const VisualModel& handle );
402 VisualModel& operator=( const VisualModel& handle );
406 Vector<GlyphInfo> mGlyphs; ///< For each glyph, the font's id, glyph's index within the font and glyph's metrics.
407 Vector<CharacterIndex> mGlyphsToCharacters; ///< For each glyph, the index of the first character.
408 Vector<GlyphIndex> mCharactersToGlyph; ///< For each character, the index of the first glyph.
409 Vector<Length> mCharactersPerGlyph; ///< For each glyph, the number of characters that form the glyph.
410 Vector<Length> mGlyphsPerCharacter; ///< For each character, the number of glyphs that are shaped.
411 Vector<Vector2> mGlyphPositions; ///< For each glyph, the position.
412 Vector<LineRun> mLines; ///< The laid out lines.
416 Size mNaturalSize; ///< Size of the text with no line wrapping.
417 Size mActualSize; ///< Size of the laid-out text considering the layout properties set.
422 } // namespace Toolkit
426 #endif // __DALI_TOOLKIT_TEXT_VISUAL_MODEL_IMPL_H__