inc/FGrpFont.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   5 // Licensed under the Apache License, Version 2.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://www.apache.org/licenses/LICENSE-2.0/
  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        FGrpFont.h
  20  * @brief       This is the header file for the %Font class.
  21  *
  22  * This header file contains the declarations of the %Font class.
  23  */
  24
  25 #ifndef _FGRP_FONT_H_
  26 #define _FGRP_FONT_H_
  27
  28 #include <FBase.h>
  29 #include <FBaseObject.h>
  30 #include <FGrpDimension.h>
  31 #include <FGrpFloatDimension.h>
  32 #include <FGrpFontCommon.h>
  33
  34 namespace Tizen { namespace Graphics
  35 {
  36 /**
  37  * @class       Font
  38  * @brief       This class provides methods to retrieve the font information.
  39  *
  40  * @since       2.0
  41  *
  42  * @final       This class is not intended for extension.
  43  *
  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.
  46  *
  47  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/graphics/fonts.htm">Fonts</a>.
  48  *
  49  *
  50  */
  51 class _OSP_EXPORT_ Font
  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         Font(void);
  64
  65         /**
  66          * This is the destructor for this class.
  67          *
  68          * @since       2.0
  69          */
  70         virtual ~Font(void);
  71
  72         /**
  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.
  75          *
  76          * @since               2.0
  77          *
  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.
  85          */
  86         result Construct(int style, int size);
  87
  88         /**
  89          * Initializes this instance of %Font with the specified parameters.
  90          *
  91          * @if OSPCOMPAT
  92          * @brief <i> [Compatibility] </i>
  93          * @endif
  94          * @since               2.0
  95          * @if OSPCOMPAT
  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.
  98          * @endif
  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.
 115          */
 116         result Construct(const Tizen::Base::String& fontNameOrPath, int style, int size);
 117
 118         /**
 119          * @if OSPCOMPAT
 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().
 125          * @endif
 126          */
 127
 128         /**
 129          * Initializes this instance of %Font with the specified parameters.
 130          *
 131          * @since               2.0
 132          *
 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.
 143          */
 144         result Construct(const Tizen::Base::ByteBuffer& fontData, int style, int size);
 145
 146         /**
 147          * Initializes this instance of %Font with a specified size and style. @n
 148          * If the size and style are not specified, the default system font is set.
 149          *
 150          * @since               2.1
 151          *
 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.
 157          * @exception   E_SUCCESS                       The method is successful.
 158          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
 159          */
 160         result Construct(int style, float size);
 161
 162         /**
 163          * Initializes this instance of %Font with the specified parameters.
 164          *
 165          * @since               2.1
 166          *
 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.
 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 @c fontNameOrPath is considered as the default system font name if it matches to any one of the values that is retrieved using GetSystemFontListN().
 181          *          If not, it is considered as the local file path of a font-resource file.
 182          */
 183         result Construct(const Tizen::Base::String& fontNameOrPath, int style, float size);
 184
 185         /**
 186          * Initializes this instance of %Font with the specified parameters.
 187          *
 188          * @since               2.1
 189          *
 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.
 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.
 200          */
 201         result Construct(const Tizen::Base::ByteBuffer& fontData, int style, float size);
 202
 203         /**
 204          * Gets the maximum height of the current instance of %Font.
 205          *
 206          * @since       2.0
 207          *
 208          * @return      The maximum height of the current instance of %Font, @n
 209          *                      else @c -1 if the method fails
 210          */
 211         int GetMaxHeight(void) const;
 212
 213         /**
 214          * Gets the maximum height of the current instance of %Font.
 215          *
 216          * @since       2.1
 217          *
 218          * @return      The maximum height of the current instance of %Font, @n
 219          *                      else @c -1 if the method fails
 220          */
 221         float GetMaxHeightF(void) const;
 222
 223         /**
 224          * Gets the maximum width of the current instance of %Font.
 225          *
 226          * @since       2.0
 227          *
 228          * @return      The maximum width of the current instance of %Font, @n
 229          *                      else @c -1 if the method fails
 230          */
 231         int GetMaxWidth(void) const;
 232
 233         /**
 234          * Gets the maximum width of the current instance of %Font.
 235          *
 236          * @since       2.1
 237          *
 238          * @return      The maximum width of the current instance of %Font, @n
 239          *                      else @c -1 if the method fails
 240          */
 241         float GetMaxWidthF(void) const;
 242
 243         /**
 244          * Gets the ascender of the current instance of %Font.
 245          *
 246          * @since       2.0
 247          *
 248          * @return     The ascender of the current instance of %Font, @n
 249          *                      else @c -1 if the method fails
 250          */
 251         int GetAscender(void) const;
 252
 253         /**
 254          * Gets the ascender of the current instance of %Font.
 255          *
 256          * @since       2.1
 257          *
 258          * @return     The ascender of the current instance of %Font, @n
 259          *                      else @c -1 if the method fails
 260          */
 261         float GetAscenderF(void) const;
 262
 263         /**
 264          * Gets the descender of the current instance of %Font.
 265          *
 266          * @since       2.0
 267          *
 268          * @return     The descender of the current instance of %Font, @n
 269          *                      else @c -1 if the method fails
 270          */
 271         int GetDescender(void) const;
 272
 273         /**
 274          * Gets the descender of the current instance of %Font.
 275          *
 276          * @since       2.1
 277          *
 278          * @return     The descender of the current instance of %Font, @n
 279          *                      else @c -1 if the method fails
 280          */
 281         float GetDescenderF(void) const;
 282
 283         /**
 284          * Gets the left bear of a character.
 285          *
 286          * @since               2.0
 287          *
 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.
 293          */
 294         result GetLeftBear(wchar_t character, int& leftBear) const;
 295
 296         /**
 297          * Gets the left bear of a character.
 298          *
 299          * @since               2.1
 300          *
 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.
 306          */
 307         result GetLeftBear(wchar_t character, float& leftBear) const;
 308
 309         /**
 310          * Gets the right bear of a character.
 311          *
 312          * @since               2.0
 313          *
 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.
 319          */
 320         result GetRightBear(wchar_t character, int& rightBear) const;
 321
 322         /**
 323          * Gets the right bear of a character.
 324          *
 325          * @since               2.1
 326          *
 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.
 332          */
 333         result GetRightBear(wchar_t character, float& rightBear) const;
 334
 335         /**
 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.
 338          *
 339          * @if OSPCOMPAT
 340          * @brief <i> [Compatibility] </i>
 341          * @endif
 342          * @since               2.0
 343          * @if OSPCOMPAT
 344          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 345          *                       For more information, see the issue description for @ref CompFontGetTextExtentPage "here".
 346          * @endif
 347          *
 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.
 355          */
 356         result GetTextExtent(const Tizen::Base::String& text, int length, Dimension& dim) const;
 357
 358         /**
 359          * @if OSPCOMPAT
 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
 364          *
 365          * @section             CompFontGetTextExtentPageSolutionSection Resolutions
 366          *                              This issue has been resolved in Tizen. @n
 367          *                              -# The method returns exact height regardless of font design. @n
 368          *
 369          * @endif
 370          */
 371
 372         /**
 373          * Gets the width and height of the font used in a specified text. @n
 374          * The %GetTextExtent() method retrieves the font dimension of the text.
 375          *
 376          * @since               2.1
 377          *
 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.
 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.
 385          */
 386         result GetTextExtent(const Tizen::Base::String& text, int length, FloatDimension& dim) const;
 387
 388         /**
 389          * Checks whether the font style of the current instance is bold.
 390          *
 391          * @since               2.0
 392          *
 393          * @return              @c true if the font style of the current instance is bold, @n
 394          *                              else @c false
 395          */
 396         bool IsBold(void) const;
 397
 398         /**
 399          * Checks whether the font style for the current instance is italics.
 400          *
 401          * @since               2.0
 402          *
 403          * @return              @c true if the font style for the current instance is italics, @n
 404          *                              else @c false
 405          */
 406         bool IsItalic(void) const;
 407
 408         /**
 409          * Checks whether the current instance has any style defined.
 410          *
 411          * @since               2.0
 412          *
 413          * @return              @c true if an extra style is not defined for the current instance, @n
 414          *                                      else @c false
 415          */
 416         bool IsPlain(void) const;
 417
 418         /**
 419          * Checks whether the current instance has the strikeout style set.
 420          *
 421          * @since               2.0
 422          *
 423          * @return              @c true if the current instance has the strikeout style set, @n
 424          *                              else @c false
 425          */
 426         bool IsStrikeOut(void) const;
 427
 428         /**
 429          * Checks whether the current instance has the underline style set.
 430          *
 431          * @since               2.0
 432          *
 433          * @return              @c true if the current instance has the underline style set, @n
 434          *                              else @c false
 435          */
 436         bool IsUnderlined(void) const;
 437
 438         /**
 439          * Gets the font size of the current instance of %Font.
 440          *
 441          * @since               2.0
 442          *
 443          * @return              The font size, @n
 444          *                              else @c -1 if the method fails
 445          */
 446         int GetSize(void) const;
 447
 448         /**
 449          * Gets the font size of the current instance of %Font.
 450          *
 451          * @since               2.1
 452          *
 453          * @return              The font size, @n
 454          *                              else @c -1 if the method fails
 455          */
 456         float GetSizeF(void) const;
 457
 458         /**
 459          * Sets the strikeout style for the current instance of %Font.
 460          *
 461          * @since               2.0
 462          *
 463          * @param[in]   strikeOut               Set to @c true to use the strikeout style for the current instance of %Font, @n
 464          *                                                              else @c false
 465          */
 466         void SetStrikeOut(bool strikeOut);
 467
 468         /**
 469          * Sets the underline style for the current instance of %Font.
 470          *
 471          * @since               2.0
 472          *
 473          * @param[in]   underline               Set to @c true to use the underline style for the current instance of %Font, @n
 474          *                                                              else @c false
 475          */
 476         void SetUnderline(bool underline);
 477
 478         /**
 479          * Gets the system font list.
 480          *
 481          * @since               2.0
 482          *
 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.
 486          */
 487         static Tizen::Base::Collection::IList* GetSystemFontListN(void);
 488
 489         /**
 490          * Gets the face name of the font file of the specific path.
 491          *
 492          * @since 2.0
 493          *
 494          * @return      The face name of the font file of the specific path
 495          * @param[in]   filePath                The path of the font file
 496          */
 497         static Tizen::Base::String GetFaceName(const Tizen::Base::String& filePath);
 498
 499         /**
 500          * Sets the character space.
 501          *
 502          * @since       2.0
 503          *
 504          * @param[in]          space    A character space
 505          */
 506         void SetCharSpace(int space);
 507
 508         /**
 509          * Sets the character space.
 510          *
 511          * @since       2.1
 512          *
 513          * @param[in]          space    A character space
 514          */
 515         void SetCharSpace(float space);
 516
 517         /**
 518          * Gets the character space.
 519          *
 520          * @since       2.0
 521          *
 522          * @return      The character space of this font instance, @n
 523          *                      else @c -1 if the method fails
 524          */
 525         int GetCharSpace(void) const;
 526
 527         /**
 528          * Gets the character space.
 529          *
 530          * @since       2.1
 531          *
 532          * @return      The character space of this font instance, @n
 533          *                      else @c -1 if the method fails
 534          */
 535         float GetCharSpaceF(void) const;
 536
 537         /**
 538          * Gets the face name.
 539          *
 540          * @since       2.0
 541          *
 542          * @return      The face name of this font instance
 543          */
 544         Tizen::Base::String GetFaceName(void) const;
 545
 546 private:
 547         friend class _FontImpl;
 548
 549         //
 550         // This variable is for internal use only.
 551         // Using this variable can cause behavioral, security-related, and consistency-related issues in the application.
 552         //
 553         // @since 2.0
 554         //
 555         class _FontImpl* __pImpl;
 556
 557         //
 558         // The implementation of this copy constructor is intentionally blank and declared as private to prohibit copying of objects.
 559         //
 560         Font(const Font& rhs);
 561
 562         //
 563         // The implementation of this copy assignment operator is intentionally blank and declared as private to prohibit copying of objects.
 564         //
 565         Font& operator =(const Font& rhs);
 566
 567 }; // Font
 568
 569 }} // Tizen::Graphics
 570
 571 #endif //_FGRP_FONT_H_