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