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