1 #ifndef __DALI_TOOLKIT_TEXT_LOGICAL_MODEL_H__
2 #define __DALI_TOOLKIT_TEXT_LOGICAL_MODEL_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>
25 #include <dali-toolkit/public-api/text/text-definitions.h>
36 struct BidirectionalLineInfoRun;
37 struct BidirectionalParagraphInfoRun;
40 typedef IntrusivePtr<LogicalModel> LogicalModelPtr;
44 * @brief A logical text model contains layout independent information.
47 * - A series of UTF-32 characters in logical order
49 class LogicalModel : public RefObject
54 * @brief Create a new instance of a LogicalModel.
56 * @return A pointer to a new LogicalModel.
58 static LogicalModelPtr New();
63 * @brief Replaces any text previously set.
65 * @param[in] text An array of UTF-32 characters.
66 * @param[in] numberOfCharacters The length of the array.
68 void SetText( const Character* const text,
69 Length numberOfCharacters );
72 * @brief Retrieves the number of characters of the text.
74 * @return The number of characters.
76 Length GetNumberOfCharacters() const;
79 * @brief Retrieves characters from the text in the given buffer.
81 * @pre The size of the @p text buffer needs to be big enough to copy the @p numberOfCharacters.
82 * @param[in] characterIndex The index to the first character to copy.
83 * @param[out] text Pointer to a buffer where the text is copied.
84 * @param[in] numberOfCharacters The number of characters to be copied.
86 void GetText( CharacterIndex characterIndex,
88 Length numberOfCharacters ) const;
91 * Retrieves a character.
93 * @param[in] characterIndex Index to a character.
95 * @return A character.
97 Character GetCharacter( CharacterIndex characterIndex ) const;
99 // Language support interface.
102 * Sets the script runs.
104 * Replaces any scripts previously set.
106 * A run is a group of consecutive characters. A script run contains the script for a run.
108 * @param[in] scripts Pointer to a buffer with all the script runs.
109 * @param[in] numberOfRuns The number of script runs.
111 void SetScripts( const ScriptRun* const scripts,
112 Length numberOfRuns );
115 * Retrieves the number of script runs for the given range of characters.
117 * A run is a group of consecutive characters. A script run contains the script for a run.
119 * @param[in] characterIndex Index to the first character.
120 * @param[in] numberOfCharacters The number of characters.
122 * @return The number of script runs.
124 Length GetNumberOfScriptRuns( CharacterIndex characterIndex,
125 Length numberOfCharacters ) const;
128 * Retrieves the script runs for the given range of characters.
130 * The @p scriptRuns buffer needs to be big enough to copy the number of script runs.
131 * Call GetNumberOfScriptRuns() to retrieve the number of script runs.
133 * @param[out] scriptRuns Pointer to a buffer where the script runs are copied.
134 * @param[in] characterIndex Index to the first character.
135 * @param[in] numberOfCharacters The number of characters.
137 void GetScriptRuns( ScriptRun* scriptRuns,
138 CharacterIndex characterIndex,
139 Length numberOfCharacters ) const;
142 * Retrieves the script for the given character index.
144 * @param[in] characterIndex Index to the character.
146 * @return The character's script.
148 Script GetScript( CharacterIndex characterIndex ) const;
151 * Sets the font runs.
153 * Replaces any fonts previously set.
155 * A run is a group of consecutive characters. A font run contains the font id for a run.
157 * @param[in] fonts Pointer to a buffer with all the font runs.
158 * @param[in] numberOfRuns The number of font runs.
160 void SetFonts( const FontRun* const fonts,
161 Length numberOfRuns );
164 * Retrieves the number of font runs for the given range of characters.
166 * A run is a group of consecutive characters. A font run contains the font id for a run.
168 * @param[in] characterIndex Index to the first character.
169 * @param[in] numberOfCharacters The number of characters.
171 * @return The number of font runs.
173 Length GetNumberOfFontRuns( CharacterIndex characterIndex,
174 Length numberOfCharacters ) const;
177 * Retrieves the font runs for the given range of characters.
179 * The @p fontRuns buffer needs to be big enough to copy the number of font runs.
180 * Call GetNumberOfFontRuns() to retrieve the number of font runs.
182 * @param[out] fontRuns Pointer to a buffer where the font runs are copied.
183 * @param[in] characterIndex Index to the first character.
184 * @param[in] numberOfCharacters The number of characters.
186 void GetFontRuns( FontRun* fontRuns,
187 CharacterIndex characterIndex,
188 Length numberOfCharacters ) const;
191 * Retrieves the font id for the given character index.
193 * @param[in] characterIndex Index to the first character.
195 * @return The font id.
197 FontId GetFont( CharacterIndex characterIndex ) const;
199 // Break info interface.
202 * Sets the line break info.
204 * See GetLineBreakInfo() to get how the line break info is encoded.
206 * Replaces any line break info previously set.
208 * @param[in] lineBreakInfo Pointer to a buffer with the line break info.
209 * @param[in] length The size of the buffer.
211 void SetLineBreakInfo( const LineBreakInfo* const lineBreakInfo,
215 * Retrieves the line break info in the given buffer.
217 * The size of the @p lineBreakInfo buffer needs to be big enough to copy the @p numberOfItems.
219 * Possible values for LineBreakInfo are:
221 * - 0 is a LINE_MUST_BREAK. Text must be broken into a new line.
222 * - 1 is a LINE_ALLOW_BREAK. Is possible to break the text into a new line.
223 * - 2 is a LINE_NO_BREAK. Text can't be broken into a new line.
226 i.e. Hello big\nworld produces:
230 * @param[out] lineBreakInfo Pointer to a buffer where the line break info is copied.
231 * @param[in] characterIndex Index to the first line break info item.
232 * @param[in] numberOfItems The number of items to be copied.
234 void GetLineBreakInfo( LineBreakInfo* lineBreakInfo,
235 CharacterIndex characterIndex,
236 Length numberOfItems ) const;
239 * Retrieves the line break info for the given item index.
241 * @param[in] characterIndex Index to the line break info item.
243 LineBreakInfo GetLineBreakInfo( CharacterIndex characterIndex ) const;
246 * Sets the word break info.
248 * See GetWordBreakInfo() to get how the word break info is encoded.
250 * Replaces any word break info previously set.
252 * @param[in] wordBreakInfo Pointer to a buffer with the word break info.
253 * @param[in] length The size of the buffer.
255 void SetWordBreakInfo( const WordBreakInfo* const wordBreakInfo,
259 * Retrieves the word break info in the given buffer.
261 * The size of the @p wordBreakInfo buffer needs to be big enough to copy the @p numberOfItems.
263 * The size of the buffer has to be big enough to store the whole word break info per character.
264 * Call GetNumberOfCharacters() to get the number of characters.
266 * Possible values for WordBreakInfo are:
268 * - 0 is a WORD_BREAK. Text can be broken into a new word.
269 * - 1 is a WORD_NO_BREAK. Text can't be broken into a new word.
272 i.e. Hello big\nworld produces:
276 * @param[out] wordBreakInfo Pointer to a buffer where the word break info is copied.
277 * @param[in] characterIndex Index to the first word break info item.
278 * @param[in] numberOfItems The number of items to be copied.
280 void GetWordBreakInfo( WordBreakInfo* wordBreakInfo,
281 CharacterIndex characterIndex,
282 Length numberOfItems ) const;
285 * Retrieves the word break info for the given item index.
287 * @param[in] characterIndex Index to the word break info item.
289 WordBreakInfo GetWordBreakInfo( CharacterIndex characterIndex ) const;
291 // Bidirectional support interface.
294 * Sets the bidirectional info runs.
296 * Replaces any bidirectional info previously set.
298 * Each bidirectional info run stores bidirectional info for a whole 'paragraph' of text which contains right to left scripts.
300 * In terms of the bidirectional algorithm, a 'paragraph' is understood as a run of characters between Paragraph Separators or appropriate Newline Functions.
301 * A 'paragraph' may also be determined by higher-level protocols like a mark-up tag.
303 * @param[in] bidirectionalInfo Pointer to a buffer with all the bidirectional info runs.
304 * @param[in] numberOfRuns The number of bidirectional info runs.
306 void SetBidirectionalInfo( const BidirectionalParagraphInfoRun* const bidirectionalInfo,
307 Length numberOfRuns );
310 * Retrieves the number of bidirectional info runs for the given range of characters.
312 * It may be zero if there is no right to left scripts.
314 * @param[in] characterIndex Index to the first character.
315 * @param[in] numberOfCharacters The number of characters.
317 * @return The number of bidirectional info runs.
319 Length GetNumberOfBidirectionalInfoRuns( CharacterIndex characterIndex,
320 Length numberOfCharacters ) const;
323 * Retrieves the direction of the characters.
325 * It sets @c true for right to left characters and @c false for left to right.
326 * For neutral characters it check's the next and previous character's directions:
327 * - If they are equals set that direction. If they are not, sets the paragraph's direction.
328 * - If there is no next, sets the paragraph's direction.
330 * See SetBidirectionalInfo() to get an explanation of the 'paragraph' meaning in the bidirectional algorithm.
332 * @param[out] directions Whether the characters are right to left or left to right.
333 * @param[in] characterIndex Index to the first character.
334 * @param[in] numberOfCharacters The number of characters.
336 void GetCharacterDirections( CharacterDirection* directions,
337 CharacterIndex characterIndex,
338 Length numberOfCharacters ) const;
341 * Retrieves the direction of a characters.
343 * See GetCharacterDirections().
345 * @param[in] characterIndex Index to a character.
347 * @return The character's direction.
349 CharacterDirection GetCharacterDirection( CharacterIndex characterIndex ) const;
351 // Visual <--> Logical conversion tables.
354 * Sets the visual to logical and the logical to visual map tables.
356 * Replaces any map tables previously set.
358 * @param[in] bidirectionalInfo Pointer to a buffer with all the bidirectional info runs.
359 * @param[in] numberOfRuns The number of bidirectional info runs.
361 void SetVisualToLogicalMap( const BidirectionalLineInfoRun* const bidirectionalInfo,
362 Length numberOfRuns );
365 * Retrieves the visual character index for the given logical character index.
367 * @param[in] logicalCharacterIndex The logical character index.
369 * @return The visual character index.
371 CharacterIndex GetVisualCharacterIndex( CharacterIndex logicalCharacterIndex ) const;
374 * Retrieves the logical character index for the given visual character index.
376 * @param[in] visualCharacterIndex The visual character index.
378 * @return The logical character index.
380 CharacterIndex GetLogicalCharacterIndex( CharacterIndex visualCharacterIndex ) const;
383 * Retrieves the whole or part of the logical to visual conversion map.
385 * The size of the buffer needs to be big enough to copy the @p numberOfCharacters.
387 * @param[out] logicalToVisualMap Pointer to a buffer where the conversion map is copied.
388 * @param[in] characterIndex Index to the first character.
389 * @param[in] numberOfCharacters The number of characters.
391 void GetLogicalToVisualMap( CharacterIndex* logicalToVisualMap,
392 CharacterIndex characterIndex,
393 Length numberOfCharacters ) const;
396 * Retrieves the whole or part of the visual to logical conversion map.
398 * The size of the buffer needs to be big enough to copy the @p numberOfCharacters.
400 * @param[out] visualToLogicalMap Pointer to a buffer where the conversion map is copied.
401 * @param[in] characterIndex Index to the first character.
402 * @param[in] numberOfCharacters The number of characters.
404 void GetVisualToLogicalMap( CharacterIndex* visualToLogicalMap,
405 CharacterIndex characterIndex,
406 Length numberOfCharacters ) const;
411 * @brief A reference counted object may only be deleted by calling Unreference().
413 virtual ~LogicalModel();
418 * @brief Private constructor.
423 LogicalModel( const LogicalModel& handle );
426 LogicalModel& operator=( const LogicalModel& handle );
436 } // namespace Toolkit
440 #endif // __DALI_TOOLKIT_TEXT_LOGICAL_MODEL_H__