sl@0: /*
sl@0: * Copyright (c) 1997-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 __FLDBASE_H__
sl@0: #define __FLDBASE_H__
sl@0: 
sl@0: #include <e32std.h>
sl@0: #include <e32base.h>
sl@0: #include <s32stor.h>
sl@0: 
sl@0: // Classes defined:
sl@0: class CTextField;
sl@0: class MTextFieldFactory;
sl@0: 
sl@0: 
sl@0: 
sl@0: 
sl@0: class CTextField : public CBase
sl@0: /** 
sl@0: Abstract class: derive from this to instantiate a particular type of field (eg date etc)
sl@0: Abstract base class for all field types.
sl@0: 
sl@0: A field contains information which relates to a text object and can be automatically 
sl@0: updated, e.g. page number or current date and time. Fields must implement 
sl@0: the pure virtual functions defined in this class, including Value() which 
sl@0: should calculate and return the field's new value, and Type() which returns 
sl@0: the field's type UID. The type UID identifies the field type to the field 
sl@0: factory (see class MTextFieldFactory). 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 	{
sl@0: public:
sl@0: 	IMPORT_C virtual TStreamId StoreL(CStreamStore& aStore)const; // calls ExternalizeL()
sl@0: 	IMPORT_C virtual void RestoreL(const CStreamStore& aStore,TStreamId aId); // calls InternalizeL()
sl@0: 	//
sl@0: 	// Should be replaced by concrete derived classes.
sl@0: 	IMPORT_C virtual void ExternalizeL(RWriteStream& aStream)const; // Externalize state info for the field
sl@0:     /** Internalises the field data. Called by RestoreL().
sl@0: 	
sl@0: 	@param aStream Stream from which the field data should be internalised. */
sl@0: 	virtual void InternalizeL(RReadStream& aStream)=0;
sl@0: 	//
sl@0: 	/** Sets aValueText to the current field value if the buffer is large enough. If 
sl@0: 	not, aValueText is not changed, and the function returns the length which 
sl@0: 	is required to hold the field's value.
sl@0: 	
sl@0: 	@param aValueText Descriptor which on return contains the field's updated 
sl@0: 	value. 
sl@0: 	@return Zero on success, otherwise, the length of the buffer which is required 
sl@0: 	to hold the field's updated value. */
sl@0: 	virtual TInt Value(TPtr& aValueText)=0; 
sl@0: 	//	
sl@0: 	/** Returns the field's type UID.
sl@0: 	
sl@0: 	@return The field's type UID. */
sl@0: 	virtual TUid Type()const=0;
sl@0: 	};
sl@0: 
sl@0: 
sl@0:  
sl@0: 
sl@0: class MTextFieldFactory
sl@0: /** 
sl@0: Abstract class that should be derived from by any application that wishes to support fields
sl@0: Abstract base class for field factories.
sl@0: 
sl@0: To use fields in editable text,
sl@0: 
sl@0: 1) Define a field factory class (derived from MTextFieldFactory) that implements 
sl@0: NewFieldL().
sl@0: 
sl@0: 2) Create an instance of the field factory and set this to be the editable 
sl@0: text object's field factory (see CPlainText::SetFieldFactory(), or you can 
sl@0: specify a field factory in the text object 's NewL()).
sl@0: 
sl@0: 3) Create a new field (CPlainText::NewTextFieldL()), specifying the field 
sl@0: type UID (the built in field type UID values are defined in flddef.h). This 
sl@0: calls the factory's NewFieldL() function.
sl@0: 
sl@0: 4) Insert the field into the text object (CPlainText::InsertFieldL()).
sl@0: 
sl@0: 5) Evaluate the field (CPlainText::UpdateFieldL()) and then re-evaluate when 
sl@0: required. 
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 	{
sl@0: public:
sl@0: 	
sl@0: 	/** Implementations of this function should create a field of the type specified, 
sl@0: 	returning NULL if the field type is not recognised or supported.
sl@0: 	
sl@0: 	@param aFieldType The field's type UID. 
sl@0: 	@return Pointer to the new text field, or NULL if the factory does not recognise 
sl@0: 	or support the field type. */
sl@0: 	virtual CTextField* NewFieldL(TUid aFieldType)=0; 
sl@0: 	// Creates a field of the type specified
sl@0: 	// Returns NULL if it does not recognise/support the field type
sl@0: 	};
sl@0: 
sl@0: 
sl@0: #endif