sl@0: /*
sl@0: * Copyright (c) 2006-2009 Nokia Corporation and/or its subsidiary(-ies).
sl@0: * All rights reserved.
sl@0: * This component and the accompanying materials are made available
sl@0: * under the terms of "Eclipse Public License v1.0"
sl@0: * which accompanies this distribution, and is available
sl@0: * at the URL "http://www.eclipse.org/legal/epl-v10.html".
sl@0: *
sl@0: * Initial Contributors:
sl@0: * Nokia Corporation - initial contribution.
sl@0: *
sl@0: * Contributors:
sl@0: *
sl@0: * Description: 
sl@0: *
sl@0: */
sl@0: 
sl@0: 
sl@0: #ifndef __LINKEDFONTS_H__
sl@0: #define __LINKEDFONTS_H__
sl@0: 
sl@0: _LIT(KFNTSTORELinkedFontsPanicCategory,"LINKED_FONTS");
sl@0: 
sl@0: class CLinkedTypefaceBody;
sl@0: class CLinkedTypefaceSpecificationBody;
sl@0: class CLinkedTypefaceElementSpec;
sl@0: class CLinkedTypefaceGroup;
sl@0: class CFbsTypefaceStore;
sl@0: class TLinkedTypefaceSpecificationArgs;
sl@0: 
sl@0: /**
sl@0: This class contains the specification of a linked typeface. It is made up of groups and typefaces.
sl@0: 
sl@0: Groups (CLinkedTypefaceGroup) must contain one or more typeface; the attributes of the group control how the rasterizer
sl@0: draws the typefaces within the group.
sl@0: 
sl@0: Typefaces (CLinkedTypefaceElementSpec) specify which individual typefaces make up the linked typeface. These are
sl@0: referred to as "elements" of the linked typeface.
sl@0: 
sl@0: Once the linked typeface has been created users can use it as if it were any other typeface assuming there
sl@0: is a rasteriser that supports this feature available. When selecting a character the rasterize searches
sl@0: each typeface in turn from the lowest index to the highest. When drawing text, the first typeface to contain
sl@0: the required character is used.
sl@0: 
sl@0: KMaxLinkedTypefaces and KMaxLinkedTypefaceGroups define the maximum number of typefaces and groups that can be
sl@0: added to the specification.
sl@0: 
sl@0: This class is not thread safe.
sl@0: 
sl@0: WARNING: Class for internal and partner use ONLY.  Compatibility is not guaranteed in future releases.
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: @see CLinkedTypefaceElementSpec
sl@0: @see CLinkedTypefaceGroup
sl@0: @see KLinkedMaxTypefaces
sl@0: @see KMaxLinkedTypefaceGroups
sl@0: */
sl@0: NONSHARABLE_CLASS(CLinkedTypefaceSpecification) : public CBase
sl@0: {
sl@0: public:
sl@0: 	/**
sl@0: 	This function constructs the linked typeface specification and places it on the CleanupStack.
sl@0: 	
sl@0: 	The specification must contain at least one group and one typeface in order for registration to be successful.
sl@0: 	
sl@0: 	@param aName The name of the linked typeface. This name should not be the same as an existing typeface.
sl@0: 	
sl@0: 	@return A linked typeface specification object
sl@0: 	*/
sl@0: 	IMPORT_C static CLinkedTypefaceSpecification* NewLC(const TDesC& aTypefaceName);
sl@0: 
sl@0: 	/**
sl@0: 	The name of this linked typeface
sl@0: 	@return The name of this linked typeface
sl@0: 	*/
sl@0: 	IMPORT_C TPtrC Name() const;
sl@0: 
sl@0: 	/**
sl@0: 	The number of typeface that have been added to this object
sl@0: 	@return TInt The number of typeface that have been added to this object
sl@0: 	*/
sl@0: 	IMPORT_C TInt TypefaceCount() const;
sl@0: 
sl@0: 	/**
sl@0: 	Returns the linked typeface at the specified index. 
sl@0: 	The first typeface is at index 0, the last at TypefaceCount()-1.
sl@0: 	@return The linked typeface.  Null is returned on error.
sl@0: 	@see CLinkedTypefaceSpecification::NumberOfTypefaces()
sl@0: 	*/
sl@0: 	IMPORT_C CLinkedTypefaceElementSpec* Typeface(TInt aIndex) const;
sl@0: 
sl@0: 	/**
sl@0: 	Function to return the index of the canonical (metrics) typeface. The typeface can be
sl@0: 	retrieved by passing the index to Typeface().
sl@0: 	
sl@0: 	@return TInt The index to the canonical typeface
sl@0: 	@return KErrNotFound No canonical typeface exists
sl@0: 	@return KErrOverFlow There is more than one canonical typeface
sl@0: 	@see CLinkedTypefaceSpecification::Typeface()
sl@0: 	*/
sl@0: 	IMPORT_C TInt CanonicalIndex();
sl@0: 	
sl@0: 	/**
sl@0: 	Adds the supplied CLinkedTypefaceElementSpec to the Linked Typeface specification.
sl@0: 	The element is placed at the specified index. Adding a canonical element will only be successful
sl@0: 	if one has not already been added. The specification takes ownership of the element specification
sl@0: 	if adding is successful.
sl@0: 	
sl@0: 	@param aElementSpec The specification to be added.
sl@0: 	@param aIndex The position at which the element spec will be added.
sl@0: 
sl@0: 	@see CLinkedTypefaceSpecification::AddTypefaceAtBackL()
sl@0: 	@see CLinkedTypefaceSpecification::RemoveTypeface()
sl@0: 	@see KMaxLinkedTypefaces
sl@0: 	
sl@0: 	@leave KErrArgument If the element is canonical and a canonical element already exists or if the group ID doesn't exist
sl@0: 	@leave KErrNoMemory There was not enough memory available to perform this operation
sl@0: 	@leave KErrOverflow The typeface specification is full; adding would exceed KMaxLinkedTypefaces
sl@0: 	*/
sl@0: 	IMPORT_C void AddTypefaceAtIndexL(CLinkedTypefaceElementSpec& aElementSpec, TInt aIndex);
sl@0: 
sl@0: 	/**
sl@0: 	Adds the supplied CLinkedTypefaceElementSpec to the Linked Typeface specification.
sl@0: 	The element is placed at the back of the specification. Adding a canonical element will only be 
sl@0: 	successful if one has not already been added. The specification takes ownership of the element 
sl@0: 	specification if adding is successful.
sl@0: 	
sl@0: 	@param aElementSpec
sl@0: 
sl@0: 	@see CLinkedTypefaceSpecification::AddTypefaceAtIndexL()
sl@0: 	@see CLinkedTypefaceSpecification::RemoveTypeface()
sl@0: 	@see KMaxLinkedTypefaces
sl@0: 	
sl@0: 	@leave KErrArgument If the element is canonical and a canonical element already exists or if the group ID doesn't exist
sl@0: 	@leave KErrNoMemory There was not enough memory available to perform this operation
sl@0: 	@leave KErrOverflow The typeface specification is full; adding would exceed KMaxLinkedTypefaces
sl@0: 	*/
sl@0: 	IMPORT_C void AddTypefaceAtBackL(CLinkedTypefaceElementSpec& aElementSpec);
sl@0: 
sl@0: 	/**
sl@0: 	Removes the element spec at the specified index from this specification.
sl@0: 	This function deletes the element spec. If the element is the only one within its group
sl@0: 	the group is also removed and deleted from the specification.
sl@0: 
sl@0: 	@param aIndex the index of the element spec to be removed
sl@0: 
sl@0: 	@return TInt KErrNone if Removal was successful; KErrNotFound If the index is negative or larger than the number of typeface elements or the element doesn't exist
sl@0: 	*/
sl@0: 	IMPORT_C TInt RemoveTypeface(TInt aIndex);
sl@0: 
sl@0: 	/**
sl@0: 	Creates the linked typeface so that it is available to use a normal typeface.
sl@0: 
sl@0: 	@param aStore The Typeface Store the linked typeface should be registered with
sl@0: 
sl@0: 	@panic EFbsPanicNoConnection There is no connection to the Font & Bitmap Server
sl@0: 
sl@0: 	@leave KErrNotFound One or more of the typeface elements do not exist
sl@0: 	@leave KErrOverflow The linked typeface contains too many or 0 elements
sl@0: 	@leave KErrArgument The typeface has no or more than one canonical element
sl@0: 	@leave KErrAlreadyExists A typeface with the same name already exists
sl@0: 	@leave KErrNotSupported There is not a rasterizer available that supports linked typefaces
sl@0: 	*/
sl@0: 	IMPORT_C void RegisterLinkedTypefaceL(CFbsTypefaceStore& aStore);
sl@0: 	
sl@0: 	/**
sl@0: 	Retrieves the linked typeface specification from the server; the name of the typeface to
sl@0: 	retrieve should be specified at construction. All typefaces and groups contained in the
sl@0: 	specification are removed before retrieval of the new data. 
sl@0: 	
sl@0: 	@see CLinkedTypefaceSpecification::NewLC()
sl@0: 	
sl@0: 	@param aStore A pointer to the FontStore
sl@0: 
sl@0: 	@leave KErrNotSupported There is not a rasterizer available that supports linked typefaces
sl@0: 	@leave KErrArgument The font specified does not exist or is not a linked typeface
sl@0: 	*/
sl@0: 	IMPORT_C void FetchLinkedTypefaceSpecificationL(CFbsTypefaceStore& aStore);
sl@0: 	
sl@0: 	/**
sl@0: 	 Adds the group specified to this specification.
sl@0: 	 The specification takes ownership of the group if addition is successful.
sl@0: 	 
sl@0: 	 @param aGroup The group to be added
sl@0: 	 
sl@0: 	 @see CLinkedTypefaceSpecification::RemoveLinkedTypefaceGroup()
sl@0: 	 
sl@0: 	 @leave KErrAlreadyExists A group with the same ID is already present in the specification
sl@0: 	 */
sl@0: 	IMPORT_C void AddLinkedTypefaceGroupL(CLinkedTypefaceGroup& aGroup);
sl@0: 	
sl@0: 	/**
sl@0: 	This will remove the group and all the elements associated with it.
sl@0: 	
sl@0: 	@param aGroupId The Id of the group to be removed
sl@0: 	*/
sl@0: 	IMPORT_C TInt RemoveLinkedTypefaceGroup(TInt aGroupId);
sl@0: 	
sl@0: 	/**
sl@0: 	Returns the linked typeface group with the specified group ID.
sl@0: 	
sl@0: 	@param aGroupId The linked typeface group ID
sl@0: 	@return The linked typeface group specified or NULL if it doesn't exist
sl@0: 	*/
sl@0: 	IMPORT_C CLinkedTypefaceGroup* GroupById(TInt aGroupId) const; 
sl@0: 	
sl@0: 	/**
sl@0: 	Returns the linked typeface group at the specified index within the specification.
sl@0: 	The Index ranges from 0 to the value returned by NumberOfGroups()-1.
sl@0: 	
sl@0: 	@param aGroupIndex The linked typeface groups index within the specification
sl@0: 	@return The linked typeface group specified or NULL if it doesn't exist
sl@0: 	*/
sl@0: 	IMPORT_C CLinkedTypefaceGroup* Group(TInt aGroupIndex) const;
sl@0: 	
sl@0: 	/**
sl@0: 	Returns the number of groups that this linked typeface specification contains.
sl@0: 	
sl@0: 	@see CLinkedTypefaceSpecification::Group()
sl@0: 	
sl@0: 	@return TInt Number of groups
sl@0: 	*/
sl@0: 	IMPORT_C TInt GroupCount() const;
sl@0: 	
sl@0: 	/**
sl@0: 	Default destructor
sl@0: 	*/
sl@0: 	IMPORT_C ~CLinkedTypefaceSpecification();
sl@0: 	
sl@0: 	/**
sl@0: 	 Removes and destroys all groups and elements from the specification.
sl@0: 	 
sl@0: 	 WARNING: Function for internal use ONLY. Compatibility is not guaranteed in future releases.
sl@0: 	 */
sl@0: 	IMPORT_C void Clear();
sl@0: 	
sl@0: 	/**
sl@0: 	 Update the specification of an existing linked typeface.
sl@0: 	 
sl@0: 	 @param aStore A typeface store
sl@0: 	 
sl@0: 	 @publishedPartner
sl@0: 	 */
sl@0: 	IMPORT_C void UpdateLinkedTypefaceL(CFbsTypefaceStore& aStore);
sl@0: 	
sl@0: private:
sl@0: 	CLinkedTypefaceSpecification();
sl@0: 	void ConstructL(const TDesC& aTypefaceName);
sl@0: 	void DoAddTypefaceL(CLinkedTypefaceElementSpec& aElementSpec, TInt aPos);
sl@0: 	
sl@0: private:
sl@0: 	CLinkedTypefaceSpecificationBody *iBody;
sl@0: 	};
sl@0: 
sl@0: 
sl@0: /**
sl@0: Class to specify an individual typeface within a linked typeface.
sl@0: 
sl@0: WARNING: Class for internal and partner use ONLY.  Compatibility is not guaranteed in future releases.
sl@0: 
sl@0: @see CLinkedTypefaceSpecification
sl@0: @see CLinkedTypefaceGroup
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: NONSHARABLE_CLASS(CLinkedTypefaceElementSpec) : public CBase
sl@0: 	{
sl@0: public:
sl@0: 	/**
sl@0: 	Create a new linked typeface element specification. The name specified must be an existing typeface
sl@0: 	that should be added to the linked typeface. The group ID links this typeface to a linked typeface
sl@0: 	group.
sl@0: 	
sl@0: 	@see CLinkedTypefaceGroup
sl@0: 	
sl@0: 	@param aTypefaceName The typeface name for this element
sl@0: 	@param aGroupId The ID of the linked font group this element should belong to
sl@0: 	
sl@0: 	@return The newly created element spec
sl@0: 	*/
sl@0: 	IMPORT_C static CLinkedTypefaceElementSpec* NewLC(const TDesC& aTypefaceName, TInt aGroupId);
sl@0: 
sl@0: 	/**
sl@0: 	Returns the typeface that this element represents within the linked typeface.
sl@0: 	
sl@0: 	@return	The element typeface name
sl@0: 	*/
sl@0: 	IMPORT_C TPtrC ElementName() const;
sl@0: 	
sl@0: 	/**
sl@0: 	Set whether the element is the canonical (metrics) font. 
sl@0: 	This is the font that provides all the metrics for the linked typeface.
sl@0: 	
sl@0: 	@param aIsCanonical ETrue if the element is canonical, EFalse otherwise
sl@0: 	*/
sl@0: 	IMPORT_C void SetCanonical(TBool aIsCanonical);
sl@0: 	/**
sl@0: 	@return	ETrue if the lement is canonical, EFalse otherwise
sl@0: 	*/
sl@0: 	IMPORT_C TBool Canonical() const;
sl@0: 	
sl@0: 	/**
sl@0: 	@return The group ID specified at construction.
sl@0: 	 */
sl@0: 	IMPORT_C TInt GroupId() const;
sl@0: 	
sl@0: 	/**
sl@0: 	Default Destructor
sl@0: 	*/
sl@0: 	IMPORT_C ~CLinkedTypefaceElementSpec();
sl@0: 
sl@0: private:
sl@0: 	/**
sl@0: 	Constructor
sl@0: 	*/
sl@0: 	CLinkedTypefaceElementSpec(TInt aGroupId);
sl@0: 	void ConstructL(const TDesC& aName);
sl@0: 	
sl@0: private:
sl@0: 	HBufC*	iElementName;
sl@0: 	TBool	iIsCanonical;
sl@0: 	TInt	iGroupId;
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: This class contains parameters used to describe the groups that linked typeface elements are associated to.
sl@0: These "metrics" apply to all fonts that are specified to be within the group.
sl@0: 
sl@0: WARNING: Class for internal and partner use ONLY.  Compatibility is not guaranteed in future releases.
sl@0: 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: NONSHARABLE_CLASS(CLinkedTypefaceGroup) : public CBase
sl@0: 	{
sl@0: public:
sl@0: 	/**
sl@0: 	Specifies the different ways in which a typeface belonging to this group can be scaled.
sl@0: 	 */
sl@0: 	enum TScalingOption
sl@0: 		{
sl@0: 		EScalingNone,
sl@0: 		EScalingUp,
sl@0: 		EScalingDown,
sl@0: 		EScalingUpOrDown,
sl@0: 		};
sl@0: 	/**
sl@0: 	Specifies whether the font baseline of fonts belonging to this group should be shifted or not.
sl@0: 	 */
sl@0: 	enum TBaselineShift
sl@0: 		{
sl@0: 		EBaselineShift,
sl@0: 		ENoBaselineShift,
sl@0: 		};
sl@0: 	/**
sl@0: 	Constructs a new linked typeface group with the specified ID and places it on the CleanupStack.
sl@0: 	
sl@0: 	By default the Antialiasing Threshold, Boldness Percentage and Italic Angle are set to -1.
sl@0: 	The rasterizer will apply its "best-guess" as to the value in this case.
sl@0: 	The default scaling option is EScalingNone; the default baseline shift is ENoBaselineShift.
sl@0: 	
sl@0: 	@param TInt The group ID of this group
sl@0: 	@return CLinkedTypefaceGroup* A newly constructed group
sl@0: 	*/
sl@0: 	IMPORT_C static CLinkedTypefaceGroup* NewLC(TInt aGroupId);
sl@0: 	
sl@0: 	/**
sl@0: 	The group ID specified at construction.
sl@0: 	
sl@0: 	@return TInt The group ID of this group
sl@0: 	 */
sl@0: 	IMPORT_C TInt GroupId() const;
sl@0: 
sl@0: 	/**
sl@0: 	Sets the scaling option associated with the typefaces within this group.
sl@0: 	
sl@0: 	@param TScalingOption The enumeration value corresponding to the required scaling.
sl@0: 	
sl@0: 	@see CLinkedTypefaceGroup::TScalingOption
sl@0: 	*/
sl@0: 	IMPORT_C void SetScalingOption(TScalingOption aOption);
sl@0: 	
sl@0: 	/**
sl@0: 	The scaling option associated with the typefaces within this group.
sl@0: 	
sl@0: 	@see CLinkedTypefaceGroup::TScalingOption
sl@0: 	
sl@0: 	@return TScalingOption Scaling options
sl@0: 	 */
sl@0: 	IMPORT_C TScalingOption ScalingOption() const;
sl@0: 	
sl@0: 	/**
sl@0: 	Sets whether the baseline of typefaces within this group is shifted.
sl@0: 	
sl@0: 	@param TBaselineShift The enumeration value corresponding to the required shifting.
sl@0: 	
sl@0: 	@see CLinkedTypefaceGroup::TBaselineShift
sl@0: 	*/
sl@0: 	IMPORT_C void SetBaselineShift(TBaselineShift aShift);
sl@0: 	
sl@0: 	/**
sl@0: 	The baseline shift associated with the typefaces within this group.
sl@0: 	
sl@0: 	@return TBaselineShift The baseline shift
sl@0: 	*/
sl@0: 	IMPORT_C TBaselineShift BaselineShift() const;
sl@0: 	
sl@0: 	/**
sl@0: 	Sets the boldness percentage used by typefaces belonging to this group.
sl@0: 	
sl@0: 	The percentage is relative to the font size specified. For example if a
sl@0: 	font with an em height of 18 has a boldness percentage of 5% the resulting
sl@0: 	emboldened text	will be emboldened by 18 x (5 / 100) = 0.9 pixels.
sl@0: 	
sl@0: 	@param aPercentage The boldness percentage to be used by this group.
sl@0: 	 */
sl@0: 	IMPORT_C void SetBoldnessPercentage(TInt aPercentage);
sl@0: 	/**
sl@0: 	Returns the current boldness percentage for this typeface group.
sl@0: 	@return The current boldness percentage for this typeface group
sl@0: 	*/
sl@0: 	IMPORT_C TInt BoldnessPercentage() const;
sl@0: 
sl@0: 	/**
sl@0: 	Sets the angle (slant) of italic text
sl@0: 	
sl@0: 	@param aAngle The angle (slant) of italic text
sl@0: 	 */
sl@0: 	IMPORT_C void SetItalicAngle(TInt aAngle);
sl@0: 	
sl@0: 	/**
sl@0: 	The angle (slant) of italic text
sl@0: 	
sl@0: 	@return The angle (slant) of italic text
sl@0: 	 */
sl@0: 	IMPORT_C TInt ItalicAngle() const;
sl@0: 	
sl@0: 	/**
sl@0: 	Default constructor
sl@0: 	*/
sl@0: 	~CLinkedTypefaceGroup();
sl@0: 	
sl@0: private:
sl@0: 	CLinkedTypefaceGroup(TInt aGroupId);
sl@0: 	
sl@0: private:
sl@0: 	TInt iGroupId;
sl@0: 	TScalingOption iScalingOption;
sl@0: 	TBaselineShift iBaselineShift;
sl@0: 	TInt iBoldnessPercentage;
sl@0: 	TInt iItalicAngle;
sl@0: 	};
sl@0: #endif