/*

* Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

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

* which accompanies this distribution, and is available

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

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

#ifndef __TXTFMLYR_H__

#define __TXTFMLYR_H__

#include <e32std.h>

#include <e32base.h>

#include <txtfmstm.h>

#include <txtfrmat.h>

// forward declarations

class CFormatStream;  

class RReadStream;

class RWriteStream;

class TCharFormatX;

#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS

#include <txtfmlyr_internal.h>

#endif

/** 

Abstract base class for the paragraph and character format layers.

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. 

@publishedAll

@released

*/

class CFormatLayer : public CBase

	{

public:

	//

	// Based-on link utilities

	IMPORT_C void Reset();  // Remove all contents of this layer in a leave safe manner.

	IMPORT_C void SetBase(const CFormatLayer* aBaseFormatLayer);  // Set this layer to be based on the specified layer.

	IMPORT_C const CFormatLayer* SenseBase()const;

	IMPORT_C TInt ChainCount()const;  // Returns the number of format layers in the chain, inclusive of itself.

	//

	// Persistence

	/** 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.

	@param aStream Stream from which the format layer should be internalised. 

	@param aBase The based-on link to assign to the layer. By default, NULL. */

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

	/** 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.

	@param aStream Stream to which the format layer should be externalised. */

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

	//

	//	Restore a format chain where the end of the chain is based on aBase (where aBase may be null).

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

	//	Stores a format layer chain of length length-aExcludeCount (or by default the whole chain).

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

	/** 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.

	@param aLayer The layer to compare to this format layer. 

	@param 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 ETrue if the two layers are identical, otherwise EFalse. */

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

	IMPORT_C TBool IsEmpty()const;

	void Swap(CFormatLayer& aLayer);

private:

	CFormatLayer(const CFormatLayer& aFormatLayer);

	CFormatLayer& operator=(const CFormatLayer& aFormatLayer);

	virtual CFormatLayer* DoCloneL()const=0;

protected:

	CFormatLayer();

	~CFormatLayer();

	virtual CFormatLayer* RestoreNewL(RReadStream& aStream)=0;

	void ExternalizeLayersRecurseL(RWriteStream& aStream,TInt aDescendantCount)const;

	TBool IsIdentical(const TUint8* aPtr,TInt aSize)const;

	const TUint8* Ptr(TInt& aSize)const;

	void CloneLayerL(CFormatLayer* aClone)const;

protected:

	RFormatStream iStore;

	const CFormatLayer* iBasedOn;  // If non-null used to inherit format attributes from the lower layer.

	__DECLARE_TEST;

	};

/** 

A paragraph format layer. 

Has a pointer (stored in its base class CFormatLayer) to another paragraph 

format layer which may be NULL. This pointer is referred to as the based-on 

link. A paragraph format layer is owned by an instance of the CGlobalText 

class and stores the object's global paragraph formatting. Implements persistence 

and allows attributes to be set and sensed. 

@publishedAll

@released

*/

class CParaFormatLayer : public CFormatLayer

	{

public:

	IMPORT_C static CParaFormatLayer* NewL();

	IMPORT_C static CParaFormatLayer* NewL(const CParaFormat* aParaFormat,const TParaFormatMask& aMask);

	IMPORT_C static CParaFormatLayer* NewL(RReadStream& aStream);

	static CParaFormatLayer* NewL(const CParaFormatLayer* aLayer);

	static CParaFormatLayer* NewCopyBaseL(const CParaFormatLayer* aLayer);

	// Create a new instance, restoring it from the specified stream.

	// The based on link is NULL. Restores only one layer.

	//

	// Persistence

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

	IMPORT_C virtual void ExternalizeL(RWriteStream& aStream)const;

	//

	// Core methods

	IMPORT_C void SetL(const CParaFormat* aDesiredEffectiveFormat,const TParaFormatMask& aMask);

	IMPORT_C void SenseEffectiveL(CParaFormat* aParaFormat,CParaFormat::TParaFormatGetMode aMode=CParaFormat::EAllAttributes)const;

	IMPORT_C void SenseL(CParaFormat* aParaFormat,TParaFormatMask& aMask,CParaFormat::TParaFormatGetMode aMode=CParaFormat::EAllAttributes)const;

	//

	// Utilities

	inline CParaFormatLayer* CloneL()const;

	IMPORT_C TBool IsIdenticalL(const CParaFormat* aParaFormat,const TParaFormatMask& aMask)const;

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

	IMPORT_C virtual TUid Type()const;

	IMPORT_C const TUint8* Ptr(TInt& aSize)const;

private:

	//

	// No implementation provided

	CParaFormatLayer(const CParaFormatLayer& aParaFormatLayer);

	CParaFormatLayer& operator=(const CParaFormatLayer& aParaFormatLayer);

	IMPORT_C virtual CFormatLayer* DoCloneL()const;

	void FillParaFormatL(CParaFormat* aParaFormat,TParaFormatMask& aMask,CParaFormat::TParaFormatGetMode aMode)const;

	void CleanupEffectiveFormat(CParaFormat* aParaFormat,TParaFormatMask aMask)const;

	void CleanupBorders(CParaFormat* aParaFormat)const;

protected:

	CParaFormatLayer();

	virtual CFormatLayer* RestoreNewL(RReadStream& aStream);

	};

/** 

Character format layer.

Uses a pointer (stored in its base class CFormatLayer) to another character 

format layer which may be NULL. This pointer is referred to as the based-on 

link. A character format layer is owned by an instance of the CGlobalText 

class and stores the object's global character formatting. Implements persistence 

and allows attributes to be set and sensed. 

@publishedAll

@released

*/

class CCharFormatLayer : public CFormatLayer

	{

public:

	IMPORT_C static CCharFormatLayer* NewL();

	IMPORT_C static CCharFormatLayer* NewL(const TCharFormat& aFormat,const TCharFormatMask& aMask);

	IMPORT_C static CCharFormatLayer* NewL(RReadStream& aStream);

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

	IMPORT_C virtual void ExternalizeL(RWriteStream& aStream)const;

	IMPORT_C void SetL(const TCharFormat& aCharFormat,const TCharFormatMask& aMask);

	IMPORT_C void SenseEffective(TCharFormat& aCharFormat)const;

	IMPORT_C void Sense(TCharFormat& aCharFormat,TCharFormatMask& aMask)const;

	inline CCharFormatLayer* CloneL()const;

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

	IMPORT_C TBool IsIdentical(const TCharFormat& aCharFormat,const TCharFormatMask& aMask)const;

	IMPORT_C const TUint8* Ptr(TInt& aSize)const;

	// non-exported public functions

	static CCharFormatLayer* NewL(const CCharFormatLayer* aLayer);

	static CCharFormatLayer* NewCopyBaseL(const CCharFormatLayer* aLayer);

	static CCharFormatLayer* NewL(const TCharFormatX& aFormat,const TCharFormatXMask& aMask);

	void SetL(const TCharFormatX& aCharFormat,const TCharFormatXMask& aMask);

	void SenseEffective(TCharFormatX& aCharFormat)const;

	void Sense(TCharFormatX& aCharFormat,TCharFormatXMask& aMask) const;

private:

	CCharFormatLayer();

	virtual CFormatLayer* RestoreNewL(RReadStream& aStream);

	virtual void FillCharFormat(TCharFormatX& aCharFormat,TCharFormatXMask& aMask)const;

	IMPORT_C virtual CFormatLayer* DoCloneL()const;

	};

#include <txtfmlyr.inl>

#endif