inc/FGrpFont.h

   1 //
   2 // Open Service Platform
   3 // Copyright (c) 2012-2013 Samsung Electronics Co., Ltd.
   4 //
   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
   8 //
   9 //     http://floralicense.org/license/
  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 <FGrpFontCommon.h>
  32
  33 namespace Tizen { namespace Graphics
  34 {
  35 /**
  36  * @class       Font
  37  * @brief       This class provides methods to retrieve the font information.
  38  *
  39  * @since       2.0
  40  *
  41  * @final       This class is not intended for extension.
  42  *
  43  * The %Font class encapsulates the characteristics, such as the size and style of a specific vector font.
  44  * Fonts are used to draw text on a Canvas.
  45  *
  46  * For more information on the class features, see <a href="../org.tizen.native.appprogramming/html/guide/graphics/fonts.htm">Fonts</a>.
  47  *
  48  *
  49  */
  50 class _OSP_EXPORT_ Font
  51         : public Tizen::Base::Object
  52 {
  53 public:
  54         /**
  55          * This is the default constructor for this class.
  56          *
  57          * @since               2.0
  58          *
  59          * @remarks             After creating an instance of this class, one of the
  60          *                                      Construct() methods must be called explicitly to initialize this instance.
  61          */
  62         Font(void);
  63
  64         /**
  65          * This is the destructor for this class.
  66          *
  67          * @since       2.0
  68          */
  69         virtual ~Font(void);
  70
  71         /**
  72          * Initializes this instance of %Font with the specified size and style. @n
  73          * If the size and style are not specified, the default system font is set.
  74          *
  75          * @since               2.0
  76          *
  77          * @return              An error code
  78          * @param[in]   style                   The font style @n
  79          *                                  For more information, see Tizen::Graphics::FontStyle.
  80          * @param[in]   size                            The font size in pixels @n
  81          *                                                                              The size must be greater than @c 0.
  82          * @exception   E_SUCCESS                       The method is successful.
  83          * @exception   E_INVALID_ARG           A specified input parameter is invalid.
  84          */
  85         result Construct(int style, int size);
  86
  87         /**
  88          * Initializes this instance of %Font with the specified parameters.
  89          *
  90          * @if OSPCOMPAT
  91          * @brief <i> [Compatibility] </i>
  92          * @endif
  93          * @since               2.0
  94          * @if OSPCOMPAT
  95          * @compatibility       This method has compatibility issues with OSP compatible applications. @n
  96          *                                      For more information, see @ref CompIoPathPage "IoPath" and @ref CompFontConstructPage "FontConstructor" issues.
  97          * @endif
  98          * @return              An error code
  99          * @param[in]   fontNameOrPath          The local file path of a font-resource file or app font name or system font name @n
 100          *                                                                      The app font name is retrieved using GetFaceName(Osp::Base::String& filepath).
 101          *                                                                      The system font name is retrieved using GetSystemFontListN().
 102          * @param[in]   style                   The font style @n
 103          *                                                              Multiple styles can be combined using the bitwise OR operator.
 104          * @param[in]   size                    The font size in pixels @n
 105          *                                                              The size must be greater than @c 0.
 106          * @exception   E_SUCCESS                               The method is successful.
 107          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 108          * @exception   E_FILE_NOT_FOUND                The specified font cannot be found or accessed.
 109          * @exception   E_UNSUPPORTED_FORMAT    The specified font format is not supported.
 110          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation.
 111          * @remarks Only TrueType font is supported.
 112          *          The value of fontNameOrPath is considered system font name if it matches one of the retrieved values using GetSystemFontListN().
 113          *          If not, it is considered local file path of a font-resource file.
 114          */
 115         result Construct(const Tizen::Base::String& fontNameOrPath, int style, int size);
 116
 117         /**
 118          * @if OSPCOMPAT
 119          * @page                                        CompFontConstructPage Compatibility for Construct().
 120          * @section                                     CompFontConstructPageIssueSection Issues
 121          *                                                      Implementing this method in OSP compatible applications has the following issues:   @n
 122          *                                                      -# 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.
 123          *                                                      -# 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().
 124          * @endif
 125          */
 126
 127         /**
 128          * Initializes this instance of %Font with the specified parameters.
 129          *
 130          * @since               2.0
 131          *
 132          * @return              An error code
 133          * @param[in]   fontData                The font data
 134          * @param[in]   style           The font style @n
 135          *                                                              Multiple styles can be combined using the bitwise OR operator.
 136          * @param[in]   size                    The font size in pixels @n
 137          *                                              The size must be greater than @c 0.
 138          * @exception   E_SUCCESS                               The method is successful.
 139          * @exception   E_INVALID_ARG                   A specified input parameter is invalid.
 140          * @exception   E_UNSUPPORTED_FORMAT    The specified font format is not supported.
 141          * @exception   E_INVALID_OPERATION             The current state of the instance prohibits the execution of the specified operation.
 142          */
 143         result Construct(const Tizen::Base::ByteBuffer& fontData, int style, int size);
 144
 145         /**
 146          * Gets the maximum height of the current instance of %Font.
 147          *
 148          * @since       2.0
 149          *
 150          * @return      The maximum height of the current instance of %Font, @n
 151          *                      else @c -1 if the method fails
 152          */
 153         int GetMaxHeight(void) const;
 154
 155         /**
 156          * Gets the maximum width of the current instance of %Font.
 157          *
 158          * @since       2.0
 159          *
 160          * @return      The maximum width of the current instance of %Font, @n
 161          *                      else @c -1 if the method fails
 162          */
 163         int GetMaxWidth(void) const;
 164
 165         /**
 166          * Gets the ascender of the current instance of %Font.
 167          *
 168          * @since       2.0
 169          *
 170          * @return     The ascender of the current instance of %Font, @n
 171          *                      else @c -1 if the method fails
 172          */
 173         int GetAscender(void) const;
 174
 175         /**
 176          * Gets the descender of the current instance of %Font.
 177          *
 178          * @since       2.0
 179          *
 180          * @return     The descender of the current instance of %Font, @n
 181          *                      else @c -1 if the method fails
 182          */
 183         int GetDescender(void) const;
 184
 185         /**
 186          * Gets the left bear of a character.
 187          *
 188          * @since               2.0
 189          *
 190          * @return              An error code
 191          * @param[in]   character               A character for getting left bear
 192          * @param[out]  leftBear         The left bear of the specified @c character
 193          * @exception E_SUCCESS                         The method is successful.
 194          * @exception E_DATA_NOT_FOUND   The requested data does not exist.
 195          */
 196         result GetLeftBear(wchar_t character, int& leftBear) const;
 197
 198         /**
 199          * Gets the right bear of a character.
 200          *
 201          * @since               2.0
 202          *
 203          * @return              An error code
 204          * @param[in]   character               A character for getting the right bear
 205          * @param[out]  rightBear               The right bear of the specified @c character
 206          * @exception E_SUCCESS                 The method is successful.
 207          * @exception E_DATA_NOT_FOUND   The requested data does not exist.
 208          */
 209         result GetRightBear(wchar_t character, int& rightBear) const;
 210
 211         /**
 212          * Gets the width and height of the font used in the specified text. @n
 213          * This method retrieves the font dimension of the text.
 214          *
 215          * @if OSPCOMPAT
 216          * @brief <i> [Compatibility] </i>
 217          * @endif
 218          * @since               2.0
 219          * @if OSPCOMPAT
 220          * @compatibility This method has compatibility issues with OSP compatible applications. @n
 221          *                       For more information, see the issue description for @ref CompFontGetTextExtentPage "here".
 222          * @endif
 223          *
 224          * @return              An error code
 225          * @param[in]   text                    The string
 226          * @param[in]   length          The length of @c text @n
 227          *                                                              The length must be greater than or equal to @c 0.
 228          * @param[out]  dim                             The width and height of the font of the @c text
 229          * @exception   E_SUCCESS               The method is successful.
 230          * @exception   E_OUT_OF_RANGE  The value of @c length is greater than the actual length of @c text.
 231          */
 232         result GetTextExtent(const Tizen::Base::String& text, int length, Dimension& dim) const;
 233
 234         /**
 235          * @if OSPCOMPAT
 236          * @page                CompFontGetTextExtentPage Compatibility for the file path.
 237          * @section             CompFontGetTextExtentPageIssueSection Issues
 238          *                              Implementing this method in OSP compatible applications has the following issues:   @n
 239          *                              -# The method returns exact height only if the font resource is designed to fit inside the emBox. @n
 240          *
 241          * @section             CompFontGetTextExtentPageSolutionSection Resolutions
 242          *                              This issue has been resolved in Tizen. @n
 243          *                              -# The method returns exact height regardless of font design. @n
 244          *
 245          * @endif
 246          */
 247
 248         /**
 249          * Checks whether the font style of the current instance is bold.
 250          *
 251          * @since               2.0
 252          *
 253          * @return              @c true if the font style of the current instance is bold, @n
 254          *                              else @c false
 255          */
 256         bool IsBold(void) const;
 257
 258         /**
 259          * Checks whether the font style for the current instance is italics.
 260          *
 261          * @since               2.0
 262          *
 263          * @return              @c true if the font style for the current instance is italics, @n
 264          *                              else @c false
 265          */
 266         bool IsItalic(void) const;
 267
 268         /**
 269          * Checks whether the current instance has any style defined.
 270          *
 271          * @since               2.0
 272          *
 273          * @return              @c true if an extra style is not defined for the current instance, @n
 274          *                                      else @c false
 275          */
 276         bool IsPlain(void) const;
 277
 278         /**
 279          * Checks whether the current instance has the strikeout style set.
 280          *
 281          * @since               2.0
 282          *
 283          * @return              @c true if the current instance has the strikeout style set, @n
 284          *                              else @c false
 285          */
 286         bool IsStrikeOut(void) const;
 287
 288         /**
 289          * Checks whether the current instance has the underline style set.
 290          *
 291          * @since               2.0
 292          *
 293          * @return              @c true if the current instance has the underline style set, @n
 294          *                              else @c false
 295          */
 296         bool IsUnderlined(void) const;
 297
 298         /**
 299          * Gets the font size of the current instance of %Font.
 300          *
 301          * @since               2.0
 302          *
 303          * @return              The font size, @n
 304          *                              else @c -1 if the method fails
 305          */
 306         int GetSize(void) const;
 307
 308         /**
 309          * Sets the strikeout style for the current instance of %Font.
 310          *
 311          * @since               2.0
 312          *
 313          * @param[in]   strikeOut               Set to @c true to use the strikeout style for the current instance of %Font, @n
 314          *                                                              else @c false
 315          */
 316         void SetStrikeOut(bool strikeOut);
 317
 318         /**
 319          * Sets the underline style for the current instance of %Font.
 320          *
 321          * @since               2.0
 322          *
 323          * @param[in]   underline               Set to @c true to use the underline style for the current instance of %Font, @n
 324          *                                                              else @c false
 325          */
 326         void SetUnderline(bool underline);
 327
 328         /**
 329          * Gets the system font list.
 330          *
 331          * @since               2.0
 332          *
 333          * @return              The list of system fonts @n
 334          *                              The font list consists of Tizen::Base::String items.
 335          * @remarks After using the system font list, you can call IList::RemoveAll(true) to clean up string items in the list.
 336          */
 337         static Tizen::Base::Collection::IList* GetSystemFontListN(void);
 338
 339         /**
 340          * Gets the face name of the font file of the specific path.
 341          *
 342          * @since 2.0
 343          *
 344          * @return      The face name of the font file of the specific path
 345          * @param[in]   filePath                The path of the font file
 346          */
 347         static Tizen::Base::String GetFaceName(const Tizen::Base::String& filePath);
 348
 349         /**
 350          * Sets the character space.
 351          *
 352          * @since       2.0
 353          *
 354          * @param[in]          space    A character space
 355          */
 356         void SetCharSpace(int space);
 357
 358         /**
 359          * Gets the character space.
 360          *
 361          * @since       2.0
 362          *
 363          * @return      The character space of this font instance, @n
 364          *                      else @c -1 if the method fails
 365          */
 366         int GetCharSpace(void) const;
 367
 368         /**
 369          * Gets the face name.
 370          *
 371          * @since       2.0
 372          *
 373          * @return      The face name of this font instance
 374          */
 375         Tizen::Base::String GetFaceName(void) const;
 376
 377 private:
 378         friend class _FontImpl;
 379
 380         //
 381         // This method is for internal use only. Using this method can cause behavioral, security-related,
 382         // and consistency-related issues in the application.
 383         //
 384         /**
 385          * @since 2.0
 386          */
 387         class _FontImpl* __pImpl;
 388
 389         /*
 390          * This is the copy constructor for the Font class.
 391          *
 392          * @remarks             Do not use this constructor.
 393          */
 394         Font(const Font& rhs);
 395         Font& operator =(const Font& rhs);
 396
 397 }; // Font
 398
 399 }} // Tizen::Graphics
 400
 401 #endif //_FGRP_FONT_H_