dali-toolkit/internal/text/logical-model.h

   1 #ifndef __DALI_TOOLKIT_TEXT_LOGICAL_MODEL_H__
   2 #define __DALI_TOOLKIT_TEXT_LOGICAL_MODEL_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/text-definitions.h>
  28
  29 namespace Dali
  30 {
  31
  32 namespace Toolkit
  33 {
  34
  35 namespace Text
  36 {
  37
  38 struct BidirectionalLineInfoRun;
  39 struct BidirectionalParagraphInfoRun;
  40 struct FontRun;
  41 class LogicalModel;
  42 typedef IntrusivePtr<LogicalModel> LogicalModelPtr;
  43 struct ScriptRun;
  44
  45 /**
  46  * @brief A logical text model contains layout independent information.
  47  *
  48  * This includes:
  49  * - A series of UTF-32 characters in logical order
  50  */
  51 class LogicalModel : public RefObject
  52 {
  53 public:
  54
  55   /**
  56    * @brief Create a new instance of a LogicalModel.
  57    *
  58    * @return A pointer to a new LogicalModel.
  59    */
  60   static LogicalModelPtr New();
  61
  62   // Text interface.
  63
  64   /**
  65    * @brief Replaces any text previously set.
  66    *
  67    * @note If the number of characters is zero the text buffer is cleared.
  68    *
  69    * @param[in] text An array of UTF-32 characters.
  70    * @param[in] numberOfCharacters The length of the array.
  71    */
  72   void SetText( const Character* const text,
  73                 Length numberOfCharacters );
  74
  75   /**
  76    * @brief Retrieves the number of characters of the text.
  77    *
  78    * @return The number of characters.
  79    */
  80   Length GetNumberOfCharacters() const;
  81
  82   /**
  83    * @brief Retrieves characters from the text in the given buffer.
  84    *
  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.
  89    */
  90   void GetText( Character* text,
  91                 CharacterIndex characterIndex,
  92                 Length numberOfCharacters ) const;
  93
  94   /**
  95    * Retrieves a character.
  96    *
  97    * @param[in] characterIndex Index to a character.
  98    *
  99    * @return A character.
 100    */
 101   Character GetCharacter( CharacterIndex characterIndex ) const;
 102
 103   /**
 104    * Replaces characters from the text.
 105    *
 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.
 108    *
 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.
 113    */
 114   void ReplaceText( CharacterIndex characterIndex,
 115                     Length numberOfCharactersToRemove,
 116                     const Character* const text,
 117                     Length numberOfCharactersToInsert );
 118
 119   // Language support interface.
 120
 121   /**
 122    * Sets the script runs.
 123    *
 124    * Replaces any scripts previously set.
 125    *
 126    * A run is a group of consecutive characters. A script run contains the script for a run.
 127    *
 128    * @note If the number of runs is zero the script buffer is cleared.
 129    *
 130    * @param[in] scripts Pointer to a buffer with all the script runs.
 131    * @param[in] numberOfRuns The number of script runs.
 132    */
 133   void SetScripts( const ScriptRun* const scripts,
 134                    Length numberOfRuns );
 135
 136   /**
 137    * Retrieves the number of script runs for the given range of characters.
 138    *
 139    * A run is a group of consecutive characters. A script run contains the script for a run.
 140    *
 141    * @param[in] characterIndex Index to the first character.
 142    * @param[in] numberOfCharacters The number of characters.
 143    *
 144    * @return The number of script runs.
 145    */
 146   Length GetNumberOfScriptRuns( CharacterIndex characterIndex,
 147                                 Length numberOfCharacters ) const;
 148
 149   /**
 150    * Retrieves the script runs for the given range of characters.
 151    *
 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.
 154    *
 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.
 158    */
 159   void GetScriptRuns( ScriptRun* scriptRuns,
 160                       CharacterIndex characterIndex,
 161                       Length numberOfCharacters ) const;
 162
 163   /**
 164    * Retrieves the script for the given character index.
 165    *
 166    * @param[in] characterIndex Index to the character.
 167    *
 168    * @return The character's script.
 169    */
 170   Script GetScript( CharacterIndex characterIndex ) const;
 171
 172   /**
 173    * Replaces script runs for the given range of characters.
 174    *
 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.
 177    *
 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.
 182    */
 183   void ReplaceScripts( CharacterIndex characterIndex,
 184                        Length numberOfCharactersToRemove,
 185                        const ScriptRun* const scriptRuns,
 186                        Length numberOfCharactersToInsert );
 187
 188   /**
 189    * Sets the font runs.
 190    *
 191    * Replaces any fonts previously set.
 192    *
 193    * A run is a group of consecutive characters. A font run contains the font id for a run.
 194    *
 195    * @note If the number of runs is zero the font buffer is cleared.
 196    *
 197    * @param[in] fonts Pointer to a buffer with all the font runs.
 198    * @param[in] numberOfRuns The number of font runs.
 199    */
 200   void SetFonts( const FontRun* const fonts,
 201                  Length numberOfRuns );
 202
 203   /**
 204    * Retrieves the number of font runs for the given range of characters.
 205    *
 206    * A run is a group of consecutive characters. A font run contains the font id for a run.
 207    *
 208    * @param[in] characterIndex Index to the first character.
 209    * @param[in] numberOfCharacters The number of characters.
 210    *
 211    * @return The number of font runs.
 212    */
 213   Length GetNumberOfFontRuns( CharacterIndex characterIndex,
 214                               Length numberOfCharacters ) const;
 215
 216   /**
 217    * Retrieves the font runs for the given range of characters.
 218    *
 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.
 221    *
 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.
 225    */
 226   void GetFontRuns( FontRun* fontRuns,
 227                     CharacterIndex characterIndex,
 228                     Length numberOfCharacters ) const;
 229
 230   /**
 231    * Retrieves the font id for the given character index.
 232    *
 233    * @param[in] characterIndex Index to the first character.
 234    *
 235    * @return The font id.
 236    */
 237   FontId GetFont( CharacterIndex characterIndex ) const;
 238
 239   /**
 240    * Replaces font runs for the given range of characters.
 241    *
 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.
 244    *
 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.
 249    */
 250   void ReplaceFonts( CharacterIndex characterIndex,
 251                      Length numberOfCharactersToRemove,
 252                      const FontRun* const fontRuns,
 253                      Length numberOfCharactersToInsert );
 254
 255   // Break info interface.
 256
 257   /**
 258    * Sets the line break info.
 259    *
 260    * See GetLineBreakInfo() to get how the line break info is encoded.
 261    *
 262    * Replaces any line break info previously set.
 263    *
 264    * @note If the @length is zero the break info buffer is cleared.
 265    *
 266    * @param[in] lineBreakInfo Pointer to a buffer with the line break info.
 267    * @param[in] length The size of the buffer.
 268    */
 269   void SetLineBreakInfo( const LineBreakInfo* const lineBreakInfo,
 270                          Length length );
 271
 272   /**
 273    * Retrieves the line break info in the given buffer.
 274    *
 275    * The size of the @p lineBreakInfo buffer needs to be big enough to copy the @p numberOfItems.
 276    *
 277    * Possible values for LineBreakInfo are:
 278    *
 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.
 282    *
 283      @verbatim
 284      i.e. Hello big\nworld produces:
 285           2222212220 22220
 286      @endverbatim
 287    *
 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.
 291    */
 292   void GetLineBreakInfo( LineBreakInfo* lineBreakInfo,
 293                          CharacterIndex characterIndex,
 294                          Length numberOfItems ) const;
 295
 296   /**
 297    * Retrieves the line break info for the given item index.
 298    *
 299    * @param[in] characterIndex Index to the line break info item.
 300    */
 301   LineBreakInfo GetLineBreakInfo( CharacterIndex characterIndex ) const;
 302
 303   /**
 304    * Replaces line break info.
 305    *
 306    * See GetLineBreakInfo() to get how the line break info is encoded.
 307    *
 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.
 310    *
 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.
 315    */
 316   void ReplaceLineBreakInfo( CharacterIndex characterIndex,
 317                              Length numberOfItemsToRemove,
 318                              const LineBreakInfo* const lineBreakInfo,
 319                              Length numberOfItemsToInsert );
 320
 321   /**
 322    * Sets the word break info.
 323    *
 324    * See GetWordBreakInfo() to get how the word break info is encoded.
 325    *
 326    * Replaces any word break info previously set.
 327    *
 328    * @note If the @length is zero the break info buffer is cleared.
 329    *
 330    * @param[in] wordBreakInfo Pointer to a buffer with the word break info.
 331    * @param[in] length The size of the buffer.
 332    */
 333   void SetWordBreakInfo( const WordBreakInfo* const wordBreakInfo,
 334                          Length length );
 335
 336   /**
 337    * Retrieves the word break info in the given buffer.
 338    *
 339    * The size of the @p wordBreakInfo buffer needs to be big enough to copy the @p numberOfItems.
 340    *
 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.
 343    *
 344    * Possible values for WordBreakInfo are:
 345    *
 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.
 348    *
 349      @verbatim
 350      i.e. Hello big\nworld produces:
 351           1111001100 11110
 352      @endverbatim
 353    *
 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.
 357    */
 358   void GetWordBreakInfo( WordBreakInfo* wordBreakInfo,
 359                          CharacterIndex characterIndex,
 360                          Length numberOfItems ) const;
 361
 362   /**
 363    * Retrieves the word break info for the given item index.
 364    *
 365    * @param[in] characterIndex Index to the word break info item.
 366    */
 367   WordBreakInfo GetWordBreakInfo( CharacterIndex characterIndex ) const;
 368
 369   /**
 370    * Replaces word break info.
 371    *
 372    * See GetWordBreakInfo() to get how the word break info is encoded.
 373    *
 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.
 376    *
 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.
 381    */
 382   void ReplaceWordBreakInfo( CharacterIndex characterIndex,
 383                              Length numberOfItemsToRemove,
 384                              const WordBreakInfo* const wordBreakInfo,
 385                              Length numberOfItemsToInsert );
 386
 387   // Bidirectional support interface.
 388
 389   /**
 390    * Sets the bidirectional info runs.
 391    *
 392    * Replaces any bidirectional info previously set.
 393    *
 394    * Each bidirectional info run stores bidirectional info for a whole 'paragraph' of text which contains right to left scripts.
 395
 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.
 398    *
 399    * @note If the number of runs is zero the bidirectional info buffer is cleared.
 400    *
 401    * @param[in] bidirectionalInfo Pointer to a buffer with all the bidirectional info runs.
 402    * @param[in] numberOfRuns The number of bidirectional info runs.
 403    */
 404   void SetBidirectionalInfo( const BidirectionalParagraphInfoRun* const bidirectionalInfo,
 405                              Length numberOfRuns );
 406
 407   /**
 408    * Retrieves the number of bidirectional info runs for the given range of characters.
 409    *
 410    * It may be zero if there is no right to left scripts.
 411    *
 412    * @param[in] characterIndex Index to the first character.
 413    * @param[in] numberOfCharacters The number of characters.
 414    *
 415    * @return The number of bidirectional info runs.
 416    */
 417   Length GetNumberOfBidirectionalInfoRuns( CharacterIndex characterIndex,
 418                                            Length numberOfCharacters ) const;
 419
 420   /**
 421    * Retrieves the bidirectional paragraph info runs for the given range of characters.
 422    *
 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.
 426    *
 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.
 430    */
 431   void GetBidirectionalInfo( BidirectionalParagraphInfoRun* bidirectionalInfo,
 432                              CharacterIndex characterIndex,
 433                              Length numberOfCharacters ) const;
 434
 435   /**
 436    * Replaces bidirectional info runs for the given range of characters.
 437    *
 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.
 440    *
 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.
 445    */
 446   void ReplaceBidirectionalInfo( CharacterIndex characterIndex,
 447                                  Length numberOfCharactersToRemove,
 448                                  const BidirectionalParagraphInfoRun* const bidirectionalInfo,
 449                                  Length numberOfCharactersToInsert );
 450
 451   /**
 452    * Retrieves the direction of the characters.
 453    *
 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.
 458    *
 459    * See SetBidirectionalInfo() to get an explanation of the 'paragraph' meaning in the bidirectional algorithm.
 460    *
 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.
 464    */
 465   void GetCharacterDirections( CharacterDirection* directions,
 466                                CharacterIndex characterIndex,
 467                                Length numberOfCharacters ) const;
 468
 469   /**
 470    * Retrieves the direction of a characters.
 471    *
 472    * See GetCharacterDirections().
 473    *
 474    * @param[in] characterIndex Index to a character.
 475    *
 476    * @return The character's direction.
 477    */
 478   CharacterDirection GetCharacterDirection( CharacterIndex characterIndex ) const;
 479
 480   // Visual <--> Logical conversion tables.
 481
 482   /**
 483    * Sets the visual to logical and the logical to visual map tables.
 484    *
 485    * Replaces any map tables previously set.
 486    *
 487    * @note If the number of runs is zero the bidirectional info buffer is cleared.
 488    *
 489    * @param[in] bidirectionalInfo Pointer to a buffer with all the bidirectional info runs.
 490    * @param[in] numberOfRuns The number of bidirectional info runs.
 491    */
 492   void SetVisualToLogicalMap( const BidirectionalLineInfoRun* const bidirectionalInfo,
 493                               Length numberOfRuns );
 494
 495   /**
 496    * Replaces the visual to logical and logical to visual map tables for the given range of characters.
 497    *
 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.
 500    *
 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.
 505    */
 506   void ReplaceVisualToLogicalMap( CharacterIndex characterIndex,
 507                                   Length numberOfCharactersToRemove,
 508                                   const BidirectionalLineInfoRun* const bidirectionalInfo,
 509                                   Length numberOfCharactersToInsert );
 510
 511   /**
 512    * Retrieves the visual character index for the given logical character index.
 513    *
 514    * @param[in] logicalCharacterIndex The logical character index.
 515    *
 516    * @return The visual character index.
 517    */
 518   CharacterIndex GetVisualCharacterIndex( CharacterIndex logicalCharacterIndex ) const;
 519
 520   /**
 521    * Retrieves the logical character index for the given visual character index.
 522    *
 523    * @param[in] visualCharacterIndex The visual character index.
 524    *
 525    * @return The logical character index.
 526    */
 527   CharacterIndex GetLogicalCharacterIndex( CharacterIndex visualCharacterIndex ) const;
 528
 529   /**
 530    * Retrieves the whole or part of the logical to visual conversion map.
 531    *
 532    * The size of the buffer needs to be big enough to copy the @p numberOfCharacters.
 533    *
 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.
 537    */
 538   void GetLogicalToVisualMap( CharacterIndex* logicalToVisualMap,
 539                               CharacterIndex characterIndex,
 540                               Length numberOfCharacters ) const;
 541
 542   /**
 543    * Retrieves the whole or part of the visual to logical conversion map.
 544    *
 545    * The size of the buffer needs to be big enough to copy the @p numberOfCharacters.
 546    *
 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.
 550    */
 551   void GetVisualToLogicalMap( CharacterIndex* visualToLogicalMap,
 552                               CharacterIndex characterIndex,
 553                               Length numberOfCharacters ) const;
 554
 555 protected:
 556
 557   /**
 558    * @brief A reference counted object may only be deleted by calling Unreference().
 559    */
 560   virtual ~LogicalModel();
 561
 562 private:
 563
 564   /**
 565    * @brief Private constructor.
 566    */
 567   LogicalModel();
 568
 569   // Undefined
 570   LogicalModel( const LogicalModel& handle );
 571
 572   // Undefined
 573   LogicalModel& operator=( const LogicalModel& handle );
 574
 575 private:
 576
 577   struct Impl;
 578   Impl* mImpl;
 579 };
 580
 581 } // namespace Text
 582
 583 } // namespace Toolkit
 584
 585 } // namespace Dali
 586
 587 #endif // __DALI_TOOLKIT_TEXT_LOGICAL_MODEL_H__