inc/FGrpTextElement.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Flora License, Version 1.0 (the License);
   6 // you may not use this file except in compliance with the License.
   7 // You may obtain a copy of the License at
   8 //
   9 //     http://floralicense.org/license/
  10 //
  11 // Unless required by applicable law or agreed to in writing, software
  12 // distributed under the License is distributed on an AS IS BASIS,
  13 // WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
  14 // See the License for the specific language governing permissions and
  15 // limitations under the License.
  16 //
  17
  18 /**
  19  * @file    FGrpTextElement.h
  20  * @brief   This is the header file for the %TextElement class.
  21  *
  22  * This header file contains the declarations of the %TextElement class.
  23  */
  24
  25 #ifndef _FGRP_TEXT_ELEMENT_H_
  26 #define _FGRP_TEXT_ELEMENT_H_
  27
  28 #include <FBase.h>
  29 #include <FBaseUtilTypes.h>
  30 #include <FGrpFont.h>
  31 #include <FGrpCanvas.h>
  32 #include <FGrpColor.h>
  33
  34 namespace Tizen { namespace Graphics
  35 {
  36 /**
  37  * @class   TextElement
  38  * @brief   This class provides methods for the text elements.
  39  *
  40  * @since   2.0
  41  *
  42  * @final       This class is not intended for extension.
  43  *
  44  * The %TextElement class encapsulates the characteristics of a text, such as the constant string and font style.
  45  * A text element draws the text on to a canvas.
  46  *
  47  * For more information on the attributes of %TextElement, see <a href="../org.tizen.native.appprogramming/html/guide/graphics/enriched_text.htm">EnrichedText</a>.
  48  *
  49  */
  50 class _OSP_EXPORT_ TextElement
  51         : public Tizen::Base::Object
  52 {
  53 public:
  54         /**
  55          * This is the default constructor for this class.
  56          *
  57          * @since               2.0
  58          *
  59          * @remarks     After creating an instance of this class, one of the
  60          *              Construct() methods must be called explicitly to initialize this instance.
  61          */
  62         TextElement(void);
  63
  64         /**
  65          * This is the destructor for this class.
  66          *
  67          * @since               2.0
  68          */
  69         virtual ~TextElement(void);
  70
  71         /**
  72          * Initializes the current instance of %TextElement with the specified text. @n
  73          * If the text is not specified, the default system font is set.
  74          *
  75          * @since       2.0
  76          *
  77          * @return      An error code
  78          * @param[in]   text                The text string
  79          * @exception   E_SUCCESS           The method is successful.
  80          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
  81          * @exception   E_INVALID_ARG       The specified input parameter is invalid.
  82          */
  83         result Construct(const Tizen::Base::String& text);
  84
  85         /**
  86          * Initializes the current instance of %TextElement with the specified text. @n
  87          * The canvas is used for initializing the font's color attributes, such as the foreground color and the background color.
  88          *
  89          * @since       2.0
  90          *
  91          * @return      An error code
  92          * @param[in]   text                The text string
  93          * @param[in]   canvas              The canvas to initialize the text element @n
  94          *                                  It sets the foreground and background colors of the text element.
  95          * @exception   E_SUCCESS           The method is successful.
  96          * @exception   E_OUT_OF_MEMORY     The memory is insufficient.
  97          * @exception   E_INVALID_ARG       A specified input parameter is invalid.
  98          */
  99         result Construct(const Tizen::Base::String& text, const Tizen::Graphics::Canvas& canvas);
 100
 101         /**
 102          * Initializes the current instance of %TextElement.
 103          *
 104          * @since       2.0
 105          *
 106          * @return      An error code
 107          * @exception   E_SUCCESS            The method is successful.
 108          * @exception   E_OUT_OF_MEMORY      The memory is insufficient.
 109          * @exception    E_SYSTEM             An unknown operating system error has occurred.
 110          * @remarks     To set the text, use the SetText() method.
 111          * @see         SetText()
 112          */
 113         result Construct(void);
 114
 115         /**
 116          * Initializes the current instance of %TextElement to represent a linked text with the specified link information. @n
 117          * If the link information is not specified, the default system font is set.
 118          *
 119          * @since     2.0
 120          *
 121          * @return    An error code
 122          * @param[in] text             The linked text string
 123          * @param[in] linkType         The link type
 124          * @param[in] link             The string that contains the actual link
 125          * @exception E_SUCCESS        The method is successful.
 126          * @exception E_OUT_OF_MEMORY  The memory is insufficient.
 127          * @exception E_INVALID_ARG    A specified input parameter is invalid.
 128          * @exception E_SYSTEM         An unknown operating system error has occurred.
 129          * @remarks   If the specified @c text is an empty string or
 130          *            @c linkType is LINK_TYPE_NONE, the method returns E_INVALID_ARG.
 131          * @see       Tizen::Base::Utility::LinkInfo
 132          */
 133         result Construct(const Tizen::Base::String& text, Tizen::Base::Utility::LinkType linkType, const Tizen::Base::String& link);
 134
 135         /**
 136          * Initializes the current instance of %TextElement with the specified text and autolink mask. @n
 137          * If the text and autolink mask are not specified, the default system font is set.
 138          *
 139          * @since     2.0
 140          *
 141          * @return    An error code
 142          * @param[in] text             The text string
 143          * @param[in] autoLink         The autolink mask @n
 144          *                             Multiple link types can be combined using the bitwise OR operator (Tizen::Base::Utility::LinkType). @n
 145          *                             For more information, see <a href="../org.tizen.native.appprogramming/html/guide/ui/auto_link_detection.htm">AutoLink Detection</a>.
 146          * @exception E_SUCCESS        The method is successful.
 147          * @exception E_INVALID_ARG    A specified input parameter is invalid.
 148          * @exception E_OUT_OF_MEMORY  The memory is insufficient.
 149          * @exception E_SYSTEM         An unknown operating system error has occurred.
 150          * @remarks   If @c text contains more than one detectable link, the first link is converted
 151          *            to a linked text and the rest of the links are ignored.
 152          * @see       Tizen::Base::Utility::LinkType
 153          */
 154         result Construct(const Tizen::Base::String& text, unsigned long autoLink);
 155
 156         /**
 157          * Initializes the current instance of %TextElement to represent a linked text with the specified link information. @n
 158          * If the link information is not specified, the default system font is set.
 159          *
 160          * @since     2.0.
 161          *
 162          * @return    An error code
 163          * @param[in] text             The linked text string
 164          * @param[in] linkType         The link type
 165          * @param[in] link             The string that contains the actual link
 166          * @param[in] canvas           The canvas to initialize the text element @n
 167          *                             It sets the foreground and background colors of the text element.
 168          * @exception E_SUCCESS        The method is successful.
 169          * @exception E_OUT_OF_MEMORY  The memory is insufficient.
 170          * @exception E_INVALID_ARG    A specified input parameter is invalid.
 171          * @exception E_SYSTEM         An unknown operating system error has occurred.
 172          * @remarks   If the specified @c text is an empty string or
 173          *            @c linkType is LINK_TYPE_NONE, the method returns E_INVALID_ARG.
 174          * @see       Tizen::Base::Utility::LinkType
 175          */
 176         result Construct(const Tizen::Base::String& text, Tizen::Base::Utility::LinkType linkType, const Tizen::Base::String& link, const Tizen::Graphics::Canvas& canvas);
 177
 178         /**
 179          * Initializes the current instance of %TextElement with the specified text, autolink mask, and graphics canvas. @n
 180          * If the parameters are not specified, the default system font is set.
 181          *
 182          * @since     2.0
 183          *
 184          * @return    An error code
 185          * @param[in] text             The text string
 186          * @param[in] autoLink         The autolink mask @n
 187          *                             Multiple link types can be combined using the bitwise OR operator (Tizen::Base::Utility::LinkType). @n
 188          *                             For more information, see <a href="../org.tizen.native.appprogramming/html/guide/ui/auto_link_detection.htm">AutoLink Detection</a>.
 189          * @param[in] canvas           The canvas to initialize the text element @n
 190          *                             It sets the foreground and background colors of the text element.
 191          * @exception E_SUCCESS        The method is successful.
 192          * @exception E_INVALID_ARG    A specified input parameter is invalid.
 193          * @exception E_OUT_OF_MEMORY  The memory is insufficient.
 194          * @exception E_SYSTEM         An unknown operating system error has occurred.
 195          * @remarks   If @c text contains more than one detectable link, the first link is converted
 196          *            to a linked text and rest of the links are ignored.
 197          * @see       Tizen::Base::Utility::LinkType
 198          */
 199         result Construct(const Tizen::Base::String& text, unsigned long autoLink, const Tizen::Graphics::Canvas& canvas);
 200
 201         /**
 202          * Gets the string that contains the actual link.
 203          *
 204          * @since      2.0
 205          *
 206          * @return     The string that contains the actual link
 207          * @remarks    If the text element contains no linked text, the method returns an empty string.
 208          */
 209         Tizen::Base::String GetLink(void) const;
 210
 211         /**
 212          * Gets the type of the link of the text element.
 213          *
 214          * @since      2.0
 215          *
 216          * @return     The string that contains the actual link
 217          * @remarks    If the text element contains no linked text, the method returns LINK_TYPE_NONE. @n
 218          *             The link type of the first auto-detected link is returned.
 219          */
 220         Tizen::Base::Utility::LinkType GetLinkType(void) const;
 221
 222         /**
 223          * Sets the text of %TextElement with the specified string.
 224          *
 225          * @since       2.0
 226          *
 227          * @return      An error code
 228          * @param[in]   text            The string to set
 229          * @exception   E_SUCCESS       The method is successful.
 230          */
 231         result SetText(const Tizen::Base::String& text);
 232
 233         /**
 234          * Sets the font of %TextElement.
 235          *
 236          * @since       2.0
 237          *
 238          * @return      An error code
 239          * @param[in]   font                The font to set
 240          * @exception   E_SUCCESS           The method is successful.
 241          * @exception   E_INVALID_ARG       The specified input parameter is invalid.
 242          */
 243         result SetFont(const Tizen::Graphics::Font& font);
 244
 245         /**
 246          * Sets the text color of %TextElement.
 247          *
 248          * @since       2.0
 249          *
 250          * @return      An error code
 251          * @param[in]   color               The color to set
 252          * @exception   E_SUCCESS           The method is successful.
 253          */
 254         result SetTextColor(const Tizen::Graphics::Color& color);
 255
 256         /**
 257          * Sets the background color of %TextElement.
 258          *
 259          * @since       2.0
 260          *
 261          * @return      An error code
 262          * @param[in]   color               The color to set
 263          * @exception   E_SUCCESS           The method is successful.
 264          */
 265         result SetBackgroundColor(const Tizen::Graphics::Color& color);
 266
 267         /**
 268          * Sets the outline color of %TextElement.
 269          *
 270          * @since       2.0
 271          *
 272          * @return              An error code
 273          * @param[in]   color   The color to set
 274          * @exception   E_SUCCESS           The method is successful.
 275          */
 276         result SetOutlineColor(const Tizen::Graphics::Color& color);
 277
 278         /**
 279          * Gets the text of %TextElement.
 280          *
 281          * @since       2.0
 282          *
 283          * @return      A string containing the text
 284          */
 285         Tizen::Base::String GetText(void) const;
 286
 287         /**
 288          * Gets the text color of %TextElement.
 289          *
 290          * @since       2.0
 291          *
 292          * @return The foreground color
 293          */
 294         Tizen::Graphics::Color GetTextColor(void) const;
 295
 296         /**
 297          * Gets the background color of %TextElement.
 298          *
 299          * @since       2.0
 300          *
 301          * @return The background color
 302          */
 303         Tizen::Graphics::Color GetBackgroundColor(void) const;
 304
 305         /**
 306          * Gets the outline color of %TextElement.
 307          *
 308          * @since       2.0
 309          *
 310          * @return The outline color
 311          */
 312         Tizen::Graphics::Color GetOutlineColor(void) const;
 313
 314 private:
 315         friend class _TextElementImpl;
 316
 317         //
 318         // This value is for internal use only. Using this value can cause behavioral, security-related,
 319         // and consistency-related issues in the application.
 320         //
 321         class _TextElementImpl * __pImpl;
 322
 323         //
 324         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 325         //
 326         TextElement(const TextElement& font);
 327
 328         //
 329         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 330         //
 331         TextElement& operator =(const TextElement& rhs);
 332
 333 }; // TextElement
 334
 335 }} // Tizen::Graphics
 336
 337 #endif  // _FGRP_TEXT_ELEMENT_H_