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