capi/dali-toolkit/public-api/markup-processor/markup-processor.h

   1 #ifndef __DALI_TOOLKIT_MARKUP_PROCESSOR_H__
   2 #define __DALI_TOOLKIT_MARKUP_PROCESSOR_H__
   3
   4 //
   5 // Copyright (c) 2014 Samsung Electronics Co., Ltd.
   6 //
   7 // Licensed under the Flora License, Version 1.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://floralicense.org/license/
  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  * @addtogroup CAPI_DALI_TOOLKIT_MARKUP_PROCESSOR_MODULE
  22  * @{
  23  */
  24
  25 // INTERNAL INCLUDES
  26 #include <dali/public-api/common/vector-wrapper.h>
  27
  28 #include <dali/public-api/text/text.h>
  29 #include <dali/public-api/text/text-style.h>
  30
  31 namespace Dali DALI_IMPORT_API
  32 {
  33
  34 namespace Toolkit
  35 {
  36
  37 /**
  38  * @brief Markup Processor enumerations, structures and functions.
  39  *
  40  * See the \link markup-processor Markup Processor \endlink page in the Programming Guide.
  41  */
  42 namespace MarkupProcessor
  43 {
  44
  45 /**
  46  * @brief A pair of Dali::Text and Dali::TextStyle.
  47  *
  48  * mText is a Dali::Text object which can store text in different
  49  * languages. mStyle is a Dali::TextStyle object which can store all
  50  * text styling features provided by Dali::TextActor.
  51  */
  52 struct StyledText
  53 {
  54   /**
  55    * @brief Constructor
  56    */
  57   StyledText()
  58   : mText(),
  59     mStyle()
  60   {
  61   }
  62
  63   /**
  64    * @brief Constructor
  65    *
  66    * @param[in] text  A Text object
  67    * @param[in] style A Style object
  68    */
  69   StyledText( const Text& text, const TextStyle& style )
  70   : mText( text ),
  71     mStyle( style )
  72   {
  73   }
  74
  75   Text      mText;  ///< Store text. Could be a mix of different languages.
  76   TextStyle mStyle; ///< Store the style for the text.
  77 };
  78
  79 /**
  80  * @brief This type defines a vector of StyledText.
  81  *
  82  * It's used to store a whole text with its style and set it to a
  83  * Dali::Toolkit::TextView. It could be used in other UI
  84  * Dali::Toolkit::Control classes which need text with style.
  85  */
  86 typedef std::vector<StyledText> StyledTextArray;
  87
  88 /**
  89  * @brief Creates a text array with its style from a markup string.
  90  *
  91  * Refer to the \link markup-processor Markup Processor \endlink page in the Programming Guide
  92  * to see the html-ish sintax and some examples.
  93  *
  94  * @param [in] markupString A string with style.
  95  * @param [out] styledTextArray A text array split in characters, each one with its style.
  96  * @param [in] scanForMarkup If true will check to see string contains markup, else assume not
  97  */
  98 void GetStyledTextArray( const std::string& markupString, StyledTextArray& styledTextArray, bool scanForMarkup );
  99
 100 /**
 101  * @brief Creates a plain string from a text array (thus stripping the style meta).
 102  *
 103  * @param [in] styledTextArray A text array split in characters, each one with its style.
 104  * @param [out] plainString A string without style.
 105  */
 106 void GetPlainString( const StyledTextArray& styledTextArray, std::string& plainString );
 107
 108 /**
 109  * @brief Creates a markup string from a text array with its style.
 110  *
 111  * @param [in] styledTextArray A text array split in characters, each one with its style.
 112  * @param [out] markupString A string with style.
 113  */
 114 void GetMarkupString( const StyledTextArray& styledTextArray, std::string& markupString );
 115
 116 /**
 117  * @brief Sets a text style to the given text.
 118  *
 119  * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
 120  * @param[in,out] styledTextArray The given text
 121  * @param[in] style The given style
 122  * @param[in] mask The bit mask.
 123  */
 124 void SetTextStyle( StyledTextArray& styledTextArray, const TextStyle& style, TextStyle::Mask mask = TextStyle::ALL );
 125
 126 /**
 127  * @brief Sets a text style to the given text.
 128  *
 129  * @see SetTextStyle( StyledTextArray& styledTextArray, const TextStyle& style, TextStyle::Mask mask )
 130  *
 131  * @param[in] text The input text.
 132  * @param[out] styledTextArray The input text with the given style.
 133  * @param[in] style The given style.
 134  * @param[in] mask The bit mask.
 135  */
 136 void SetTextStyle( const Text& text, StyledTextArray& styledTextArray, const TextStyle& style, TextStyle::Mask mask = TextStyle::ALL );
 137
 138 /**
 139  * @brief Sets a text style to a range of characters of the given text.
 140  *
 141  * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
 142  * @param[in,out] styledTextArray The given text
 143  * @param[in] style The given style
 144  * @param[in] mask The bit mask.
 145  * @param[in] begin The first character of the range.
 146  * @param[in] end The last character of the range.
 147  * @note It will assert if begin or end are out of range, or if begin > end.
 148  */
 149 void SetTextStyleToRange( StyledTextArray& styledTextArray, const TextStyle& style, TextStyle::Mask mask, std::size_t begin, std::size_t end );
 150
 151 } // namespace MarkupProcessor
 152
 153 } // namespace Toolkit
 154
 155 } // namespace Dali
 156
 157 /**
 158  * @}
 159  */
 160 #endif // __DALI_TOOLKIT_MARKUP_PROCESSOR_H__