inc/FGrpTextElement.h

   1 //
   2 //
   3 // Open Service Platform
   4 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   5 //
   6 // Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0/
  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         */
 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    Either the specified @c text is an empty string or @c linkType is @c LINK_TYPE_NONE
 128         * @exception E_SYSTEM         An unknown operating system error has occurred.
 129         * @see       Tizen::Base::Utility::LinkInfo
 130         */
 131         result Construct(const Tizen::Base::String& text, Tizen::Base::Utility::LinkType linkType, const Tizen::Base::String& link);
 132
 133         /**
 134         * Initializes the current instance of %TextElement with the specified text and autolink mask. @n
 135         * If the text and autolink mask are not specified, the default system font is set.
 136         *
 137         * @since     2.0
 138         *
 139         * @return    An error code
 140         * @param[in] text             The text string
 141         * @param[in] autoLink         The autolink mask @n
 142         *                             Multiple link types can be combined using the bitwise OR operator. @n
 143         *                             For more information, see <a href="../org.tizen.native.appprogramming/html/guide/ui/auto_link_detection.htm">AutoLink Detection</a>.
 144         * @exception E_SUCCESS        The method is successful.
 145         * @exception E_INVALID_ARG    A specified input parameter is invalid.
 146         * @exception E_OUT_OF_MEMORY  The memory is insufficient.
 147         * @exception E_SYSTEM         An unknown operating system error has occurred.
 148         * @remarks   If @c text contains more than one detectable link, the first link is converted
 149         *            to a linked text and the rest of the links are ignored.
 150         * @see       Tizen::Base::Utility::LinkType
 151         */
 152         result Construct(const Tizen::Base::String& text, unsigned long autoLink);
 153
 154         /**
 155         * Initializes the current instance of %TextElement to represent a linked text with the specified link information. @n
 156         * If the link information is not specified, the default system font is set.
 157         *
 158         * @since     2.0.
 159         *
 160         * @return    An error code
 161         * @param[in] text             The linked text string
 162         * @param[in] linkType         The link type
 163         * @param[in] link             The string that contains the actual link
 164         * @param[in] canvas           The canvas to initialize the text element @n
 165         *                             It sets the foreground and background colors of the text element.
 166         * @exception E_SUCCESS        The method is successful.
 167         * @exception E_OUT_OF_MEMORY  The memory is insufficient.
 168         * @exception E_INVALID_ARG    Either the specified @c text is an empty string or @c linkType is @c LINK_TYPE_NONE.
 169         * @exception E_SYSTEM         An unknown operating system error has occurred.
 170         */
 171         result Construct(const Tizen::Base::String& text, Tizen::Base::Utility::LinkType linkType, const Tizen::Base::String& link, const Tizen::Graphics::Canvas& canvas);
 172
 173         /**
 174         * Initializes the current instance of %TextElement with the specified text, autolink mask, and graphics canvas. @n
 175         * If the parameters are not specified, the default system font is set.
 176         *
 177         * @since     2.0
 178         *
 179         * @return    An error code
 180         * @param[in] text             The text string @n
 181         *                                       If the text contains more than one detectable link, the first link is converted to a linked text and rest of the links are ignored.
 182         * @param[in] autoLink         The autolink mask @n
 183         *                             Multiple link types can be combined using the bitwise OR operator. @n
 184         *                             For more information, see <a href="../org.tizen.native.appprogramming/html/guide/ui/auto_link_detection.htm">AutoLink Detection</a>.
 185         * @param[in] canvas           The canvas to initialize the text element @n
 186         *                             It sets the foreground and background colors of the text element.
 187         * @exception E_SUCCESS        The method is successful.
 188         * @exception E_INVALID_ARG    A specified input parameter is invalid.
 189         * @exception E_OUT_OF_MEMORY  The memory is insufficient.
 190         * @exception E_SYSTEM         An unknown operating system error has occurred.
 191         * @see       Tizen::Base::Utility::LinkType
 192         */
 193         result Construct(const Tizen::Base::String& text, unsigned long autoLink, const Tizen::Graphics::Canvas& canvas);
 194
 195         /**
 196         * Gets the string that contains the actual link.
 197         *
 198         * @since                2.0
 199         *
 200         * @return               The string that contains the actual link @n
 201         *                       If the text element contains no linked text, the method returns an empty string.
 202         */
 203         Tizen::Base::String GetLink(void) const;
 204
 205         /**
 206         * Gets the type of the link of the text element. @n
 207         * The link type is the first auto-detected link.
 208         *
 209         * @since                2.0
 210         *
 211         * @return               The string that contains the actual link @n
 212         *                       If the text element contains no linked text, the method returns @c LINK_TYPE_NONE.
 213         */
 214         Tizen::Base::Utility::LinkType GetLinkType(void) const;
 215
 216         /**
 217         * Sets the text of %TextElement with the specified string.
 218         *
 219         * @since       2.0
 220         *
 221         * @return      An error code
 222         * @param[in]   text            The string to set
 223         * @exception   E_SUCCESS       The method is successful.
 224         */
 225         result SetText(const Tizen::Base::String& text);
 226
 227         /**
 228         * Sets the font of %TextElement.
 229         *
 230         * @since       2.0
 231         *
 232         * @return      An error code
 233         * @param[in]   font                The font to set
 234         * @exception   E_SUCCESS           The method is successful.
 235         * @exception   E_INVALID_ARG       The specified input parameter is invalid.
 236         */
 237         result SetFont(const Tizen::Graphics::Font& font);
 238
 239         /**
 240         * Sets the text color of %TextElement.
 241         *
 242         * @since       2.0
 243         *
 244         * @return      An error code
 245         * @param[in]   color               The color to set
 246         * @exception   E_SUCCESS           The method is successful.
 247         */
 248         result SetTextColor(const Tizen::Graphics::Color& color);
 249
 250         /**
 251         * Sets the background color of %TextElement.
 252         *
 253         * @since       2.0
 254         *
 255         * @return      An error code
 256         * @param[in]   color               The color to set
 257         * @exception   E_SUCCESS           The method is successful.
 258          */
 259         result SetBackgroundColor(const Tizen::Graphics::Color& color);
 260
 261         /**
 262         * Sets the outline color of %TextElement.
 263         *
 264         * @since       2.0
 265         *
 266         * @return              An error code
 267         * @param[in]   color   The color to set
 268         * @exception   E_SUCCESS           The method is successful.
 269         */
 270         result SetOutlineColor(const Tizen::Graphics::Color& color);
 271
 272         /**
 273         * Gets the text of %TextElement.
 274         *
 275         * @since       2.0
 276         *
 277         * @return      A string containing the text
 278         */
 279         Tizen::Base::String GetText(void) const;
 280
 281         /**
 282         * Gets the text color of %TextElement.
 283         *
 284         * @since       2.0
 285         *
 286         * @return The foreground color
 287         */
 288         Tizen::Graphics::Color GetTextColor(void) const;
 289
 290         /**
 291         * Gets the background color of %TextElement.
 292         *
 293         * @since       2.0
 294         *
 295         * @return The background color
 296         */
 297         Tizen::Graphics::Color GetBackgroundColor(void) const;
 298
 299         /**
 300         * Gets the outline color of %TextElement.
 301         *
 302         * @since       2.0
 303         *
 304         * @return The outline color
 305         */
 306         Tizen::Graphics::Color GetOutlineColor(void) const;
 307
 308 private:
 309         friend class _TextElementImpl;
 310
 311         //
 312         // This value is for internal use only. Using this value can cause behavioral, security-related,
 313         // and consistency-related issues in the application.
 314         //
 315         /**
 316          * @since 2.0
 317          */
 318         class _TextElementImpl * __pImpl;
 319
 320         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 321         TextElement(const TextElement& font);
 322
 323         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 324         TextElement& operator =(const TextElement& rhs);
 325
 326 }; // TextElement
 327
 328 } } // Tizen::Graphics
 329
 330 #endif  // _FGRP_TEXT_ELEMENT_H_