1 /*

     2 * Copyright (c) 2006-2007 Nokia Corporation and/or its subsidiary(-ies). 

     3 * All rights reserved.

     4 * This component and the accompanying materials are made available

     5 * under the terms of "Eclipse Public License v1.0"

     6 * which accompanies this distribution, and is available

     7 * at the URL "http://www.eclipse.org/legal/epl-v10.html".

     8 *

     9 * Initial Contributors:

    10 * Nokia Corporation - initial contribution.

    11 *

    12 * Contributors:

    13 *

    14 * Description:   Font base class.

    15 *

    16 */

    17 

    18 

    19 

    20 #ifndef __HUIFONT_H__

    21 #define __HUIFONT_H__

    22 

    23 #include <AknFontSpecification.h> 

    24 

    25 #include <e32base.h>

    26 #include <gdi.h>

    27 #include <bitstd.h>

    28 

    29 /**

    30  * THuiFont is presents an abstract font implementation. It cannot be used on

    31  * its own. Its main purpose is to act as a handle to a system font and

    32  * provide metrics to the layout and drawing routines.

    33  *

    34  * Different rendering plugins will implement their own version of this class

    35  * to suit their own functionality.

    36  */

    37 class THuiFont

    38     {

    39 public:

    40 

    41     /** @beginAPI */

    42 

    43     /**

    44      * Default constructor. This instance should be initialised before use.

    45      */

    46     IMPORT_C THuiFont();

    47     

    48     /**

    49      * Constructor from a TFontSpec in twips.

    50      * Since the metrics are mastered in pixels, the passed-in TFontSpec::Height() is converted to 

    51      * pixels using the default screen device's twips-to-pixel ratio.

    52      *

    53      * @param aId       A handle id set into the THuiFont by the Texture manager or skin

    54      * @param aFontSpec Symbian OS Font Specification to store

    55      */

    56     IMPORT_C THuiFont(TInt aId, const TFontSpec& aFontSpec);

    57 

    58     /**

    59      * Destructor.

    60      * @todo: T-class shouldn't have destructor to begin with

    61      */

    62     IMPORT_C ~THuiFont();

    63 

    64     /**

    65      * Copy constructor.

    66      * @param aFont Font to be copied.

    67      */

    68     IMPORT_C THuiFont( const THuiFont& aFont );

    69             

    70     /**

    71      * Assignment operator.

    72      * @param aFont Font to be copied.

    73      * @return Reference to this instance.

    74      */

    75     IMPORT_C THuiFont& operator=( const THuiFont& aFont );

    76 

    77     /* Methods. */

    78 

    79     /**

    80      * Determines the font's identifier.

    81      *

    82      * @return  Font identifier.

    83      */

    84     IMPORT_C TInt Id() const;

    85 

    86     /**

    87      * Returns the font category.

    88      */

    89     IMPORT_C TAknFontCategory Category() const;

    90 

    91     /**

    92      * Returns the Symbian font specification. Always returned in Twips

    93      * 

    94      *  @param aMap  Graphics device map containing desired pixel to twips ratio to use

    95      *  @return Symbian OS Font specification

    96      */

    97     IMPORT_C TFontSpec FontSpec(MGraphicsDeviceMap* aMap = NULL) const;    

    98     

    99     /** @endAPI */

   100 

   101     /**

   102      * Sets the font specification.

   103      */

   104     IMPORT_C void SetFontSpec(const TFontSpec& aFontSpec);

   105    

   106     /**

   107      * Sets the category.

   108      */

   109     IMPORT_C void SetCategory(const TAknFontCategory aCategory);

   110 

   111     /**

   112      * Required vertical extend of the font. This value is always returned in pixels.

   113      * The text will fit within a rectangle of this height

   114      * 

   115      * @return  text pane height in pixels into which the text is to fit completely

   116      */

   117     IMPORT_C TInt TextPaneHeight() const;

   118     

   119     /**

   120      * Required vertical extend of the font. This value is always specified in pixels.

   121      * The text will fit within a rectangle of this height

   122      * 

   123      * @param aTextPaneHeight  text pane height in pixels into which the text is to fit completely

   124      */

   125     IMPORT_C void SetTextPaneHeight(TInt aTextPaneHeight);

   126     

   127     /**

   128      * Returns the nearest CFont object representation of this THuiFont object.

   129      * Creates the CFont object according to specifications in this THuiFont unless

   130      * one is already created. If CFont object is already created then the already

   131      * created instance is returned. Releasing of CFont - object is handled by this

   132      * class.

   133      *

   134      * @param aTextMeshYScale  Height scale factor from LCD resolution to TV resolution. @todo: tell more...

   135      * 

   136      * @return Closest CFont - object representing this THuiFont.

   137      */

   138     IMPORT_C CFont* NearestFontL(TReal32 aTextMeshYScale = 1) __SOFTFP;

   139     

   140     /**

   141      * Rasterizes the given text string to the target graphics context using this font.

   142      * The caller has to configure the graphics context with parameters to be used in

   143      * rasterization before calling this method.

   144      * 

   145      * @param aTextString 		The text string to be rasterized.

   146      * @param aTargetContext 	The target graphics context to be used in rasterization.

   147      */

   148     IMPORT_C void RasterizeLineL(const TDesC& aTextString, CFbsBitGc& aTargetContext);

   149 

   150     /**

   151      * Retrieves the dimensions in pixels occupied by rasterization of the given string using

   152      * this font.

   153      * 

   154      * @param aTextString String that is used in calculation of rasterization dimensions.

   155      * @return Dimensions occupied by rasterization of the text string in pixels.

   156      */

   157     IMPORT_C TSize LineExtentsL(const TDesC& aTextString);

   158     

   159 	/**

   160 	 * Release the Symbian font representation.

   161 	 */

   162 	IMPORT_C void ReleaseFont();

   163 	

   164 private:

   165 

   166     /**

   167     * This is backporting AknBidiTextUtils::MeasureTextBoundsWidth from S60 3.1 to have that

   168     * functionality also when running hitchcock on S60 3.0 platform

   169     *

   170     * Measures the full horizontal width in pixels of the passed-in text using a particular font, 

   171     * including in the width any side-bearings of the glyphs at the ends of the text, and any

   172     * declared "advance" of the run of glyphs. 

   173     * 

   174     * It cannot be used for vertical text measurement.

   175     * 

   176     * Side-bearings are parts of glyphs that extend left or right from the normal width

   177     * or "advance" of the glyph. A left side-bearing, for instance, will overlap with a glyph

   178     * to its left. Another way of thinking about this is that the origin (0,0) of the glyph is 

   179     * not at its bottom left. 

   180     *

   181     * The advance of a run of glyphs is the sum of the advances - once in visual ordering and 

   182     * shaping has been performed - of all the glyphs. It is defined relative to a drawing origin.

   183     * 

   184     * Within runs of text, side-bearings do not contribute to the width of the text. However,

   185     * at the (visual) ends of text, they are likely to need to be counted, depending upon the

   186     * exact use case.

   187     * 

   188     * This method returns the width of the horizontal envelope of the text by taking the extreme 

   189     * horizontal extents of the text bounds rectangle (which includes side-bearings on either end)

   190     * and the extent of the advance. Thus it returns the width of :

   191     *   Min(<left_text_bound>, 0), Max( <right_text_bound>, <advance>)

   192     *   

   193     * This method should be used when the proposed text is going to be drawn using any horizontal

   194     * CGraphicsContext::DrawText drawing API. 

   195     *

   196     * The text can be in visual or logical order.

   197     *

   198     * @since 3.1

   199     * @param aFont  Font to use

   200     * @param aText  Text to be measured

   201     * @param aOrder Whether the text provided is in visual or logical order

   202     * @return       width of the text in pixels.

   203     */

   204     TInt THuiFont::MeasureBidiTextBoundsWidth(const CFont& aFont,

   205                                           const TDesC& aText,

   206                                           CFont::TMeasureTextInput::TFlags aOrder) const;

   207 

   208 

   209     /** Identifier number. Assigned by the texture manager. */

   210     TInt iId;

   211 

   212     /** Symbian Font specification. */

   213     TFontSpec iFontSpec;

   214 

   215     // Structure containing Symbian Font instance and reference count.

   216     struct TFontRef;

   217 

   218     /** Nearest Font object. */

   219     TFontRef* iFont;

   220     

   221     /** This is the vertical space in which the font will fit.

   222     This measure is alwasy in pixels.

   223     It may be necessary to use this request the font, rather than via the Fontspec*/

   224     TInt iTextPaneHeight;

   225     

   226     TAknFontCategory iCategory;

   227     

   228     TInt iSpare1;

   229     TInt iSpare2;

   230     };

   231 

   232 

   233 #endif // __HUIFONT_H__