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   // Language support interface.
 104
 105   /**
 106    * Sets the script runs.
 107    *
 108    * Replaces any scripts previously set.
 109    *
 110    * A run is a group of consecutive characters. A script run contains the script for a run.
 111    *
 112    * @note If the number of runs is zero the script buffer is cleared.
 113    *
 114    * @param[in] scripts Pointer to a buffer with all the script runs.
 115    * @param[in] numberOfRuns The number of script runs.
 116    */
 117   void SetScripts( const ScriptRun* const scripts,
 118                    Length numberOfRuns );
 119
 120   /**
 121    * Retrieves the number of script runs for the given range of characters.
 122    *
 123    * A run is a group of consecutive characters. A script run contains the script for a run.
 124    *
 125    * @param[in] characterIndex Index to the first character.
 126    * @param[in] numberOfCharacters The number of characters.
 127    *
 128    * @return The number of script runs.
 129    */
 130   Length GetNumberOfScriptRuns( CharacterIndex characterIndex,
 131                                 Length numberOfCharacters ) const;
 132
 133   /**
 134    * Retrieves the script runs for the given range of characters.
 135    *
 136    * The @p scriptRuns buffer needs to be big enough to copy the number of script runs.
 137    * Call GetNumberOfScriptRuns() to retrieve the number of script runs.
 138    *
 139    * @param[out] scriptRuns Pointer to a buffer where the script runs are copied.
 140    * @param[in] characterIndex Index to the first character.
 141    * @param[in] numberOfCharacters The number of characters.
 142    */
 143   void GetScriptRuns( ScriptRun* scriptRuns,
 144                       CharacterIndex characterIndex,
 145                       Length numberOfCharacters ) const;
 146
 147   /**
 148    * Retrieves the script for the given character index.
 149    *
 150    * @param[in] characterIndex Index to the character.
 151    *
 152    * @return The character's script.
 153    */
 154   Script GetScript( CharacterIndex characterIndex ) const;
 155
 156   /**
 157    * Sets the font runs.
 158    *
 159    * Replaces any fonts previously set.
 160    *
 161    * A run is a group of consecutive characters. A font run contains the font id for a run.
 162    *
 163    * @note If the number of runs is zero the font buffer is cleared.
 164    *
 165    * @param[in] fonts Pointer to a buffer with all the font runs.
 166    * @param[in] numberOfRuns The number of font runs.
 167    */
 168   void SetFonts( const FontRun* const fonts,
 169                  Length numberOfRuns );
 170
 171   /**
 172    * Retrieves the number of font runs for the given range of characters.
 173    *
 174    * A run is a group of consecutive characters. A font run contains the font id for a run.
 175    *
 176    * @param[in] characterIndex Index to the first character.
 177    * @param[in] numberOfCharacters The number of characters.
 178    *
 179    * @return The number of font runs.
 180    */
 181   Length GetNumberOfFontRuns( CharacterIndex characterIndex,
 182                               Length numberOfCharacters ) const;
 183
 184   /**
 185    * Retrieves the font runs for the given range of characters.
 186    *
 187    * The @p fontRuns buffer needs to be big enough to copy the number of font runs.
 188    * Call GetNumberOfFontRuns() to retrieve the number of font runs.
 189    *
 190    * @param[out] fontRuns Pointer to a buffer where the font runs are copied.
 191    * @param[in] characterIndex Index to the first character.
 192    * @param[in] numberOfCharacters The number of characters.
 193    */
 194   void GetFontRuns( FontRun* fontRuns,
 195                     CharacterIndex characterIndex,
 196                     Length numberOfCharacters ) const;
 197
 198   /**
 199    * Retrieves the font id for the given character index.
 200    *
 201    * @param[in] characterIndex Index to the first character.
 202    *
 203    * @return The font id.
 204    */
 205   FontId GetFont( CharacterIndex characterIndex ) const;
 206
 207   // Break info interface.
 208
 209   /**
 210    * Sets the line break info.
 211    *
 212    * See GetLineBreakInfo() to get how the line break info is encoded.
 213    *
 214    * Replaces any line break info previously set.
 215    *
 216    * @note If the @length is zero the break info buffer is cleared.
 217    *
 218    * @param[in] lineBreakInfo Pointer to a buffer with the line break info.
 219    * @param[in] length The size of the buffer.
 220    */
 221   void SetLineBreakInfo( const LineBreakInfo* const lineBreakInfo,
 222                          Length length );
 223
 224   /**
 225    * Retrieves the line break info in the given buffer.
 226    *
 227    * The size of the @p lineBreakInfo buffer needs to be big enough to copy the @p numberOfItems.
 228    *
 229    * Possible values for LineBreakInfo are:
 230    *
 231    *  - 0 is a LINE_MUST_BREAK.  Text must be broken into a new line.
 232    *  - 1 is a LINE_ALLOW_BREAK. Is possible to break the text into a new line.
 233    *  - 2 is a LINE_NO_BREAK.    Text can't be broken into a new line.
 234    *
 235      @verbatim
 236      i.e. Hello big\nworld produces:
 237           2222212220 22220
 238      @endverbatim
 239    *
 240    * @param[out] lineBreakInfo Pointer to a buffer where the line break info is copied.
 241    * @param[in] characterIndex Index to the first line break info item.
 242    * @param[in] numberOfItems The number of items to be copied.
 243    */
 244   void GetLineBreakInfo( LineBreakInfo* lineBreakInfo,
 245                          CharacterIndex characterIndex,
 246                          Length numberOfItems ) const;
 247
 248   /**
 249    * Retrieves the line break info for the given item index.
 250    *
 251    * @param[in] characterIndex Index to the line break info item.
 252    */
 253   LineBreakInfo GetLineBreakInfo( CharacterIndex characterIndex ) const;
 254
 255   /**
 256    * Sets the word break info.
 257    *
 258    * See GetWordBreakInfo() to get how the word break info is encoded.
 259    *
 260    * Replaces any word break info previously set.
 261    *
 262    * @note If the @length is zero the break info buffer is cleared.
 263    *
 264    * @param[in] wordBreakInfo Pointer to a buffer with the word break info.
 265    * @param[in] length The size of the buffer.
 266    */
 267   void SetWordBreakInfo( const WordBreakInfo* const wordBreakInfo,
 268                          Length length );
 269
 270   /**
 271    * Retrieves the word break info in the given buffer.
 272    *
 273    * The size of the @p wordBreakInfo buffer needs to be big enough to copy the @p numberOfItems.
 274    *
 275    * The size of the buffer has to be big enough to store the whole word break info per character.
 276    * Call GetNumberOfCharacters() to get the number of characters.
 277    *
 278    * Possible values for WordBreakInfo are:
 279    *
 280    * - 0 is a WORD_BREAK.    Text can be broken into a new word.
 281    * - 1 is a WORD_NO_BREAK. Text can't be broken into a new word.
 282    *
 283      @verbatim
 284      i.e. Hello big\nworld produces:
 285           1111001100 11110
 286      @endverbatim
 287    *
 288    * @param[out] wordBreakInfo Pointer to a buffer where the word break info is copied.
 289    * @param[in] characterIndex Index to the first word break info item.
 290    * @param[in] numberOfItems The number of items to be copied.
 291    */
 292   void GetWordBreakInfo( WordBreakInfo* wordBreakInfo,
 293                          CharacterIndex characterIndex,
 294                          Length numberOfItems ) const;
 295
 296   /**
 297    * Retrieves the word break info for the given item index.
 298    *
 299    * @param[in] characterIndex Index to the word break info item.
 300    */
 301   WordBreakInfo GetWordBreakInfo( CharacterIndex characterIndex ) const;
 302
 303   // Bidirectional support interface.
 304
 305   /**
 306    * Sets the bidirectional info runs.
 307    *
 308    * Replaces any bidirectional info previously set.
 309    *
 310    * Each bidirectional info run stores bidirectional info for a whole 'paragraph' of text which contains right to left scripts.
 311
 312    * In terms of the bidirectional algorithm, a 'paragraph' is understood as a run of characters between Paragraph Separators or appropriate Newline Functions.
 313    * A 'paragraph' may also be determined by higher-level protocols like a mark-up tag.
 314    *
 315    * @note If the number of runs is zero the bidirectional info buffer is cleared.
 316    *
 317    * @param[in] bidirectionalInfo Pointer to a buffer with all the bidirectional info runs.
 318    * @param[in] numberOfRuns The number of bidirectional info runs.
 319    */
 320   void SetBidirectionalInfo( const BidirectionalParagraphInfoRun* const bidirectionalInfo,
 321                              Length numberOfRuns );
 322
 323   /**
 324    * Retrieves the number of bidirectional info runs for the given range of characters.
 325    *
 326    * It may be zero if there is no right to left scripts.
 327    *
 328    * @param[in] characterIndex Index to the first character.
 329    * @param[in] numberOfCharacters The number of characters.
 330    *
 331    * @return The number of bidirectional info runs.
 332    */
 333   Length GetNumberOfBidirectionalInfoRuns( CharacterIndex characterIndex,
 334                                            Length numberOfCharacters ) const;
 335
 336   /**
 337    * Retrieves the bidirectional paragraph info runs for the given range of characters.
 338    *
 339    * The @p bidirectionalInfo buffer needs to be big enough to copy the number of bidirectional
 340    * paragraph info runs.
 341    * Call GetNumberOfBidirectionalInfoRuns() to retrieve the number of bidirectional runs.
 342    *
 343    * @param[out] bidirectionalInfo Pointer to a buffer where the bidirectional info runs are copied.
 344    * @param[in] characterIndex Index to the first character.
 345    * @param[in] numberOfCharacters The number of characters.
 346    */
 347   void GetBidirectionalInfo( BidirectionalParagraphInfoRun* bidirectionalInfo,
 348                              CharacterIndex characterIndex,
 349                              Length numberOfCharacters ) const;
 350
 351   /**
 352    * Retrieves the direction of the characters.
 353    *
 354    * It sets @c true for right to left characters and @c false for left to right.
 355    * For neutral characters it check's the next and previous character's directions:
 356    * - If they are equals set that direction. If they are not, sets the paragraph's direction.
 357    * - If there is no next, sets the paragraph's direction.
 358    *
 359    * See SetBidirectionalInfo() to get an explanation of the 'paragraph' meaning in the bidirectional algorithm.
 360    *
 361    * @param[out] directions Whether the characters are right to left or left to right.
 362    * @param[in] characterIndex Index to the first character.
 363    * @param[in] numberOfCharacters The number of characters.
 364    */
 365   void GetCharacterDirections( CharacterDirection* directions,
 366                                CharacterIndex characterIndex,
 367                                Length numberOfCharacters ) const;
 368
 369   /**
 370    * Retrieves the direction of a characters.
 371    *
 372    * See GetCharacterDirections().
 373    *
 374    * @param[in] characterIndex Index to a character.
 375    *
 376    * @return The character's direction.
 377    */
 378   CharacterDirection GetCharacterDirection( CharacterIndex characterIndex ) const;
 379
 380   // Visual <--> Logical conversion tables.
 381
 382   /**
 383    * Sets the visual to logical and the logical to visual map tables.
 384    *
 385    * Replaces any map tables previously set.
 386    *
 387    * @note If the number of runs is zero the bidirectional info buffer is cleared.
 388    *
 389    * @param[in] bidirectionalInfo Pointer to a buffer with all the bidirectional info runs.
 390    * @param[in] numberOfRuns The number of bidirectional info runs.
 391    */
 392   void SetVisualToLogicalMap( const BidirectionalLineInfoRun* const bidirectionalInfo,
 393                               Length numberOfRuns );
 394
 395   /**
 396    * Retrieves the visual character index for the given logical character index.
 397    *
 398    * @param[in] logicalCharacterIndex The logical character index.
 399    *
 400    * @return The visual character index.
 401    */
 402   CharacterIndex GetVisualCharacterIndex( CharacterIndex logicalCharacterIndex ) const;
 403
 404   /**
 405    * Retrieves the logical character index for the given visual character index.
 406    *
 407    * @param[in] visualCharacterIndex The visual character index.
 408    *
 409    * @return The logical character index.
 410    */
 411   CharacterIndex GetLogicalCharacterIndex( CharacterIndex visualCharacterIndex ) const;
 412
 413   /**
 414    * Retrieves the whole or part of the logical to visual conversion map.
 415    *
 416    * The size of the buffer needs to be big enough to copy the @p numberOfCharacters.
 417    *
 418    * @param[out] logicalToVisualMap Pointer to a buffer where the conversion map is copied.
 419    * @param[in] characterIndex Index to the first character.
 420    * @param[in] numberOfCharacters The number of characters.
 421    */
 422   void GetLogicalToVisualMap( CharacterIndex* logicalToVisualMap,
 423                               CharacterIndex characterIndex,
 424                               Length numberOfCharacters ) const;
 425
 426   /**
 427    * Retrieves the whole or part of the visual to logical conversion map.
 428    *
 429    * The size of the buffer needs to be big enough to copy the @p numberOfCharacters.
 430    *
 431    * @param[out] visualToLogicalMap Pointer to a buffer where the conversion map is copied.
 432    * @param[in] characterIndex Index to the first character.
 433    * @param[in] numberOfCharacters The number of characters.
 434    */
 435   void GetVisualToLogicalMap( CharacterIndex* visualToLogicalMap,
 436                               CharacterIndex characterIndex,
 437                               Length numberOfCharacters ) const;
 438
 439 protected:
 440
 441   /**
 442    * @brief A reference counted object may only be deleted by calling Unreference().
 443    */
 444   virtual ~LogicalModel();
 445
 446 private:
 447
 448   /**
 449    * @brief Private constructor.
 450    */
 451   LogicalModel();
 452
 453   // Undefined
 454   LogicalModel( const LogicalModel& handle );
 455
 456   // Undefined
 457   LogicalModel& operator=( const LogicalModel& handle );
 458
 459 private:
 460
 461   struct Impl;
 462   Impl* mImpl;
 463 };
 464
 465 } // namespace Text
 466
 467 } // namespace Toolkit
 468
 469 } // namespace Dali
 470
 471 #endif // __DALI_TOOLKIT_TEXT_LOGICAL_MODEL_H__