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