1 #ifndef __DALI_TOOLKIT_TEXT_LOGICAL_MODEL_IMPL_H__
2 #define __DALI_TOOLKIT_TEXT_LOGICAL_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/bidirectional-line-info-run.h>
28 #include <dali-toolkit/internal/text/bidirectional-paragraph-info-run.h>
29 #include <dali-toolkit/internal/text/font-run.h>
30 #include <dali-toolkit/internal/text/script-run.h>
41 struct BidirectionalLineInfoRun;
42 struct BidirectionalParagraphInfoRun;
45 typedef IntrusivePtr<LogicalModel> LogicalModelPtr;
49 * @brief A logical text model contains layout independent information.
52 * - A series of UTF-32 characters in logical order
54 class LogicalModel : public RefObject
59 * @brief Create a new instance of a LogicalModel.
61 * @return A pointer to a new LogicalModel.
63 static LogicalModelPtr New();
68 * @brief Replaces any text previously set.
70 * @note If the number of characters is zero the text buffer is cleared.
72 * @param[in] text An array of UTF-32 characters.
73 * @param[in] numberOfCharacters The length of the array.
75 void SetText( const Character* const text,
76 Length numberOfCharacters );
79 * @brief Retrieves the number of characters of the text.
81 * @return The number of characters.
83 Length GetNumberOfCharacters() const;
86 * @brief Retrieves characters from the text in the given buffer.
88 * @pre The size of the @p text buffer needs to be big enough to copy the @p numberOfCharacters.
89 * @param[out] text Pointer to a buffer where the text is copied.
90 * @param[in] characterIndex The index to the first character to copy.
91 * @param[in] numberOfCharacters The number of characters to be copied.
93 void GetText( Character* text,
94 CharacterIndex characterIndex,
95 Length numberOfCharacters ) const;
98 * @brief Retrieves a character.
100 * @param[in] characterIndex Index to a character.
102 * @return A character.
104 Character GetCharacter( CharacterIndex characterIndex ) const;
107 * @brief Replaces characters from the text.
109 * If the @p numberOfCharactersToRemove is zero, this operation is like an insert.
110 * If the @p numberOfCharactersToInsert is zero, this operation is like a remove.
112 * @param[in] characterIndex Where to replace the text.
113 * @param[in] numberOfCharactersToRemove The number of characters to be removed.
114 * @param[in] text Pointer to a buffer with the text encoded in utf32.
115 * @param[in] numberOfCharactersToInsert The number of characters in the buffer.
117 void ReplaceText( CharacterIndex characterIndex,
118 Length numberOfCharactersToRemove,
119 const Character* const text,
120 Length numberOfCharactersToInsert );
122 // Language support interface.
125 * @brief Sets the script runs.
127 * Replaces any scripts previously set.
129 * A run is a group of consecutive characters. A script run contains the script for a run.
131 * @note If the number of runs is zero the script buffer is cleared.
133 * @param[in] scripts Pointer to a buffer with all the script runs.
134 * @param[in] numberOfRuns The number of script runs.
136 void SetScripts( const ScriptRun* const scripts,
137 Length numberOfRuns );
140 * @brief Retrieves the number of script runs and the index to the first one for the given range of characters.
142 * A run is a group of consecutive characters. A script run contains the script for a run.
144 * @param[in] characterIndex Index to the first character.
145 * @param[in] numberOfCharacters The number of characters.
146 * @param[out] firstScriptRun Index to the script run containing the character index.
147 * @param[out] numberOfScriptRuns The number of script runs.
149 void GetNumberOfScriptRuns( CharacterIndex characterIndex,
150 Length numberOfCharacters,
151 ScriptRunIndex& firstScriptRun,
152 Length& numberOfScriptRuns ) const;
155 * @brief Retrieves the script runs for the given range of characters.
157 * The @p scriptRuns buffer needs to be big enough to copy the number of script runs.
158 * Call GetNumberOfScriptRuns() to retrieve the number of script runs.
160 * @param[out] scriptRuns Pointer to a buffer where the script runs are copied.
161 * @param[in] characterIndex Index to the first character.
162 * @param[in] numberOfCharacters The number of characters.
164 void GetScriptRuns( ScriptRun* scriptRuns,
165 CharacterIndex characterIndex,
166 Length numberOfCharacters ) const;
169 * @brief Retrieves the script for the given character index.
171 * @param[in] characterIndex Index to the character.
173 * @return The character's script.
175 Script GetScript( CharacterIndex characterIndex ) const;
178 * @brief Replaces script runs for the given range of characters.
180 * If the @p numberOfCharactersToRemove is zero, this operation is like an insert.
181 * If the @p numberOfCharactersToInsert is zero, this operation is like a remove.
183 * @param[in] characterIndex Index of the first character where to replace the scripts.
184 * @param[in] numberOfCharactersToRemove The number of characters to be the script removed.
185 * @param[in] scriptRuns Pointer to a buffer with the script runs.
186 * @param[in] numberOfCharactersToInsert The number of characters to be the script inserted.
188 void ReplaceScripts( CharacterIndex characterIndex,
189 Length numberOfCharactersToRemove,
190 const ScriptRun* const scriptRuns,
191 Length numberOfCharactersToInsert );
194 * @brief Sets the font runs.
196 * Replaces any fonts previously set.
198 * A run is a group of consecutive characters. A font run contains the font id for a run.
200 * @note If the number of runs is zero the font buffer is cleared.
202 * @param[in] fonts Pointer to a buffer with all the font runs.
203 * @param[in] numberOfRuns The number of font runs.
205 void SetFonts( const FontRun* const fonts,
206 Length numberOfRuns );
209 * @brief Retrieves the number of font runs and the index of the first one for the given range of characters.
211 * A run is a group of consecutive characters. A font run contains the font id for a run.
213 * @param[in] characterIndex Index to the first character.
214 * @param[in] numberOfCharacters The number of characters.
215 * @param[out] firstFontRun Index to the font run containing the character index.
216 * @param[out] numberOfFontRuns The number of font runs.
218 void GetNumberOfFontRuns( CharacterIndex characterIndex,
219 Length numberOfCharacters,
220 FontRunIndex& firstFontRun,
221 Length& numberOfFontRuns ) const;
224 * @brief Retrieves the font runs for the given range of characters.
226 * The @p fontRuns buffer needs to be big enough to copy the number of font runs.
227 * Call GetNumberOfFontRuns() to retrieve the number of font runs.
229 * @param[out] fontRuns Pointer to a buffer where the font runs are copied.
230 * @param[in] characterIndex Index to the first character.
231 * @param[in] numberOfCharacters The number of characters.
233 void GetFontRuns( FontRun* fontRuns,
234 CharacterIndex characterIndex,
235 Length numberOfCharacters ) const;
238 * @brief Retrieves the font id for the given character index.
240 * @param[in] characterIndex Index to the first character.
242 * @return The font id.
244 FontId GetFont( CharacterIndex characterIndex ) const;
247 * @brief Replaces font runs for the given range of characters.
249 * If the @p numberOfCharactersToRemove is zero, this operation is like an insert.
250 * If the @p numberOfCharactersToInsert is zero, this operation is like a remove.
252 * @param[in] characterIndex Index of the first character where to replace the fonts.
253 * @param[in] numberOfCharactersToRemove The number of characters to be the font removed.
254 * @param[in] fontRuns Pointer to a buffer with the font runs.
255 * @param[in] numberOfCharactersToInsert The number of characters to be the font inserted.
257 void ReplaceFonts( CharacterIndex characterIndex,
258 Length numberOfCharactersToRemove,
259 const FontRun* const fontRuns,
260 Length numberOfCharactersToInsert );
262 // Break info interface.
265 * @brief Sets the line break info.
267 * See GetLineBreakInfo() to get how the line break info is encoded.
269 * Replaces any line break info previously set.
271 * @note If the @length is zero the break info buffer is cleared.
273 * @param[in] lineBreakInfo Pointer to a buffer with the line break info.
274 * @param[in] length The size of the buffer.
276 void SetLineBreakInfo( const LineBreakInfo* const lineBreakInfo,
280 * @brief Retrieves the line break info in the given buffer.
282 * The size of the @p lineBreakInfo buffer needs to be big enough to copy the @p numberOfItems.
284 * Possible values for LineBreakInfo are:
286 * - 0 is a LINE_MUST_BREAK. Text must be broken into a new line.
287 * - 1 is a LINE_ALLOW_BREAK. Is possible to break the text into a new line.
288 * - 2 is a LINE_NO_BREAK. Text can't be broken into a new line.
291 i.e. Hello big\nworld produces:
295 * @param[out] lineBreakInfo Pointer to a buffer where the line break info is copied.
296 * @param[in] characterIndex Index to the first line break info item.
297 * @param[in] numberOfItems The number of items to be copied.
299 void GetLineBreakInfo( LineBreakInfo* lineBreakInfo,
300 CharacterIndex characterIndex,
301 Length numberOfItems ) const;
304 * @brief Retrieves the line break info for the given item index.
306 * @param[in] characterIndex Index to the line break info item.
308 LineBreakInfo GetLineBreakInfo( CharacterIndex characterIndex ) const;
311 * @brief Replaces line break info.
313 * See GetLineBreakInfo() to get how the line break info is encoded.
315 * If the @p numberOfItemsToRemove is zero, this operation is like an insert.
316 * If the @p numberOfItemsToInsert is zero, this operation is like a remove.
318 * @param[in] characterIndex Where to replace the line break info.
319 * @param[in] numberOfItemsToRemove The number of items to be removed.
320 * @param[in] lineBreakInfo Pointer to a buffer with the line break info.
321 * @param[in] numberOfItemsToInsert The number of items in the buffer.
323 void ReplaceLineBreakInfo( CharacterIndex characterIndex,
324 Length numberOfItemsToRemove,
325 const LineBreakInfo* const lineBreakInfo,
326 Length numberOfItemsToInsert );
329 * @brief Sets the word break info.
331 * See GetWordBreakInfo() to get how the word break info is encoded.
333 * Replaces any word break info previously set.
335 * @note If the @length is zero the break info buffer is cleared.
337 * @param[in] wordBreakInfo Pointer to a buffer with the word break info.
338 * @param[in] length The size of the buffer.
340 void SetWordBreakInfo( const WordBreakInfo* const wordBreakInfo,
344 * @brief Retrieves the word break info in the given buffer.
346 * The size of the @p wordBreakInfo buffer needs to be big enough to copy the @p numberOfItems.
348 * The size of the buffer has to be big enough to store the whole word break info per character.
349 * Call GetNumberOfCharacters() to get the number of characters.
351 * Possible values for WordBreakInfo are:
353 * - 0 is a WORD_BREAK. Text can be broken into a new word.
354 * - 1 is a WORD_NO_BREAK. Text can't be broken into a new word.
357 i.e. Hello big\nworld produces:
361 * @param[out] wordBreakInfo Pointer to a buffer where the word break info is copied.
362 * @param[in] characterIndex Index to the first word break info item.
363 * @param[in] numberOfItems The number of items to be copied.
365 void GetWordBreakInfo( WordBreakInfo* wordBreakInfo,
366 CharacterIndex characterIndex,
367 Length numberOfItems ) const;
370 * @brief Retrieves the word break info for the given item index.
372 * @param[in] characterIndex Index to the word break info item.
374 WordBreakInfo GetWordBreakInfo( CharacterIndex characterIndex ) const;
377 * @brief Replaces word break info.
379 * See GetWordBreakInfo() to get how the word break info is encoded.
381 * If the @p numberOfItemsToRemove is zero, this operation is like an insert.
382 * If the @p numberOfItemsToInsert is zero, this operation is like a remove.
384 * @param[in] characterIndex Where to replace the word break info.
385 * @param[in] numberOfItemsToRemove The number of items to be removed.
386 * @param[in] wordBreakInfo Pointer to a buffer with the word break info.
387 * @param[in] numberOfItemsToInsert The number of items in the buffer.
389 void ReplaceWordBreakInfo( CharacterIndex characterIndex,
390 Length numberOfItemsToRemove,
391 const WordBreakInfo* const wordBreakInfo,
392 Length numberOfItemsToInsert );
394 // Bidirectional support interface.
397 * @brief Sets the bidirectional info runs.
399 * Replaces any bidirectional info previously set.
401 * Each bidirectional info run stores bidirectional info for a whole 'paragraph' of text which contains right to left scripts.
403 * In terms of the bidirectional algorithm, a 'paragraph' is understood as a run of characters between Paragraph Separators or appropriate Newline Functions.
404 * A 'paragraph' may also be determined by higher-level protocols like a mark-up tag.
406 * @note If the number of runs is zero the bidirectional info buffer is cleared.
408 * @param[in] bidirectionalInfo Pointer to a buffer with all the bidirectional info runs.
409 * @param[in] numberOfRuns The number of bidirectional info runs.
411 void SetBidirectionalInfo( const BidirectionalParagraphInfoRun* const bidirectionalInfo,
412 Length numberOfRuns );
415 * @brief Retrieves the number of bidirectional info runs and the index to the first one for the given range of characters.
417 * It may be zero if there is no right to left scripts.
419 * @param[in] characterIndex Index to the first character.
420 * @param[in] numberOfCharacters The number of characters.
422 * @return The number of bidirectional info runs.
424 void GetNumberOfBidirectionalInfoRuns( CharacterIndex characterIndex,
425 Length numberOfCharacters,
426 BidirectionalRunIndex& firstBidirectionalRun,
427 Length& numberOfFontRuns ) const;
430 * @brief Retrieves the bidirectional paragraph info runs for the given range of characters.
432 * The @p bidirectionalInfo buffer needs to be big enough to copy the number of bidirectional
433 * paragraph info runs.
434 * Call GetNumberOfBidirectionalInfoRuns() to retrieve the number of bidirectional runs.
436 * @param[out] bidirectionalInfo Pointer to a buffer where the bidirectional info runs are copied.
437 * @param[in] characterIndex Index to the first character.
438 * @param[in] numberOfCharacters The number of characters.
440 void GetBidirectionalInfo( BidirectionalParagraphInfoRun* bidirectionalInfo,
441 CharacterIndex characterIndex,
442 Length numberOfCharacters ) const;
445 * @brief Replaces bidirectional info runs for the given range of characters.
447 * If the @p numberOfCharactersToRemove is zero, this operation is like an insert.
448 * If the @p numberOfCharactersToInsert is zero, this operation is like a remove.
450 * @param[in] characterIndex Index of the first character where to replace the bidirectional info.
451 * @param[in] numberOfCharactersToRemove The number of characters to be the bidirectional info removed.
452 * @param[in] bidirectionalInfo Pointer to a buffer with the bidirectional info runs.
453 * @param[in] numberOfCharactersToInsert The number of characters to be the bidirectional info inserted.
455 void ReplaceBidirectionalInfo( CharacterIndex characterIndex,
456 Length numberOfCharactersToRemove,
457 const BidirectionalParagraphInfoRun* const bidirectionalInfo,
458 Length numberOfCharactersToInsert );
461 * @brief Replaces the direction of the characters.
463 * @note If the number of characters is zero the directions buffer is cleared.
465 * @param[in] directions The directions of the characters.
466 * @param[in] numberOfCharacters The number of characters.
468 void SetCharacterDirections( const CharacterDirection* const directions,
469 Length numberOfCharacters );
472 * @brief Retrieves the direction of the characters.
474 * It sets @e true for right to left characters and @e false for left to right.
475 * For neutral characters it check's the next and previous character's directions:
476 * - If they are equals set that direction. If they are not, sets the paragraph's direction.
477 * - If there is no next, sets the paragraph's direction.
479 * See SetBidirectionalInfo() to get an explanation of the 'paragraph' meaning in the bidirectional algorithm.
481 * @pre the @p directions vector should be initialized to @e false (left to right) as this method is not going
482 * to update it if there is no right to left characters.
484 * @param[out] directions Whether the characters are right to left or left to right.
485 * @param[in] characterIndex Index to the first character.
486 * @param[in] numberOfCharacters The number of characters.
488 void GetCharacterDirections( CharacterDirection* directions,
489 CharacterIndex characterIndex,
490 Length numberOfCharacters ) const;
493 * @brief Retrieves the direction of a characters.
495 * See GetCharacterDirections().
497 * @param[in] characterIndex Index to a character.
499 * @return The character's direction.
501 CharacterDirection GetCharacterDirection( CharacterIndex characterIndex ) const;
503 // Visual <--> Logical conversion tables.
506 * @brief Sets the visual to logical and the logical to visual map tables.
508 * Replaces any map tables previously set.
510 * @note If the number of runs is zero the bidirectional info buffer is cleared.
512 * @param[in] bidirectionalInfo Pointer to a buffer with all the bidirectional info runs.
513 * @param[in] numberOfRuns The number of bidirectional info runs.
515 void SetVisualToLogicalMap( const BidirectionalLineInfoRun* const bidirectionalInfo,
516 Length numberOfRuns );
519 * @brief Replaces the visual to logical and logical to visual map tables for the given range of characters.
521 * If the @p numberOfCharactersToRemove is zero, this operation is like an insert.
522 * If the @p numberOfCharactersToInsert is zero, this operation is like a remove.
524 * @param[in] characterIndex Index of the first character where to replace the map tables.
525 * @param[in] numberOfCharactersToRemove The number of characters to be removed.
526 * @param[in] bidirectionalInfo Pointer to a buffer with the bidirectional info runs.
527 * @param[in] numberOfCharactersToInsert The number of characters to be inserted.
529 void ReplaceVisualToLogicalMap( CharacterIndex characterIndex,
530 Length numberOfCharactersToRemove,
531 const BidirectionalLineInfoRun* const bidirectionalInfo,
532 Length numberOfCharactersToInsert );
535 * @brief Retrieves the visual character index for the given logical character index.
537 * @param[in] logicalCharacterIndex The logical character index.
539 * @return The visual character index.
541 CharacterIndex GetVisualCharacterIndex( CharacterIndex logicalCharacterIndex ) const;
544 * @brief Retrieves the logical character index for the given visual character index.
546 * @param[in] visualCharacterIndex The visual character index.
548 * @return The logical character index.
550 CharacterIndex GetLogicalCharacterIndex( CharacterIndex visualCharacterIndex ) const;
553 * @brief Retrieves the whole or part of the logical to visual conversion map.
555 * The size of the buffer needs to be big enough to copy the @p numberOfCharacters.
557 * @param[out] logicalToVisualMap Pointer to a buffer where the conversion map is copied.
558 * @param[in] characterIndex Index to the first character.
559 * @param[in] numberOfCharacters The number of characters.
561 void GetLogicalToVisualMap( CharacterIndex* logicalToVisualMap,
562 CharacterIndex characterIndex,
563 Length numberOfCharacters ) const;
566 * @brief Retrieves the whole or part of the visual to logical conversion map.
568 * The size of the buffer needs to be big enough to copy the @p numberOfCharacters.
570 * @param[out] visualToLogicalMap Pointer to a buffer where the conversion map is copied.
571 * @param[in] characterIndex Index to the first character.
572 * @param[in] numberOfCharacters The number of characters.
574 void GetVisualToLogicalMap( CharacterIndex* visualToLogicalMap,
575 CharacterIndex characterIndex,
576 Length numberOfCharacters ) const;
581 * @brief A reference counted object may only be deleted by calling Unreference().
583 virtual ~LogicalModel();
588 * @brief Private constructor.
593 LogicalModel( const LogicalModel& handle );
596 LogicalModel& operator=( const LogicalModel& handle );
600 Vector<Character> mText;
601 Vector<ScriptRun> mScriptRuns;
602 Vector<FontRun> mFontRuns;
603 Vector<LineBreakInfo> mLineBreakInfo;
604 Vector<WordBreakInfo> mWordBreakInfo;
605 Vector<BidirectionalParagraphInfoRun> mBidirectionalParagraphInfo;
606 Vector<CharacterDirection> mCharacterDirections; ///< For each character, whether is right to left. ( @e flase is left to right, @e true right to left ).
607 Vector<BidirectionalLineInfoRun> mBidirectionalLineInfo;
608 Vector<CharacterIndex> mLogicalToVisualMap; ///< Bidirectional logical to visual conversion table.
609 Vector<CharacterIndex> mVisualToLogicalMap; ///< Bidirectional visual to logical conversion table.
610 Vector<CharacterIndex> mVisualToLogicalCursorMap; ///< Bidirectional visual to logical cursor conversion table.
615 } // namespace Toolkit
619 #endif // __DALI_TOOLKIT_TEXT_LOGICAL_MODEL_IMPL_H__