2 // Open Service Platform
3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
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
9 // http://floralicense.org/license/
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.
19 * @file FGrpTextElement.h
20 * @brief This is the header file for the %TextElement class.
22 * This header file contains the declarations of the %TextElement class.
25 #ifndef _FGRP_TEXT_ELEMENT_H_
26 #define _FGRP_TEXT_ELEMENT_H_
29 #include <FBaseUtilTypes.h>
31 #include <FGrpCanvas.h>
32 #include <FGrpColor.h>
34 namespace Tizen { namespace Graphics
38 * @brief This class provides methods for the text elements.
42 * @final This class is not intended for extension.
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.
47 * For more information on the attributes of %TextElement, see <a href="../org.tizen.native.appprogramming/html/guide/graphics/enriched_text.htm">EnrichedText</a>.
50 class _OSP_EXPORT_ TextElement
51 : public Tizen::Base::Object
55 * This is the default constructor for this class.
59 * @remarks After creating an instance of this class, one of the
60 * Construct() methods must be called explicitly to initialize this instance.
65 * This is the destructor for this class.
69 virtual ~TextElement(void);
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.
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.
83 result Construct(const Tizen::Base::String& text);
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.
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.
99 result Construct(const Tizen::Base::String& text, const Tizen::Graphics::Canvas& canvas);
102 * Initializes the current instance of %TextElement.
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.
113 result Construct(void);
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.
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
133 result Construct(const Tizen::Base::String& text, Tizen::Base::Utility::LinkType linkType, const Tizen::Base::String& link);
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.
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
154 result Construct(const Tizen::Base::String& text, unsigned long autoLink);
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.
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
176 result Construct(const Tizen::Base::String& text, Tizen::Base::Utility::LinkType linkType, const Tizen::Base::String& link, const Tizen::Graphics::Canvas& canvas);
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.
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
199 result Construct(const Tizen::Base::String& text, unsigned long autoLink, const Tizen::Graphics::Canvas& canvas);
202 * Gets the string that contains the actual link.
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.
209 Tizen::Base::String GetLink(void) const;
212 * Gets the type of the link of the text element.
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.
220 Tizen::Base::Utility::LinkType GetLinkType(void) const;
223 * Sets the text of %TextElement with the specified string.
227 * @return An error code
228 * @param[in] text The string to set
229 * @exception E_SUCCESS The method is successful.
231 result SetText(const Tizen::Base::String& text);
234 * Sets the font of %TextElement.
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.
243 result SetFont(const Tizen::Graphics::Font& font);
246 * Sets the text color of %TextElement.
250 * @return An error code
251 * @param[in] color The color to set
252 * @exception E_SUCCESS The method is successful.
254 result SetTextColor(const Tizen::Graphics::Color& color);
257 * Sets the background color of %TextElement.
261 * @return An error code
262 * @param[in] color The color to set
263 * @exception E_SUCCESS The method is successful.
265 result SetBackgroundColor(const Tizen::Graphics::Color& color);
268 * Sets the outline color of %TextElement.
272 * @return An error code
273 * @param[in] color The color to set
274 * @exception E_SUCCESS The method is successful.
276 result SetOutlineColor(const Tizen::Graphics::Color& color);
279 * Gets the text of %TextElement.
283 * @return A string containing the text
285 Tizen::Base::String GetText(void) const;
288 * Gets the text color of %TextElement.
292 * @return The foreground color
294 Tizen::Graphics::Color GetTextColor(void) const;
297 * Gets the background color of %TextElement.
301 * @return The background color
303 Tizen::Graphics::Color GetBackgroundColor(void) const;
306 * Gets the outline color of %TextElement.
310 * @return The outline color
312 Tizen::Graphics::Color GetOutlineColor(void) const;
315 friend class _TextElementImpl;
318 // This value is for internal use only. Using this value can cause behavioral, security-related,
319 // and consistency-related issues in the application.
321 class _TextElementImpl * __pImpl;
324 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
326 TextElement(const TextElement& font);
329 // 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);
335 }} // Tizen::Graphics
337 #endif // _FGRP_TEXT_ELEMENT_H_