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>
27 #include <dali-toolkit/internal/text/text-definitions.h>
38 struct BidirectionalLineInfoRun;
39 struct BidirectionalParagraphInfoRun;
42 typedef IntrusivePtr<LogicalModel> LogicalModelPtr;
46 * @brief A logical text model contains layout independent information.
49 * - A series of UTF-32 characters in logical order
51 class LogicalModel : public RefObject
56 * @brief Create a new instance of a LogicalModel.
58 * @return A pointer to a new LogicalModel.
60 static LogicalModelPtr New();
65 * @brief Replaces any text previously set.
67 * @note If the number of characters is zero the text buffer is cleared.
69 * @param[in] text An array of UTF-32 characters.
70 * @param[in] numberOfCharacters The length of the array.
72 void SetText( const Character* const text,
73 Length numberOfCharacters );
76 * @brief Retrieves the number of characters of the text.
78 * @return The number of characters.
80 Length GetNumberOfCharacters() const;
83 * @brief Retrieves characters from the text in the given buffer.
85 * @pre The size of the @p text buffer needs to be big enough to copy the @p numberOfCharacters.
86 * @param[out] text Pointer to a buffer where the text is copied.
87 * @param[in] characterIndex The index to the first character to copy.
88 * @param[in] numberOfCharacters The number of characters to be copied.
90 void GetText( Character* text,
91 CharacterIndex characterIndex,
92 Length numberOfCharacters ) const;
95 * Retrieves a character.
97 * @param[in] characterIndex Index to a character.
99 * @return A character.
101 Character GetCharacter( CharacterIndex characterIndex ) const;
104 * Replaces characters from the text.
106 * If the @p numberOfCharactersToRemove is zero, this operation is like an insert.
107 * If the @p numberOfCharactersToInsert is zero, this operation is like a remove.
109 * @param[in] characterIndex Where to replace the text.
110 * @param[in] numberOfCharactersToRemove The number of characters to be removed.
111 * @param[in] text Pointer to a buffer with the text encoded in utf32.
112 * @param[in] numberOfCharactersToInsert The number of characters in the buffer.
114 void ReplaceText( CharacterIndex characterIndex,
115 Length numberOfCharactersToRemove,
116 const Character* const text,
117 Length numberOfCharactersToInsert );
119 // Language support interface.
122 * Sets the script runs.
124 * Replaces any scripts previously set.
126 * A run is a group of consecutive characters. A script run contains the script for a run.
128 * @note If the number of runs is zero the script buffer is cleared.
130 * @param[in] scripts Pointer to a buffer with all the script runs.
131 * @param[in] numberOfRuns The number of script runs.
133 void SetScripts( const ScriptRun* const scripts,
134 Length numberOfRuns );
137 * Retrieves the number of script runs for the given range of characters.
139 * A run is a group of consecutive characters. A script run contains the script for a run.
141 * @param[in] characterIndex Index to the first character.
142 * @param[in] numberOfCharacters The number of characters.
144 * @return The number of script runs.
146 Length GetNumberOfScriptRuns( CharacterIndex characterIndex,
147 Length numberOfCharacters ) const;
150 * Retrieves the script runs for the given range of characters.
152 * The @p scriptRuns buffer needs to be big enough to copy the number of script runs.
153 * Call GetNumberOfScriptRuns() to retrieve the number of script runs.
155 * @param[out] scriptRuns Pointer to a buffer where the script runs are copied.
156 * @param[in] characterIndex Index to the first character.
157 * @param[in] numberOfCharacters The number of characters.
159 void GetScriptRuns( ScriptRun* scriptRuns,
160 CharacterIndex characterIndex,
161 Length numberOfCharacters ) const;
164 * Retrieves the script for the given character index.
166 * @param[in] characterIndex Index to the character.
168 * @return The character's script.
170 Script GetScript( CharacterIndex characterIndex ) const;
173 * Replaces script runs for the given range of characters.
175 * If the @p numberOfCharactersToRemove is zero, this operation is like an insert.
176 * If the @p numberOfCharactersToInsert is zero, this operation is like a remove.
178 * @param[in] characterIndex Index of the first character where to replace the scripts.
179 * @param[in] numberOfCharactersToRemove The number of characters to be the script removed.
180 * @param[in] scriptRuns Pointer to a buffer with the script runs.
181 * @param[in] numberOfCharactersToInsert The number of characters to be the script inserted.
183 void ReplaceScripts( CharacterIndex characterIndex,
184 Length numberOfCharactersToRemove,
185 const ScriptRun* const scriptRuns,
186 Length numberOfCharactersToInsert );
189 * Sets the font runs.
191 * Replaces any fonts previously set.
193 * A run is a group of consecutive characters. A font run contains the font id for a run.
195 * @note If the number of runs is zero the font buffer is cleared.
197 * @param[in] fonts Pointer to a buffer with all the font runs.
198 * @param[in] numberOfRuns The number of font runs.
200 void SetFonts( const FontRun* const fonts,
201 Length numberOfRuns );
204 * Retrieves the number of font runs for the given range of characters.
206 * A run is a group of consecutive characters. A font run contains the font id for a run.
208 * @param[in] characterIndex Index to the first character.
209 * @param[in] numberOfCharacters The number of characters.
211 * @return The number of font runs.
213 Length GetNumberOfFontRuns( CharacterIndex characterIndex,
214 Length numberOfCharacters ) const;
217 * Retrieves the font runs for the given range of characters.
219 * The @p fontRuns buffer needs to be big enough to copy the number of font runs.
220 * Call GetNumberOfFontRuns() to retrieve the number of font runs.
222 * @param[out] fontRuns Pointer to a buffer where the font runs are copied.
223 * @param[in] characterIndex Index to the first character.
224 * @param[in] numberOfCharacters The number of characters.
226 void GetFontRuns( FontRun* fontRuns,
227 CharacterIndex characterIndex,
228 Length numberOfCharacters ) const;
231 * Retrieves the font id for the given character index.
233 * @param[in] characterIndex Index to the first character.
235 * @return The font id.
237 FontId GetFont( CharacterIndex characterIndex ) const;
240 * Replaces font runs for the given range of characters.
242 * If the @p numberOfCharactersToRemove is zero, this operation is like an insert.
243 * If the @p numberOfCharactersToInsert is zero, this operation is like a remove.
245 * @param[in] characterIndex Index of the first character where to replace the fonts.
246 * @param[in] numberOfCharactersToRemove The number of characters to be the font removed.
247 * @param[in] fontRuns Pointer to a buffer with the font runs.
248 * @param[in] numberOfCharactersToInsert The number of characters to be the font inserted.
250 void ReplaceFonts( CharacterIndex characterIndex,
251 Length numberOfCharactersToRemove,
252 const FontRun* const fontRuns,
253 Length numberOfCharactersToInsert );
255 // Break info interface.
258 * Sets the line break info.
260 * See GetLineBreakInfo() to get how the line break info is encoded.
262 * Replaces any line break info previously set.
264 * @note If the @length is zero the break info buffer is cleared.
266 * @param[in] lineBreakInfo Pointer to a buffer with the line break info.
267 * @param[in] length The size of the buffer.
269 void SetLineBreakInfo( const LineBreakInfo* const lineBreakInfo,
273 * Retrieves the line break info in the given buffer.
275 * The size of the @p lineBreakInfo buffer needs to be big enough to copy the @p numberOfItems.
277 * Possible values for LineBreakInfo are:
279 * - 0 is a LINE_MUST_BREAK. Text must be broken into a new line.
280 * - 1 is a LINE_ALLOW_BREAK. Is possible to break the text into a new line.
281 * - 2 is a LINE_NO_BREAK. Text can't be broken into a new line.
284 i.e. Hello big\nworld produces:
288 * @param[out] lineBreakInfo Pointer to a buffer where the line break info is copied.
289 * @param[in] characterIndex Index to the first line break info item.
290 * @param[in] numberOfItems The number of items to be copied.
292 void GetLineBreakInfo( LineBreakInfo* lineBreakInfo,
293 CharacterIndex characterIndex,
294 Length numberOfItems ) const;
297 * Retrieves the line break info for the given item index.
299 * @param[in] characterIndex Index to the line break info item.
301 LineBreakInfo GetLineBreakInfo( CharacterIndex characterIndex ) const;
304 * Replaces line break info.
306 * See GetLineBreakInfo() to get how the line break info is encoded.
308 * If the @p numberOfItemsToRemove is zero, this operation is like an insert.
309 * If the @p numberOfItemsToInsert is zero, this operation is like a remove.
311 * @param[in] characterIndex Where to replace the line break info.
312 * @param[in] numberOfItemsToRemove The number of items to be removed.
313 * @param[in] lineBreakInfo Pointer to a buffer with the line break info.
314 * @param[in] numberOfItemsToInsert The number of items in the buffer.
316 void ReplaceLineBreakInfo( CharacterIndex characterIndex,
317 Length numberOfItemsToRemove,
318 const LineBreakInfo* const lineBreakInfo,
319 Length numberOfItemsToInsert );
322 * Sets the word break info.
324 * See GetWordBreakInfo() to get how the word break info is encoded.
326 * Replaces any word break info previously set.
328 * @note If the @length is zero the break info buffer is cleared.
330 * @param[in] wordBreakInfo Pointer to a buffer with the word break info.
331 * @param[in] length The size of the buffer.
333 void SetWordBreakInfo( const WordBreakInfo* const wordBreakInfo,
337 * Retrieves the word break info in the given buffer.
339 * The size of the @p wordBreakInfo buffer needs to be big enough to copy the @p numberOfItems.
341 * The size of the buffer has to be big enough to store the whole word break info per character.
342 * Call GetNumberOfCharacters() to get the number of characters.
344 * Possible values for WordBreakInfo are:
346 * - 0 is a WORD_BREAK. Text can be broken into a new word.
347 * - 1 is a WORD_NO_BREAK. Text can't be broken into a new word.
350 i.e. Hello big\nworld produces:
354 * @param[out] wordBreakInfo Pointer to a buffer where the word break info is copied.
355 * @param[in] characterIndex Index to the first word break info item.
356 * @param[in] numberOfItems The number of items to be copied.
358 void GetWordBreakInfo( WordBreakInfo* wordBreakInfo,
359 CharacterIndex characterIndex,
360 Length numberOfItems ) const;
363 * Retrieves the word break info for the given item index.
365 * @param[in] characterIndex Index to the word break info item.
367 WordBreakInfo GetWordBreakInfo( CharacterIndex characterIndex ) const;
370 * Replaces word break info.
372 * See GetWordBreakInfo() to get how the word break info is encoded.
374 * If the @p numberOfItemsToRemove is zero, this operation is like an insert.
375 * If the @p numberOfItemsToInsert is zero, this operation is like a remove.
377 * @param[in] characterIndex Where to replace the word break info.
378 * @param[in] numberOfItemsToRemove The number of items to be removed.
379 * @param[in] wordBreakInfo Pointer to a buffer with the word break info.
380 * @param[in] numberOfItemsToInsert The number of items in the buffer.
382 void ReplaceWordBreakInfo( CharacterIndex characterIndex,
383 Length numberOfItemsToRemove,
384 const WordBreakInfo* const wordBreakInfo,
385 Length numberOfItemsToInsert );
387 // Bidirectional support interface.
390 * Sets the bidirectional info runs.
392 * Replaces any bidirectional info previously set.
394 * Each bidirectional info run stores bidirectional info for a whole 'paragraph' of text which contains right to left scripts.
396 * In terms of the bidirectional algorithm, a 'paragraph' is understood as a run of characters between Paragraph Separators or appropriate Newline Functions.
397 * A 'paragraph' may also be determined by higher-level protocols like a mark-up tag.
399 * @note If the number of runs is zero the bidirectional info buffer is cleared.
401 * @param[in] bidirectionalInfo Pointer to a buffer with all the bidirectional info runs.
402 * @param[in] numberOfRuns The number of bidirectional info runs.
404 void SetBidirectionalInfo( const BidirectionalParagraphInfoRun* const bidirectionalInfo,
405 Length numberOfRuns );
408 * Retrieves the number of bidirectional info runs for the given range of characters.
410 * It may be zero if there is no right to left scripts.
412 * @param[in] characterIndex Index to the first character.
413 * @param[in] numberOfCharacters The number of characters.
415 * @return The number of bidirectional info runs.
417 Length GetNumberOfBidirectionalInfoRuns( CharacterIndex characterIndex,
418 Length numberOfCharacters ) const;
421 * Retrieves the bidirectional paragraph info runs for the given range of characters.
423 * The @p bidirectionalInfo buffer needs to be big enough to copy the number of bidirectional
424 * paragraph info runs.
425 * Call GetNumberOfBidirectionalInfoRuns() to retrieve the number of bidirectional runs.
427 * @param[out] bidirectionalInfo Pointer to a buffer where the bidirectional info runs are copied.
428 * @param[in] characterIndex Index to the first character.
429 * @param[in] numberOfCharacters The number of characters.
431 void GetBidirectionalInfo( BidirectionalParagraphInfoRun* bidirectionalInfo,
432 CharacterIndex characterIndex,
433 Length numberOfCharacters ) const;
436 * Replaces bidirectional info runs for the given range of characters.
438 * If the @p numberOfCharactersToRemove is zero, this operation is like an insert.
439 * If the @p numberOfCharactersToInsert is zero, this operation is like a remove.
441 * @param[in] characterIndex Index of the first character where to replace the bidirectional info.
442 * @param[in] numberOfCharactersToRemove The number of characters to be the bidirectional info removed.
443 * @param[in] bidirectionalInfo Pointer to a buffer with the bidirectional info runs.
444 * @param[in] numberOfCharactersToInsert The number of characters to be the bidirectional info inserted.
446 void ReplaceBidirectionalInfo( CharacterIndex characterIndex,
447 Length numberOfCharactersToRemove,
448 const BidirectionalParagraphInfoRun* const bidirectionalInfo,
449 Length numberOfCharactersToInsert );
452 * Retrieves the direction of the characters.
454 * It sets @c true for right to left characters and @c false for left to right.
455 * For neutral characters it check's the next and previous character's directions:
456 * - If they are equals set that direction. If they are not, sets the paragraph's direction.
457 * - If there is no next, sets the paragraph's direction.
459 * See SetBidirectionalInfo() to get an explanation of the 'paragraph' meaning in the bidirectional algorithm.
461 * @param[out] directions Whether the characters are right to left or left to right.
462 * @param[in] characterIndex Index to the first character.
463 * @param[in] numberOfCharacters The number of characters.
465 void GetCharacterDirections( CharacterDirection* directions,
466 CharacterIndex characterIndex,
467 Length numberOfCharacters ) const;
470 * Retrieves the direction of a characters.
472 * See GetCharacterDirections().
474 * @param[in] characterIndex Index to a character.
476 * @return The character's direction.
478 CharacterDirection GetCharacterDirection( CharacterIndex characterIndex ) const;
480 // Visual <--> Logical conversion tables.
483 * Sets the visual to logical and the logical to visual map tables.
485 * Replaces any map tables previously set.
487 * @note If the number of runs is zero the bidirectional info buffer is cleared.
489 * @param[in] bidirectionalInfo Pointer to a buffer with all the bidirectional info runs.
490 * @param[in] numberOfRuns The number of bidirectional info runs.
492 void SetVisualToLogicalMap( const BidirectionalLineInfoRun* const bidirectionalInfo,
493 Length numberOfRuns );
496 * Replaces the visual to logical and logical to visual map tables for the given range of characters.
498 * If the @p numberOfCharactersToRemove is zero, this operation is like an insert.
499 * If the @p numberOfCharactersToInsert is zero, this operation is like a remove.
501 * @param[in] characterIndex Index of the first character where to replace the map tables.
502 * @param[in] numberOfCharactersToRemove The number of characters to be removed.
503 * @param[in] bidirectionalInfo Pointer to a buffer with the bidirectional info runs.
504 * @param[in] numberOfCharactersToInsert The number of characters to be inserted.
506 void ReplaceVisualToLogicalMap( CharacterIndex characterIndex,
507 Length numberOfCharactersToRemove,
508 const BidirectionalLineInfoRun* const bidirectionalInfo,
509 Length numberOfCharactersToInsert );
512 * Retrieves the visual character index for the given logical character index.
514 * @param[in] logicalCharacterIndex The logical character index.
516 * @return The visual character index.
518 CharacterIndex GetVisualCharacterIndex( CharacterIndex logicalCharacterIndex ) const;
521 * Retrieves the logical character index for the given visual character index.
523 * @param[in] visualCharacterIndex The visual character index.
525 * @return The logical character index.
527 CharacterIndex GetLogicalCharacterIndex( CharacterIndex visualCharacterIndex ) const;
530 * Retrieves the whole or part of the logical to visual conversion map.
532 * The size of the buffer needs to be big enough to copy the @p numberOfCharacters.
534 * @param[out] logicalToVisualMap Pointer to a buffer where the conversion map is copied.
535 * @param[in] characterIndex Index to the first character.
536 * @param[in] numberOfCharacters The number of characters.
538 void GetLogicalToVisualMap( CharacterIndex* logicalToVisualMap,
539 CharacterIndex characterIndex,
540 Length numberOfCharacters ) const;
543 * Retrieves the whole or part of the visual to logical conversion map.
545 * The size of the buffer needs to be big enough to copy the @p numberOfCharacters.
547 * @param[out] visualToLogicalMap Pointer to a buffer where the conversion map is copied.
548 * @param[in] characterIndex Index to the first character.
549 * @param[in] numberOfCharacters The number of characters.
551 void GetVisualToLogicalMap( CharacterIndex* visualToLogicalMap,
552 CharacterIndex characterIndex,
553 Length numberOfCharacters ) const;
558 * @brief A reference counted object may only be deleted by calling Unreference().
560 virtual ~LogicalModel();
565 * @brief Private constructor.
570 LogicalModel( const LogicalModel& handle );
573 LogicalModel& operator=( const LogicalModel& handle );
583 } // namespace Toolkit
587 #endif // __DALI_TOOLKIT_TEXT_LOGICAL_MODEL_H__