Changes for std::vector removal from api
[platform/core/uifw/dali-toolkit.git] / dali-toolkit / internal / text / logical-model-impl.h
1 #ifndef __DALI_TOOLKIT_TEXT_LOGICAL_MODEL_IMPL_H__
2 #define __DALI_TOOLKIT_TEXT_LOGICAL_MODEL_IMPL_H__
3
4 /*
5  * Copyright (c) 2015 Samsung Electronics Co., Ltd.
6  *
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
10  *
11  * http://www.apache.org/licenses/LICENSE-2.0
12  *
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.
18  *
19  */
20
21 // EXTERNAL INCLUDES
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
26 // INTERNAL INCLUDES
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>
31
32 namespace Dali
33 {
34
35 namespace Toolkit
36 {
37
38 namespace Text
39 {
40
41 struct BidirectionalLineInfoRun;
42 struct BidirectionalParagraphInfoRun;
43 struct FontRun;
44 class LogicalModel;
45 typedef IntrusivePtr<LogicalModel> LogicalModelPtr;
46 struct ScriptRun;
47
48 /**
49  * @brief A logical text model contains layout independent information.
50  *
51  * This includes:
52  * - A series of UTF-32 characters in logical order
53  */
54 class LogicalModel : public RefObject
55 {
56 public:
57
58   /**
59    * @brief Create a new instance of a LogicalModel.
60    *
61    * @return A pointer to a new LogicalModel.
62    */
63   static LogicalModelPtr New();
64
65   // Text interface.
66
67   /**
68    * @brief Replaces any text previously set.
69    *
70    * @note If the number of characters is zero the text buffer is cleared.
71    *
72    * @param[in] text An array of UTF-32 characters.
73    * @param[in] numberOfCharacters The length of the array.
74    */
75   void SetText( const Character* const text,
76                 Length numberOfCharacters );
77
78   /**
79    * @brief Retrieves the number of characters of the text.
80    *
81    * @return The number of characters.
82    */
83   Length GetNumberOfCharacters() const;
84
85   /**
86    * @brief Retrieves characters from the text in the given buffer.
87    *
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.
92    */
93   void GetText( Character* text,
94                 CharacterIndex characterIndex,
95                 Length numberOfCharacters ) const;
96
97   /**
98    * @brief Retrieves a character.
99    *
100    * @param[in] characterIndex Index to a character.
101    *
102    * @return A character.
103    */
104   Character GetCharacter( CharacterIndex characterIndex ) const;
105
106   /**
107    * @brief Replaces characters from the text.
108    *
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.
111    *
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.
116    */
117   void ReplaceText( CharacterIndex characterIndex,
118                     Length numberOfCharactersToRemove,
119                     const Character* const text,
120                     Length numberOfCharactersToInsert );
121
122   // Language support interface.
123
124   /**
125    * @brief Sets the script runs.
126    *
127    * Replaces any scripts previously set.
128    *
129    * A run is a group of consecutive characters. A script run contains the script for a run.
130    *
131    * @note If the number of runs is zero the script buffer is cleared.
132    *
133    * @param[in] scripts Pointer to a buffer with all the script runs.
134    * @param[in] numberOfRuns The number of script runs.
135    */
136   void SetScripts( const ScriptRun* const scripts,
137                    Length numberOfRuns );
138
139   /**
140    * @brief Retrieves the number of script runs and the index to the first one for the given range of characters.
141    *
142    * A run is a group of consecutive characters. A script run contains the script for a run.
143    *
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.
148    */
149   void GetNumberOfScriptRuns( CharacterIndex characterIndex,
150                               Length numberOfCharacters,
151                               ScriptRunIndex& firstScriptRun,
152                               Length& numberOfScriptRuns ) const;
153
154   /**
155    * @brief Retrieves the script runs for the given range of characters.
156    *
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.
159    *
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.
163    */
164   void GetScriptRuns( ScriptRun* scriptRuns,
165                       CharacterIndex characterIndex,
166                       Length numberOfCharacters ) const;
167
168   /**
169    * @brief Retrieves the script for the given character index.
170    *
171    * @param[in] characterIndex Index to the character.
172    *
173    * @return The character's script.
174    */
175   Script GetScript( CharacterIndex characterIndex ) const;
176
177   /**
178    * @brief Replaces script runs for the given range of characters.
179    *
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.
182    *
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.
187    */
188   void ReplaceScripts( CharacterIndex characterIndex,
189                        Length numberOfCharactersToRemove,
190                        const ScriptRun* const scriptRuns,
191                        Length numberOfCharactersToInsert );
192
193   /**
194    * @brief Sets the font runs.
195    *
196    * Replaces any fonts previously set.
197    *
198    * A run is a group of consecutive characters. A font run contains the font id for a run.
199    *
200    * @note If the number of runs is zero the font buffer is cleared.
201    *
202    * @param[in] fonts Pointer to a buffer with all the font runs.
203    * @param[in] numberOfRuns The number of font runs.
204    */
205   void SetFonts( const FontRun* const fonts,
206                  Length numberOfRuns );
207
208   /**
209    * @brief Retrieves the number of font runs and the index of the first one for the given range of characters.
210    *
211    * A run is a group of consecutive characters. A font run contains the font id for a run.
212    *
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.
217    */
218   void GetNumberOfFontRuns( CharacterIndex characterIndex,
219                             Length numberOfCharacters,
220                             FontRunIndex& firstFontRun,
221                             Length& numberOfFontRuns ) const;
222
223   /**
224    * @brief Retrieves the font runs for the given range of characters.
225    *
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.
228    *
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.
232    */
233   void GetFontRuns( FontRun* fontRuns,
234                     CharacterIndex characterIndex,
235                     Length numberOfCharacters ) const;
236
237   /**
238    * @brief Retrieves the font id for the given character index.
239    *
240    * @param[in] characterIndex Index to the first character.
241    *
242    * @return The font id.
243    */
244   FontId GetFont( CharacterIndex characterIndex ) const;
245
246   /**
247    * @brief Replaces font runs for the given range of characters.
248    *
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.
251    *
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.
256    */
257   void ReplaceFonts( CharacterIndex characterIndex,
258                      Length numberOfCharactersToRemove,
259                      const FontRun* const fontRuns,
260                      Length numberOfCharactersToInsert );
261
262   // Break info interface.
263
264   /**
265    * @brief Sets the line break info.
266    *
267    * See GetLineBreakInfo() to get how the line break info is encoded.
268    *
269    * Replaces any line break info previously set.
270    *
271    * @note If the @length is zero the break info buffer is cleared.
272    *
273    * @param[in] lineBreakInfo Pointer to a buffer with the line break info.
274    * @param[in] length The size of the buffer.
275    */
276   void SetLineBreakInfo( const LineBreakInfo* const lineBreakInfo,
277                          Length length );
278
279   /**
280    * @brief Retrieves the line break info in the given buffer.
281    *
282    * The size of the @p lineBreakInfo buffer needs to be big enough to copy the @p numberOfItems.
283    *
284    * Possible values for LineBreakInfo are:
285    *
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.
289    *
290      @verbatim
291      i.e. Hello big\nworld produces:
292           2222212220 22220
293      @endverbatim
294    *
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.
298    */
299   void GetLineBreakInfo( LineBreakInfo* lineBreakInfo,
300                          CharacterIndex characterIndex,
301                          Length numberOfItems ) const;
302
303   /**
304    * @brief Retrieves the line break info for the given item index.
305    *
306    * @param[in] characterIndex Index to the line break info item.
307    */
308   LineBreakInfo GetLineBreakInfo( CharacterIndex characterIndex ) const;
309
310   /**
311    * @brief Replaces line break info.
312    *
313    * See GetLineBreakInfo() to get how the line break info is encoded.
314    *
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.
317    *
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.
322    */
323   void ReplaceLineBreakInfo( CharacterIndex characterIndex,
324                              Length numberOfItemsToRemove,
325                              const LineBreakInfo* const lineBreakInfo,
326                              Length numberOfItemsToInsert );
327
328   /**
329    * @brief Sets the word break info.
330    *
331    * See GetWordBreakInfo() to get how the word break info is encoded.
332    *
333    * Replaces any word break info previously set.
334    *
335    * @note If the @length is zero the break info buffer is cleared.
336    *
337    * @param[in] wordBreakInfo Pointer to a buffer with the word break info.
338    * @param[in] length The size of the buffer.
339    */
340   void SetWordBreakInfo( const WordBreakInfo* const wordBreakInfo,
341                          Length length );
342
343   /**
344    * @brief Retrieves the word break info in the given buffer.
345    *
346    * The size of the @p wordBreakInfo buffer needs to be big enough to copy the @p numberOfItems.
347    *
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.
350    *
351    * Possible values for WordBreakInfo are:
352    *
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.
355    *
356      @verbatim
357      i.e. Hello big\nworld produces:
358           1111001100 11110
359      @endverbatim
360    *
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.
364    */
365   void GetWordBreakInfo( WordBreakInfo* wordBreakInfo,
366                          CharacterIndex characterIndex,
367                          Length numberOfItems ) const;
368
369   /**
370    * @brief Retrieves the word break info for the given item index.
371    *
372    * @param[in] characterIndex Index to the word break info item.
373    */
374   WordBreakInfo GetWordBreakInfo( CharacterIndex characterIndex ) const;
375
376   /**
377    * @brief Replaces word break info.
378    *
379    * See GetWordBreakInfo() to get how the word break info is encoded.
380    *
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.
383    *
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.
388    */
389   void ReplaceWordBreakInfo( CharacterIndex characterIndex,
390                              Length numberOfItemsToRemove,
391                              const WordBreakInfo* const wordBreakInfo,
392                              Length numberOfItemsToInsert );
393
394   // Bidirectional support interface.
395
396   /**
397    * @brief Sets the bidirectional info runs.
398    *
399    * Replaces any bidirectional info previously set.
400    *
401    * Each bidirectional info run stores bidirectional info for a whole 'paragraph' of text which contains right to left scripts.
402
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.
405    *
406    * @note If the number of runs is zero the bidirectional info buffer is cleared.
407    *
408    * @param[in] bidirectionalInfo Pointer to a buffer with all the bidirectional info runs.
409    * @param[in] numberOfRuns The number of bidirectional info runs.
410    */
411   void SetBidirectionalInfo( const BidirectionalParagraphInfoRun* const bidirectionalInfo,
412                              Length numberOfRuns );
413
414   /**
415    * @brief Retrieves the number of bidirectional info runs and the index to the first one for the given range of characters.
416    *
417    * It may be zero if there is no right to left scripts.
418    *
419    * @param[in] characterIndex Index to the first character.
420    * @param[in] numberOfCharacters The number of characters.
421    *
422    * @return The number of bidirectional info runs.
423    */
424   void GetNumberOfBidirectionalInfoRuns( CharacterIndex characterIndex,
425                                          Length numberOfCharacters,
426                                          BidirectionalRunIndex& firstBidirectionalRun,
427                                          Length& numberOfFontRuns ) const;
428
429   /**
430    * @brief Retrieves the bidirectional paragraph info runs for the given range of characters.
431    *
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.
435    *
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.
439    */
440   void GetBidirectionalInfo( BidirectionalParagraphInfoRun* bidirectionalInfo,
441                              CharacterIndex characterIndex,
442                              Length numberOfCharacters ) const;
443
444   /**
445    * @brief Replaces bidirectional info runs for the given range of characters.
446    *
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.
449    *
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.
454    */
455   void ReplaceBidirectionalInfo( CharacterIndex characterIndex,
456                                  Length numberOfCharactersToRemove,
457                                  const BidirectionalParagraphInfoRun* const bidirectionalInfo,
458                                  Length numberOfCharactersToInsert );
459
460   /**
461    * @brief Replaces the direction of the characters.
462    *
463    * @note If the number of characters is zero the directions buffer is cleared.
464    *
465    * @param[in] directions The directions of the characters.
466    * @param[in] numberOfCharacters The number of characters.
467    */
468   void SetCharacterDirections( const CharacterDirection* const directions,
469                                Length numberOfCharacters );
470
471   /**
472    * @brief Retrieves the direction of the characters.
473    *
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.
478    *
479    * See SetBidirectionalInfo() to get an explanation of the 'paragraph' meaning in the bidirectional algorithm.
480    *
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.
483    *
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.
487    */
488   void GetCharacterDirections( CharacterDirection* directions,
489                                CharacterIndex characterIndex,
490                                Length numberOfCharacters ) const;
491
492   /**
493    * @brief Retrieves the direction of a characters.
494    *
495    * See GetCharacterDirections().
496    *
497    * @param[in] characterIndex Index to a character.
498    *
499    * @return The character's direction.
500    */
501   CharacterDirection GetCharacterDirection( CharacterIndex characterIndex ) const;
502
503   // Visual <--> Logical conversion tables.
504
505   /**
506    * @brief Sets the visual to logical and the logical to visual map tables.
507    *
508    * Replaces any map tables previously set.
509    *
510    * @note If the number of runs is zero the bidirectional info buffer is cleared.
511    *
512    * @param[in] bidirectionalInfo Pointer to a buffer with all the bidirectional info runs.
513    * @param[in] numberOfRuns The number of bidirectional info runs.
514    */
515   void SetVisualToLogicalMap( const BidirectionalLineInfoRun* const bidirectionalInfo,
516                               Length numberOfRuns );
517
518   /**
519    * @brief Replaces the visual to logical and logical to visual map tables for the given range of characters.
520    *
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.
523    *
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.
528    */
529   void ReplaceVisualToLogicalMap( CharacterIndex characterIndex,
530                                   Length numberOfCharactersToRemove,
531                                   const BidirectionalLineInfoRun* const bidirectionalInfo,
532                                   Length numberOfCharactersToInsert );
533
534   /**
535    * @brief Retrieves the visual character index for the given logical character index.
536    *
537    * @param[in] logicalCharacterIndex The logical character index.
538    *
539    * @return The visual character index.
540    */
541   CharacterIndex GetVisualCharacterIndex( CharacterIndex logicalCharacterIndex ) const;
542
543   /**
544    * @brief Retrieves the logical character index for the given visual character index.
545    *
546    * @param[in] visualCharacterIndex The visual character index.
547    *
548    * @return The logical character index.
549    */
550   CharacterIndex GetLogicalCharacterIndex( CharacterIndex visualCharacterIndex ) const;
551
552   /**
553    * @brief Retrieves the whole or part of the logical to visual conversion map.
554    *
555    * The size of the buffer needs to be big enough to copy the @p numberOfCharacters.
556    *
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.
560    */
561   void GetLogicalToVisualMap( CharacterIndex* logicalToVisualMap,
562                               CharacterIndex characterIndex,
563                               Length numberOfCharacters ) const;
564
565   /**
566    * @brief Retrieves the whole or part of the visual to logical conversion map.
567    *
568    * The size of the buffer needs to be big enough to copy the @p numberOfCharacters.
569    *
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.
573    */
574   void GetVisualToLogicalMap( CharacterIndex* visualToLogicalMap,
575                               CharacterIndex characterIndex,
576                               Length numberOfCharacters ) const;
577
578 protected:
579
580   /**
581    * @brief A reference counted object may only be deleted by calling Unreference().
582    */
583   virtual ~LogicalModel();
584
585 private:
586
587   /**
588    * @brief Private constructor.
589    */
590   LogicalModel();
591
592   // Undefined
593   LogicalModel( const LogicalModel& handle );
594
595   // Undefined
596   LogicalModel& operator=( const LogicalModel& handle );
597
598 public:
599
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.
611 };
612
613 } // namespace Text
614
615 } // namespace Toolkit
616
617 } // namespace Dali
618
619 #endif // __DALI_TOOLKIT_TEXT_LOGICAL_MODEL_IMPL_H__