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 namespace MarkupProcessor
  41 {
  42
  43 /**
  44  * @brief A pair of Dali::Text and Dali::TextStyle.
  45  *
  46  * mText is a Dali::Text object which can store text in different
  47  * languages. mStyle is a Dali::TextStyle object which can store all
  48  * text styling features provided by Dali::TextActor.
  49  */
  50 struct StyledText
  51 {
  52   /**
  53    * @brief Constructor
  54    */
  55   StyledText()
  56   : mText(),
  57     mStyle()
  58   {
  59   }
  60
  61   /**
  62    * @brief Constructor
  63    *
  64    * @param[in] text  A Text object
  65    * @param[in] style A Style object
  66    */
  67   StyledText( const Text& text, const TextStyle& style )
  68   : mText( text ),
  69     mStyle( style )
  70   {
  71   }
  72
  73   Text      mText;  ///< Store text. Could be a mix of different languages.
  74   TextStyle mStyle; ///< Store the style for the text.
  75 };
  76
  77 /**
  78  * @brief This type defines a vector of StyledText.
  79  *
  80  * It's used to store a whole text with its style and set it to a
  81  * Dali::Toolkit::TextView. It could be used in other UI
  82  * Dali::Toolkit::Control classes which need text with style.
  83  */
  84 typedef std::vector<StyledText> StyledTextArray;
  85
  86 /**
  87  * @brief Creates a text array with its style from a markup string.
  88  *
  89  * The syntax of a markup string is html-ish. It contains open, close
  90  * and empty tags and some of them can contain parameters.
  91  *
  92  * <ul>
  93  *   <li>\e \<b\>\</b\> Bold text.
  94  *   <li>\e \<i\>\</i\> Italic text.
  95  *   <li>\e \<u\>\</u\> Underlined text.
  96  *   <li>\e \<br /\> New line.
  97  *   <li>\e \<font\>\</font\> Specifies font properties:
  98  *     <ul>
  99  *       <li> \e face Font face.
 100  *       <li> \e size Font size.
 101  *       <li> \e color Font color.
 102  *     </ul>
 103  *   <li>\e \<shadow\>\</shadow\> Specifies shadow properties @see Dali::TextActor::SetShadow().
 104  *     <ul>
 105  *       <li> \e paramx X offset.
 106  *       <li> \e paramy Y offset.
 107  *       <li> \e color Shadow color.
 108  *     </ul>
 109  *   <li>\e \<glow\>\</glow\> Specifies glow properties @see Dali::TextActor::SetGlow().
 110  *     <ul>
 111  *       <li> \e param Glow around the text.
 112  *       <li> \e color Glow color.
 113  *     </ul>
 114  *   <li>\e \<outline\>\</outline\> Specifies outline properties @see Dali::TextActor::SetOutline().
 115  *     <ul>
 116  *       <li> \e paramx X thickness.
 117  *       <li> \e paramy Y thickness.
 118  *       <li> \e color Outline color.
 119  *     </ul>
 120  *   <li>\e \<smooth\>\</smooth\> Specify the smooth edge @see Dali::TextActor::SetSmoothEdge().
 121  *     <ul>
 122  *       <li> \e paramx Distance field.
 123  *     </ul>
 124  * </ul>
 125  *
 126  * It transform any pair CR+LF new line characters into a single LF new line character.
 127  * @param [in] markupString A string with style.
 128  * @param [out] styledTextArray A text array split in characters, each one with its style.
 129  * @param [in] scanForMarkup If true will check to see string contains markup, else assume not
 130  */
 131 void GetStyledTextArray( const std::string& markupString, StyledTextArray& styledTextArray, bool scanForMarkup );
 132
 133 /**
 134  * @brief Creates a plain string from a text array (thus stripping the style meta).
 135  *
 136  * @param [in] styledTextArray A text array split in characters, each one with its style.
 137  * @param [out] plainString A string without style.
 138  */
 139 void GetPlainString( const StyledTextArray& styledTextArray, std::string& plainString );
 140
 141 /**
 142  * @brief Creates a markup string from a text array with its style.
 143  *
 144  * @param [in] styledTextArray A text array split in characters, each one with its style.
 145  * @param [out] markupString A string with style.
 146  */
 147 void GetMarkupString( const StyledTextArray& styledTextArray, std::string& markupString );
 148
 149 /**
 150  * @brief Sets a text style to the given text.
 151  *
 152  * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
 153  * @param[in,out] styledTextArray The given text
 154  * @param[in] style The given style
 155  * @param[in] mask The bit mask.
 156  */
 157 void SetTextStyle( StyledTextArray& styledTextArray, const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
 158
 159 /**
 160  * @see SetTextStyle( StyledTextArray& styledTextArray, const TextStyle& style, StyleMask mask )
 161  * @param[in] text The input text.
 162  * @param[out] styledTextArray The input text with the given style.
 163  * @param[in] style The given style.
 164  * @param[in] mask The bit mask.
 165  */
 166 void SetTextStyle( const Text& text, StyledTextArray& styledTextArray, const TextStyle& style, const TextStyle::Mask mask = TextStyle::ALL );
 167
 168 /**
 169  * @brief Sets a text style to a range of characters of the given text.
 170  *
 171  * By default all style settings are applied but a bit mask could be used to modify only certain style settings.
 172  * @param[in,out] styledTextArray The given text
 173  * @param[in] style The given style
 174  * @param[in] mask The bit mask.
 175  * @param[in] begin The first character of the range.
 176  * @param[in] end The last character of the range.
 177  * @note It will assert if begin or end are out of range, or if begin > end.
 178  */
 179 void SetTextStyleToRange( StyledTextArray& styledTextArray, const TextStyle& style, const TextStyle::Mask mask, const std::size_t begin, const std::size_t end );
 180
 181 } // namespace MarkupProcessor
 182
 183 } // namespace Toolkit
 184
 185 } // namespace Dali
 186
 187 /**
 188  * @}
 189  */
 190 #endif // __DALI_TOOLKIT_MARKUP_PROCESSOR_H__