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.
20 * @brief This is the header file for the %Font class.
22 * This header file contains the declarations of the %Font class.
29 #include <FBaseObject.h>
30 #include <FGrpDimension.h>
31 #include <FGrpFloatDimension.h>
32 #include <FGrpFontCommon.h>
34 namespace Tizen { namespace Graphics
38 * @brief This class provides methods to retrieve the font information.
42 * @final This class is not intended for extension.
44 * The %Font class encapsulates the characteristics, such as the size and style of a specific vector font.
45 * Fonts are used to draw text on a Canvas.
47 * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/graphics/fonts.htm">Fonts</a>.
51 class _OSP_EXPORT_ Font
52 : public Tizen::Base::Object
56 * This is the default constructor for this class.
60 * @remarks After creating an instance of this class, one of the
61 * Construct() methods must be called explicitly to initialize this instance.
66 * This is the destructor for this class.
73 * Initializes this instance of %Font with the specified size and style. @n
74 * If the size and style are not specified, the default system font is set.
78 * @return An error code
79 * @param[in] style The font style @n
80 * For more information, see Tizen::Graphics::FontStyle.
81 * @param[in] size The font size in pixels @n
82 * The size must be greater than @c 0.
83 * @exception E_SUCCESS The method is successful.
84 * @exception E_INVALID_ARG A specified input parameter is invalid.
86 result Construct(int style, int size);
89 * Initializes this instance of %Font with the specified parameters.
92 * @brief <i> [Compatibility] </i>
96 * @compatibility This method has compatibility issues with OSP compatible applications. @n
97 * For more information, see @ref CompIoPathPage "IoPath" and @ref CompFontConstructPage "FontConstructor" issues.
99 * @return An error code
100 * @param[in] fontNameOrPath The local file path of a font-resource file or app font name or system font name @n
101 * The app font name is retrieved using GetFaceName(Tizen::Base::String& filepath).
102 * The system font name is retrieved using GetSystemFontListN().
103 * @param[in] style The font style @n
104 * Multiple styles can be combined using the bitwise OR operator.
105 * @param[in] size The font size in pixels @n
106 * The size must be greater than @c 0.
107 * @exception E_SUCCESS The method is successful.
108 * @exception E_INVALID_ARG A specified input parameter is invalid.
109 * @exception E_FILE_NOT_FOUND The specified font cannot be found or accessed.
110 * @exception E_UNSUPPORTED_FORMAT The specified font format is not supported.
111 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
112 * @remarks Only TrueType font is supported.
113 * The value of fontNameOrPath is considered system font name if it matches one of the retrieved values using GetSystemFontListN().
114 * If not, it is considered local file path of a font-resource file.
116 result Construct(const Tizen::Base::String& fontNameOrPath, int style, int size);
120 * @page CompFontConstructPage Compatibility for Construct().
121 * @section CompFontConstructPageIssueSection Issues
122 * Implementing this method in OSP compatible applications has the following issues: @n
123 * -# In OSP, the value of 1 st parameter(fontNameOrPath) can be system font name or local font path. At first, it is compared to the retrieved values using GetSystemFontListN(). If the matched value is exist, it is considered system font name. Or, it is considered local file path of a font-resource file.
124 * -# In Tizen, the value of 1 st parameter(fontNameOrPath) can be app font name or system font name or local font path. At first, it is compared to the font face names in app font resource folder. If the matched value is exist, it is considered app font name. Or, it is considered system font name if it matches one of the retrieved values using GetSystemFontListN().
129 * Initializes this instance of %Font with the specified parameters.
133 * @return An error code
134 * @param[in] fontData The font data
135 * @param[in] style The font style @n
136 * Multiple styles can be combined using the bitwise OR operator.
137 * @param[in] size The font size in pixels @n
138 * The size must be greater than @c 0.
139 * @exception E_SUCCESS The method is successful.
140 * @exception E_INVALID_ARG A specified input parameter is invalid.
141 * @exception E_UNSUPPORTED_FORMAT The specified font format is not supported.
142 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
144 result Construct(const Tizen::Base::ByteBuffer& fontData, int style, int size);
147 * Initializes this instance of %Font with the specified size and style. @n
148 * If the size and style are not specified, the default system font is set.
152 * @return An error code
153 * @param[in] style The font style @n
154 * For more information, see Tizen::Graphics::FontStyle.
155 * @param[in] size The font size in pixels @n
156 * The size must be greater than @c 0.0f.
157 * @exception E_SUCCESS The method is successful.
158 * @exception E_INVALID_ARG A specified input parameter is invalid.
160 result Construct(int style, float size);
163 * Initializes this instance of %Font with the specified parameters.
167 * @return An error code
168 * @param[in] fontNameOrPath The local file path of a font-resource file or system font name @n
169 * The system font name is retrieved using GetSystemFontListN().
170 * @param[in] style The font style @n
171 * Multiple styles can be combined using the bitwise OR operator.
172 * @param[in] size The font size in pixels @n
173 * The size must be greater than @c 0.0f.
174 * @exception E_SUCCESS The method is successful.
175 * @exception E_INVALID_ARG A specified input parameter is invalid.
176 * @exception E_FILE_NOT_FOUND The specified font cannot be found or accessed.
177 * @exception E_UNSUPPORTED_FORMAT The specified font format is not supported.
178 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
179 * @remarks Only TrueType font is supported.
180 * The value of fontNameOrPath is considered system font name if it matches one of the retrieved values using GetSystemFontListN().
181 * If not, it is considered local file path of a font-resource file.
183 result Construct(const Tizen::Base::String& fontNameOrPath, int style, float size);
186 * Initializes this instance of %Font with the specified parameters.
190 * @return An error code
191 * @param[in] fontData The font data
192 * @param[in] style The font style @n
193 * Multiple styles can be combined using the bitwise OR operator.
194 * @param[in] size The font size in pixels @n
195 * The size must be greater than @c 0.0f.
196 * @exception E_SUCCESS The method is successful.
197 * @exception E_INVALID_ARG A specified input parameter is invalid.
198 * @exception E_UNSUPPORTED_FORMAT The specified font format is not supported.
199 * @exception E_INVALID_OPERATION The current state of the instance prohibits the execution of the specified operation.
201 result Construct(const Tizen::Base::ByteBuffer& fontData, int style, float size);
204 * Gets the maximum height of the current instance of %Font.
208 * @return The maximum height of the current instance of %Font, @n
209 * else @c -1 if the method fails
211 int GetMaxHeight(void) const;
214 * Gets the maximum height of the current instance of %Font.
218 * @return The maximum height of the current instance of %Font, @n
219 * else @c -1.0f if the method fails
221 float GetMaxHeightF(void) const;
224 * Gets the maximum width of the current instance of %Font.
228 * @return The maximum width of the current instance of %Font, @n
229 * else @c -1 if the method fails
231 int GetMaxWidth(void) const;
234 * Gets the maximum width of the current instance of %Font.
238 * @return The maximum width of the current instance of %Font, @n
239 * else @c -1.0f if the method fails
241 float GetMaxWidthF(void) const;
244 * Gets the ascender of the current instance of %Font.
248 * @return The ascender of the current instance of %Font, @n
249 * else @c -1 if the method fails
251 int GetAscender(void) const;
254 * Gets the ascender of the current instance of %Font.
258 * @return The ascender of the current instance of %Font, @n
259 * else @c -1.0f if the method fails
261 float GetAscenderF(void) const;
264 * Gets the descender of the current instance of %Font.
268 * @return The descender of the current instance of %Font, @n
269 * else @c -1 if the method fails
271 int GetDescender(void) const;
274 * Gets the descender of the current instance of %Font.
278 * @return The descender of the current instance of %Font, @n
279 * else @c -1.0f if the method fails
281 float GetDescenderF(void) const;
284 * Gets the left bear of a character.
288 * @return An error code
289 * @param[in] character A character for getting left bear
290 * @param[out] leftBear The left bear of the specified @c character
291 * @exception E_SUCCESS The method is successful.
292 * @exception E_DATA_NOT_FOUND The requested data does not exist.
294 result GetLeftBear(wchar_t character, int& leftBear) const;
297 * Gets the left bear of a character.
301 * @return An error code
302 * @param[in] character A character for getting left bear
303 * @param[out] leftBear The left bear of the specified @c character
304 * @exception E_SUCCESS The method is successful.
305 * @exception E_DATA_NOT_FOUND The requested data does not exist.
307 result GetLeftBear(wchar_t character, float& leftBear) const;
310 * Gets the right bear of a character.
314 * @return An error code
315 * @param[in] character A character for getting the right bear
316 * @param[out] rightBear The right bear of the specified @c character
317 * @exception E_SUCCESS The method is successful.
318 * @exception E_DATA_NOT_FOUND The requested data does not exist.
320 result GetRightBear(wchar_t character, int& rightBear) const;
323 * Gets the right bear of a character.
327 * @return An error code
328 * @param[in] character A character for getting the right bear
329 * @param[out] rightBear The right bear of the specified @c character
330 * @exception E_SUCCESS The method is successful.
331 * @exception E_DATA_NOT_FOUND The requested data does not exist.
333 result GetRightBear(wchar_t character, float& rightBear) const;
336 * Gets the width and height of the font used in the specified text. @n
337 * This method retrieves the font dimension of the text.
340 * @brief <i> [Compatibility] </i>
344 * @compatibility This method has compatibility issues with OSP compatible applications. @n
345 * For more information, see the issue description for @ref CompFontGetTextExtentPage "here".
348 * @return An error code
349 * @param[in] text The string
350 * @param[in] length The length of @c text @n
351 * The length must be greater than or equal to @c 0.
352 * @param[out] dim The width and height of the font of the @c text
353 * @exception E_SUCCESS The method is successful.
354 * @exception E_OUT_OF_RANGE The value of @c length is greater than the actual length of @c text.
356 result GetTextExtent(const Tizen::Base::String& text, int length, Dimension& dim) const;
360 * @page CompFontGetTextExtentPage Compatibility for the file path.
361 * @section CompFontGetTextExtentPageIssueSection Issues
362 * Implementing this method in OSP compatible applications has the following issues: @n
363 * -# The method returns exact height only if the font resource is designed to fit inside the emBox. @n
365 * @section CompFontGetTextExtentPageSolutionSection Resolutions
366 * This issue has been resolved in Tizen. @n
367 * -# The method returns exact height regardless of font design. @n
373 * Gets the width and height of the font used in the specified text. @n
374 * This method retrieves the font dimension of the text.
378 * @return An error code
379 * @param[in] text The string
380 * @param[in] length The length of @c text @n
381 * The length must be greater than or equal to @c 0.0f.
382 * @param[out] dim The width and height of the font of the @c text
383 * @exception E_SUCCESS The method is successful.
384 * @exception E_OUT_OF_RANGE The value of @c length is greater than the actual length of @c text.
386 result GetTextExtent(const Tizen::Base::String& text, int length, FloatDimension& dim) const;
389 * Checks whether the font style of the current instance is bold.
393 * @return @c true if the font style of the current instance is bold, @n
396 bool IsBold(void) const;
399 * Checks whether the font style for the current instance is italics.
403 * @return @c true if the font style for the current instance is italics, @n
406 bool IsItalic(void) const;
409 * Checks whether the current instance has any style defined.
413 * @return @c true if an extra style is not defined for the current instance, @n
416 bool IsPlain(void) const;
419 * Checks whether the current instance has the strikeout style set.
423 * @return @c true if the current instance has the strikeout style set, @n
426 bool IsStrikeOut(void) const;
429 * Checks whether the current instance has the underline style set.
433 * @return @c true if the current instance has the underline style set, @n
436 bool IsUnderlined(void) const;
439 * Gets the font size of the current instance of %Font.
443 * @return The font size, @n
444 * else @c -1 if the method fails
446 int GetSize(void) const;
449 * Gets the font size of the current instance of %Font.
453 * @return The font size, @n
454 * else @c -1.0f if the method fails
456 float GetSizeF(void) const;
459 * Sets the strikeout style for the current instance of %Font.
463 * @param[in] strikeOut Set to @c true to use the strikeout style for the current instance of %Font, @n
466 void SetStrikeOut(bool strikeOut);
469 * Sets the underline style for the current instance of %Font.
473 * @param[in] underline Set to @c true to use the underline style for the current instance of %Font, @n
476 void SetUnderline(bool underline);
479 * Gets the system font list.
483 * @return The list of system fonts @n
484 * The font list consists of Tizen::Base::String items.
485 * @remarks After using the system font list, you can call IList::RemoveAll(true) to clean up string items in the list.
487 static Tizen::Base::Collection::IList* GetSystemFontListN(void);
490 * Gets the face name of the font file of the specific path.
494 * @return The face name of the font file of the specific path
495 * @param[in] filePath The path of the font file
497 static Tizen::Base::String GetFaceName(const Tizen::Base::String& filePath);
500 * Sets the character space.
504 * @param[in] space A character space
506 void SetCharSpace(int space);
509 * Sets the character space.
513 * @param[in] space A character space
515 void SetCharSpace(float space);
518 * Gets the character space.
522 * @return The character space of this font instance, @n
523 * else @c -1 if the method fails
525 int GetCharSpace(void) const;
528 * Gets the character space.
532 * @return The character space of this font instance, @n
533 * else @c -1.0f if the method fails
535 float GetCharSpaceF(void) const;
538 * Gets the face name.
542 * @return The face name of this font instance
544 Tizen::Base::String GetFaceName(void) const;
547 friend class _FontImpl;
550 // This variable is for internal use only.
551 // Using this variable can cause behavioral, security-related, and consistency-related issues in the application.
555 class _FontImpl* __pImpl;
558 // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
560 Font(const Font& rhs);
563 // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
565 Font& operator =(const Font& rhs);
569 }} // Tizen::Graphics
571 #endif //_FGRP_FONT_H_