inc/FGrpTextElement.h

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