Class CFormatLayer

CFormatLayer

Support

Supported from 5.0

Description

Abstract base class for the paragraph and character format layers (CParaFormatLayer and CCharFormatLayer).

A format layer is a set of character or paragraph format attributes which may own a pointer to another format layer. This pointer is called a based-on link. The effective formatting of a text object may be built up from a chain of format layers — the final layer in the chain has a NULL based-on link. In case of conflict, attribute values set in upper layers (layers furthest from the layer with the NULL based-on link) override those set in lower layers. In rich text, additional formatting may be applied on top of these format layers.

The system of based-on links is implemented by the CFormatLayer class. It also implements persistence for chains of format layers.

When setting or sensing the attributes of a CParaFormatLayer or CCharFormatLayer, a format mask and container are specified as parameters. The container has data members for every format attribute, which may be set independently. When setting the layer, the mask indicates the attributes which will be taken from the container. Any attributes not specified in the mask will be taken from the system-provided default values.

When sensing a layer, on return, the mask indicates which attributes have been explicitly set in the layer, (i.e. not taken from the default values). In addition, a layer’s effective format may be sensed. In this case, no mask is used because the format container will, on return, contain a value for every attribute.

Derivation

CBase Base class for all classes to be instantiated on the heap CFormatLayer Abstract base class for the paragraph and character format layers (CParaFormatLayer and CCharFormatLayer)

Defined in CFormatLayer:
ChainCount(), ExternalizeChainL(), ExternalizeL(), InternalizeChainL(), InternalizeL(), IsEmpty(), IsIdentical(), Reset(), SenseBase(), SetBase()

Inherited from CBase:
operator new()

void SetBase(const CFormatLayer* aBaseFormatLayer);

Description

Sets the format layer which this layer's based-on link points to.

Parameters

const CFormatLayer* aBaseFormatLayer The format layer which this layer's based-on link points to. Specify NULL if this is the final layer in the chain (the layer on which all other layers are based).

const CFormatLayer* SenseBase()const;

Description

Gets the format layer which this layer's based-on link points to. If NULL, this layer is the final layer in the chain.

Return value

const CFormatLayer* The format layer on which this layer is based.

TInt ChainCount()const;

Description

Gets the number of format layers in the chain, inclusive of itself. Assumes that the format layer chain has been correctly set up to terminate with a NULL based-on link.

Return value

TInt The number of format layers in the chain, counting from the current layer.

virtual TBool IsIdentical(CFormatLayer* aLayer,TBool aCheckBasedOnLink=ETrue)const=0;

Description

Pure virtual function. Implementations of this function compare another format layer with the current object. For the two layers to be equal, they must have the same contents and (if the second parameter is ETrue), their based-on links must point to the same format layer.

Parameters

CFormatLayer* aLayer The layer to compare to this format layer. TBool aCheckBasedOnLink If ETrue, both layers' based-on links must point to the same format layer. If EFalse, the based-on links are not used in the comparison. By default, ETrue.

Return value

TBool ETrue if the two layers are identical, otherwise EFalse.

TBool IsEmpty()const;

Description

Tests whether any formatting is stored in the format layer.

Return value

TBool ETrue if no formatting is stored in the format layer, otherwise returns EFalse.

void Reset();

Description

Deletes the contents of the format layer. The based-on link is not affected.

virtual void ExternalizeL(RWriteStream& aStream)const=0;

Description

Pure virtual function. Implementations of this function externalise the format layer but not its based-on link to a write stream. The presence of this function means that the standard templatedoperator<<()(defined in s32strm.h) is available to externalise objects of the derived class.

Parameters

RWriteStream& aStream Stream to which the format layer should be externalised.

void ExternalizeChainL(RWriteStream& aStream,TInt aExcludeCount=0)const;

Description

Stores a chain of format layers. By default an entire chain is stored unless an exclude count is provided. In this case, the length of the chain stored is the ChainCount() minus the exclude count. The excluded layers are the ones starting with the layer with the NULL based-on link.

Note

The exclude count must be zero or greater but must be less than the total number of layers in the chain, otherwise a panic occurs.

Parameters

RWriteStream& aStream Stream to which the format layer chain should be externalised. TInt aExcludeCount The number of layers to be excluded. By default, zero.

virtual void InternalizeL(RReadStream& aStream,const CFormatLayer* aBase=NULL)=0;

Description

Pure virtual function. Implementations of this function internalise the format layer but not its based-on link from a read stream. The presence of this function means that the standard templated operator>>() (defined in s32strm.h) is available to internalise objects of the derived class. The internalised layer is set to be based on the layer specified.

Parameters

RReadStream& aStream Stream from which the format layer should be internalised. const CFormatLayer* aBase The based-on link to assign to the layer. By default, NULL.

void InternalizeChainL(RReadStream& aStream,const CFormatLayer* aBase=NULL);

Description

Restores a chain of format layers from a read stream. The layer at the end of the chain (the one furthest from this layer) is set to be based on the specified layer aBase, which may be NULL. This layer is set to be at the head of the restored chain (i.e. no other layers are based on it).

Parameters

RReadStream& aStream Stream from which the format layer chain should be internalised. const CFormatLayer* aBase The format layer at the end of the chain (furthest from this layer). May be NULL.