Class COpenFontFile

COpenFontFile

Support

Supported from 5.0

Description

Font file abstract base class.

Write a class derived from COpenFontFile to manage a file with the font format supported by your DLL. The derived class must implement the virtual GetNearestFontInPixelsL() function. This function takes a font description and creates a COpenFont derived object if the description matches a typeface contained in the font file.

Derived classes must also load typeface attributes from the file into the protected typeface attribute array during construction. This array is what is searched when getting font attribute information — see AddArrayL(), GetNearestFontHelper().

Writing derived classes — construction:

Call the COpenFontFile constructor in the constructor for your derived object, passing it aUid and aFileName arguments. These values are the arguments passed when the constructor is called by COpenFontRasterizer::NewFontFileL().

A file may contain one or more typefaces. During construction the derived object should extract the information for each typeface and add it to this object's protected typeface attribute array — see AddFaceL(). This process will probably leave under some conditions. It should therefore be implemented in a second phase constructor.

Writing derived classes — implement the pure virtual functions:

Derived classes must also implement the two pure virtual functions GetNearestFontInPixelsL() and HasUnicodeCharacterL(). Information about these functions is provided in the definitions below. Information about deriving from this class is also provided in the API guide.

Derivation

CBase Base class for all classes to be instantiated on the heap COpenFontFile Font file abstract base class

Defined in COpenFontFile:
AddFaceL(), COpenFontFile(), DecRefCount(), FaceAttrib(), FaceCount(), FileName(), GetNearestFontHelper(), GetNearestFontInPixelsL(), HasUnicodeCharacterL(), IncRefCount(), Uid(), ~COpenFontFile()

Inherited from CBase:
operator new()

See also:

• COpenFontRasterizer::NewFontFileL()
• CWsScreenDevice::AddFile()

COpenFontFile(TInt aUid,const TDesC& aFileName);

Description

C++ constructor with UID and filename.

Call this constructor in the constructor for your derived object, passing it aUid and aFileName arguments.

Note:

• Non Symbian-platform-native font files are allocated IDs by the font store — these are passed in by the rasteriser class. UIDs are required by the font framework. However you should not use the ID to access the file, since a new UID will need to be allocated when the file is next loaded, e.g. after a device reboot. Instead use the font file name.

Parameters

TInt aUid The UID of the font file. const TDesC& aFileName The full filename, including the path, of the font file.

~COpenFontFile();

Description

Destructor.

The destructor notifies fonts using this file that it has been deleted, allowing a controlled exit if a file is deleted before its fonts.

virtual void GetNearestFontInPixelsL(RHeap* aHeap,COpenFontSessionCacheList* aSessionCacheList, const TOpenFontSpec& aDesiredFontSpec,TInt aPixelWidth,TInt aPixelHeight, COpenFont*& aFont,TOpenFontSpec& aActualFontSpec)=0;

Description

Gets the nearest font in pixels.

Implementations of this pure virtual function should create the COpenFont derived object that most closely matches aFontSpec, and place a pointer to it in aFont. If this cannot be done, e.g. if the font name doesn't match, aFont should be set to NULL.

The other two arguments, aHeap and aSessionCacheList, should be passed to the COpenFont constructor.

Note:

• Implementations may use the utilitity function GetNearestFontHelper() to get the attributes of the closest matching font.

Parameters

RHeap* aHeap Shared heap. This value should be passed to the COpenFont derived classes' constructor. COpenFontSessionCacheList* aSessionCacheList The session cache list. This value should be passed to the COpenFont derived classes' constructor. const TOpenFontSpec& aDesiredFontSpec The desired font specification. TInt aPixelWidth The width of a pixel. Used with aPixelHeight for calculating the algorithmic slant of the typeface. TInt aPixelHeight The height of a pixel. Used with aPixelWidth for calculating the algorithmic slant of the typeface. COpenFont*& aFont On return, contains a pointer to the newly created COpenFont derived object, or NULL if no font matching aDesiredFontSpec exists. TOpenFontSpec& aActualFontSpec The actual font specification of the font retrieved into aFont.

See also:

• GetNearestFontHelper()

virtual TBool HasUnicodeCharacterL(TInt aFaceIndex,TInt aCode) const=0;

Description

Tests whether a specified typeface contains a particular character.

Parameters

TInt aFaceIndex The index of the typeface to be tested. TInt aCode The Unicode character code for the character to be tested.

Return value

TBool ETrue if the typeface contains aCode, otherwise EFalse.

void AddFaceL(const TOpenFontFaceAttrib& aAttrib);

Support

Supported from 5.1

Description

Adds a typeface to this object's typeface array.

This function should be called during construction to add the attributes for each typeface in the font file to the typeface attribute array.

Note:

• The typeface array is what is searched for the closest match to a specified font by GetNearestFontHelper().

Parameters

const TOpenFontFaceAttrib& aAttrib The attributes for a typeface to be added to the typeface attribute array.

See also:

• FaceAttrib()
• FaceCount()

TBool DecRefCount();

Description

Decrement a reference count by one.

The function will reduce the reference count below zero, but will return EFalse for values below zero.

Return value

TBool ETrue if the decrement was successful, EFalse if the reference count decreased to zero.

See also:

• IncRefCount()

const TOpenFontFaceAttrib& FaceAttrib(TInt aFaceIndex) const;

Description

Gets the typeface at a specified index in the typeface attribute array.

Parameters

TInt aFaceIndex The index of the typeface for which the attributes are required.

Return value

TOpenFontFaceAttrib& The attributes of the typeface with the specified index.

See also:

• AddFaceL()
• FaceCount()

TInt FaceCount() const;

Description

Gets the number of typefaces in the typeface attributes array.

This is the number of typefaces in the font file — the attributes for each typeface should be loaded into the array when the derived object is constructed.

Return value

TInt The number of typefaces in the font file.

See also:

• AddFaceL()
• FaceAttrib()

const TDesC& FileName() const;

Description

Gets the full path and filename of the font file

This is the filename that was passed to the constructor when the object is created.

Return value

TDesC& The filename of the font file.

TBool GetNearestFontHelper(const TOpenFontSpec& aDesiredFontSpec,TInt aPixelWidth,TInt aPixelHeight, TInt& aFaceIndex,TOpenFontSpec& aActualFontSpec) const;

Description

Gets the nearest font — helper function.

This function may be used by derived classes in their GetNearestFontInPixelsL() implementations. It finds the nearest font in the typeface attribute array, if any, to the provided font specification. If there is a possible match it places the face index in aFaceIndex and the actual specification (including algorithmic effects) in aActualFontSpec.

Parameters

const TOpenFontSpec& aDesiredFontSpec The desired font specification. TInt aPixelWidth The width of a pixel. Used with aPixelHeight for calculating the algorithmic slant of the typeface. TInt aPixelHeight The height of a pixel. Used with aPixelWidth for calculating the algorithmic slant of the typeface. TInt& aFaceIndex The index of the typeface which contains the closest match to aDesiredFontSpec. TOpenFontSpec& aActualFontSpec The actual font specification of the font with attributes closest to aDesiredFontSpec.

Return value

TBool ETrue if there is a possible font match, otherwise EFalse.

void IncRefCount();

Description

Increments a reference count by one.

See also:

• DecRefCount()

TUid Uid() const;

Description

Gets the font file's UID.

Return value

TUid The uid of the file.