sl@0: /*
sl@0: * Copyright (c) 2000-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: 
sl@0: 
sl@0: #ifndef __UNIFIED_EDITOR_H__
sl@0: #define __UNIFIED_EDITOR_H__ 1
sl@0: 
sl@0: #include <tagma.h>
sl@0: 
sl@0: #ifdef SYMBIAN_ENABLE_SPLIT_HEADERS
sl@0: #include <tagma_internal.h>
sl@0: #endif
sl@0: 
sl@0: /*
sl@0: The header file for MUnifiedEditor, an interface that unifies editing operations on backing text and layout,
sl@0: which are traditionally separated between ETEXT (backing text) and FORM (layout). It is not dependent
sl@0: on FORM or ETEXT, although there is an implementation (TFormAndTextEditor) using those components.
sl@0: */
sl@0: 
sl@0: /**
sl@0: Base class for optional interfaces
sl@0: @internalComponent
sl@0: */
sl@0: class MTmOptionalInterface
sl@0: 
sl@0: 	{
sl@0: 	};
sl@0: 
sl@0: /**
sl@0: UIDs for standard optional interfaces
sl@0: @internalComponent
sl@0: */
sl@0: const TUint KUidMUnifiedEditorStyleSupport = 0x100092B6;
sl@0: const TUint KUidMUnifiedEditorPictureSupport = 0x100092B7;
sl@0: const TUint KUidMUnifiedEditorFieldSupport = 0x100092B8;
sl@0: const TUint KUidMUnifiedEditorClipboardSupport = 0x100095EF;
sl@0: 
sl@0: /**
sl@0: An interface class for text editing.
sl@0: 
sl@0: An object that supports text editing has some backing text - zero or more Unicode characters - and
sl@0: character and paragraph formats applicable to ranges of these characters. A paragraph is a sequence of characters
sl@0: terminating either at the end of the document or after the next paragraph separator, whichever comes first.
sl@0: 
sl@0: The format for a given position is derived from up to three formatting layers. The base layer is the lowest and
sl@0: provides default attributes. These may be optionally overridden by attributes from a named style, and these in
sl@0: turn may be overridden by specific formatting. Text editing objects may support any or none of these layers; they
sl@0: may in fact ignore all attempts to set format attributes.
sl@0: @internalComponent
sl@0: */
sl@0: class MUnifiedEditor
sl@0: 
sl@0: 	{
sl@0: public:
sl@0: 	/**
sl@0: 	 * constants used when getting formats
sl@0: 	 */
sl@0: 	enum TFormatLevel
sl@0: 		{
sl@0: 		ESpecific,			// format applied by the user
sl@0: 		EEffective			// the actual format: a combination of base and specific formats
sl@0: 		};
sl@0: 	class MStyleSupport : public MTmOptionalInterface
sl@0: 	/**
sl@0: 	An optional interface to support styles
sl@0: 	@internalComponent
sl@0: 	*/
sl@0: 		{
sl@0: 	public:
sl@0: 		/**
sl@0: 		 * Creates a style.
sl@0: 		 */
sl@0: 		virtual TInt CreateStyleL(const RTmStyle& /*aStyle*/) { return KErrNotSupported; }
sl@0: 		/**
sl@0: 		 * Sets the attributes of a style.
sl@0: 		 */
sl@0: 		virtual TInt ChangeStyleL(const RTmStyle& /*aStyle*/) { return KErrNotSupported; }
sl@0: 		/**
sl@0: 		 * Applies the named style to the specified run of text.
sl@0: 		 */
sl@0: 		virtual TInt SetStyleL(TInt aPos, TInt aLength, const TDesC& aName) = 0;
sl@0: 		/**
sl@0: 		 * Renames a style.
sl@0: 		 */
sl@0: 		virtual TInt RenameStyleL(const TDesC& /*aOldName*/,const TDesC& /*aNewName*/) { return KErrNotSupported; }
sl@0: 		/**
sl@0: 		 * Deletes the named style.
sl@0: 		 */
sl@0: 		virtual TInt DeleteStyleL(const TDesC& /*aName*/) { return KErrNotSupported; }
sl@0: 		/**
sl@0: 		 * Get the number of named styles.
sl@0: 		 */
sl@0: 		virtual TInt StyleCount() const = 0;
sl@0: 		/**
sl@0: 		 * Gets the style set at the document position aPos. If no style is set
sl@0: 		 * there return an empty string and the run length over which no style
sl@0: 		 * applies.
sl@0: 		 */
sl@0: 		virtual void GetStyle(TInt aPos, TPtrC& aName, TInt& aRunLength) const = 0;
sl@0: 		/**
sl@0: 		 * Gets the attributes of a named style by completing aStyle from its
sl@0: 		 * name.
sl@0: 		 */
sl@0: 		virtual TInt GetStyleByNameL(const TDesC& aName, RTmStyle& aStyle) const = 0;
sl@0: 		/**
sl@0: 		 * Gets the name and attributes of a style by index; use this in
sl@0: 		 * conjunction with StyleCount to enumerate existing styles.
sl@0: 		 */
sl@0: 		virtual TInt GetStyleByIndexL(TInt aIndex, RTmStyle& aStyle) const = 0;
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	An optional interface to support embedded pictures
sl@0: 	@internalComponent
sl@0: 	*/
sl@0: 	class MPictureSupport : public MTmOptionalInterface
sl@0: 
sl@0: 		{
sl@0: 	public:
sl@0: 		/**
sl@0: 		 * Inserts a picture, passing ownership in.
sl@0: 		 */
sl@0: 		virtual void InsertPictureL(TInt aPos, const TPictureHeader& aPictureIn) = 0;
sl@0: 		/**
sl@0: 		 * Deletes picture character in the text at aPos, if any. Ownership of
sl@0: 		 * any picture is passed to the caller, therefore Picture(aPos,
sl@0: 		 * aPictureOut) must have been called previously, and
sl@0: 		 * aPictureOut.DeletePicture() must be called in the future to avoid a
sl@0: 		 * memory leak.
sl@0: 		 * If the character at aPos is a picture character, it will be deleted,
sl@0: 		 * regardless of whether or not a picture was actually attatched.
sl@0: 		 */
sl@0: 		virtual void DropPictureL(TInt aPos) = 0;
sl@0: 		/**
sl@0: 		 * Gets the picture if any at aPos. No picture is indicated by
sl@0: 		 * aPictureOut.iPictureType containing KUidNull.
sl@0: 		 * Ownership of the picture is retained. Note that aPictureOut is
sl@0: 		 * merely overwritten by this function: aPictureOut.DeletePicture() is
sl@0: 		 * NOT called!
sl@0: 		 */
sl@0: 		virtual void Picture(TInt aPos, TPictureHeader& aPictureOut) const = 0;
sl@0: 		};
sl@0: 
sl@0: 	/**
sl@0: 	An optional interface to support clipboard operations
sl@0: 	@internalComponent 
sl@0: 	*/
sl@0: 	class MClipboardSupport : public MTmOptionalInterface
sl@0: 	
sl@0: 		{
sl@0: 	public:
sl@0: 		/**
sl@0: 		 * Copy the text and formatting specified to the stream, updating
sl@0: 		 * the dictionary as appropriate.
sl@0: 		 */
sl@0: 		virtual void CopyToStoreL(CStreamStore& aStore, CStreamDictionary& aDictionary,
sl@0: 			TInt aPos, TInt aLength) const = 0;
sl@0: 		/**
sl@0: 		 * Insert text and formatting from the stream at aPos.
sl@0: 		 */
sl@0: 		virtual void PasteFromStoreL(const CStreamStore& aStore,
sl@0: 			const CStreamDictionary& aDictionary, TInt aPos) = 0;
sl@0: 		};
sl@0: 
sl@0: 	// VIRTUAL FUNCTIONS
sl@0: 
sl@0: 	// getters
sl@0: 
sl@0: 	/**
sl@0: 	 * Returns the optional interface with the specified UID, or 0 if it is not
sl@0: 	 * supported.
sl@0: 	 */
sl@0: 	virtual MTmOptionalInterface* Interface(TUint /*aId*/) { return NULL; }
sl@0: 	/**
sl@0: 	 * Returns the length of the document in characters, not including any
sl@0: 	 * notional final paragraph separator.
sl@0: 	 */
sl@0: 	virtual TInt DocumentLength() const = 0;
sl@0: 	/**
sl@0: 	 * Gets some text starting at aPos. The amount of text returned may be as
sl@0: 	 * much or as little as is convenient to the implementation, but must be
sl@0: 	 * at least one character. The text is raw Unicode text including any
sl@0: 	 * paragraph separators.
sl@0: 	 */
sl@0: 	virtual void GetText(TInt aPos,TPtrC& aText) const = 0;
sl@0: 	/**
sl@0: 	 * Gets the base character and paragraph formats
sl@0: 	 */
sl@0: 	virtual void GetBaseFormatL(TTmCharFormat& aCharFormat,RTmParFormat& aParFormat) const = 0;
sl@0: 	/**
sl@0: 	 * Gets the specific or effective character format and the run over which
sl@0: 	 * that format applies.
sl@0: 	 */
sl@0: 	virtual void GetCharFormat(TInt aPos,TFormatLevel aLevel,
sl@0: 							   TTmCharFormatLayer& aFormat,TInt& aRunLength) const = 0;
sl@0: 	/**
sl@0: 	 * Gets the specific or effective paragraph format and the run over which
sl@0: 	 * that format applies.
sl@0: 	 */
sl@0: 	virtual void GetParFormatL(TInt aPos,TFormatLevel aLevel,
sl@0: 							   RTmParFormatLayer& aFormat,TInt& aRunLength) const = 0;
sl@0: 
sl@0: 	// setters
sl@0: 
sl@0: 	/**
sl@0: 	 * Inserts text at aPos, optionally applying the specified character and
sl@0: 	 * paragraph formats. Unspecified attributes take the format at the
sl@0: 	 * insertion point; what this means in detail is implementation-dependent.
sl@0: 	 */
sl@0: 	virtual void InsertTextL(TInt aPos,const TDesC& aText,
sl@0: 							 const TDesC* aStyle = NULL,
sl@0: 							 const TTmCharFormatLayer* aCharFormat = NULL,
sl@0: 							 const RTmParFormatLayer* aParFormat = NULL) = 0;
sl@0: 	/**
sl@0: 	 * Deletes aLength characters starting at aPos.
sl@0: 	 */
sl@0: 	virtual void DeleteTextL(TInt aPos,TInt aLength) = 0;
sl@0: 	/**
sl@0: 	 * Sets the base character and paragraph formats
sl@0: 	 */
sl@0: 	virtual void SetBaseFormatL(const TTmCharFormat& aCharFormat,const RTmParFormat& aParFormat) = 0;
sl@0: 	/**
sl@0: 	 * Sets specific character attributes beginning at aPos for aLength characters.
sl@0: 	 */
sl@0: 	virtual void SetCharFormatL(TInt aPos,TInt aLength,const TTmCharFormatLayer& aFormat) = 0;
sl@0: 	/**
sl@0: 	 * Sets specific paragraph attributes beginning at aPos for aLength characters.
sl@0: 	 */
sl@0: 	virtual void SetParFormatL(TInt aPos,TInt aLength,const RTmParFormatLayer& aFormat) = 0;
sl@0: 	/**
sl@0: 	 * Deletes specific character attributes beginning at aPos for aLength characters.
sl@0: 	 */
sl@0: 	virtual void DeleteCharFormatL(TInt aPos,TInt aLength) = 0;
sl@0: 	/**
sl@0: 	 * Deletes specific paragraph attributes beginning at aPos for aLength characters.
sl@0: 	 */
sl@0: 	virtual void DeleteParFormatL(TInt aPos,TInt aLength) = 0;
sl@0: 
sl@0: 	// NON-VIRTUAL FUNCTIONS
sl@0: 	/**
sl@0: 	 * Reads text into a writable descriptor.
sl@0: 	 *
sl@0: 	 * @see GetText(TInt, TPtrC) const
sl@0: 	 */
sl@0: 	IMPORT_C void GetText(TInt aPos, TDes& aText) const;
sl@0: 	/**
sl@0: 	 * Returns the interface for manipulating styles, if applicable.
sl@0: 	 */
sl@0: 	inline MStyleSupport* StyleSupport();
sl@0: 	inline const MStyleSupport* StyleSupport() const;
sl@0: 	/**
sl@0: 	 * Returns the interface for manipulating pictures, if applicable.
sl@0: 	 */
sl@0: 	inline MPictureSupport* PictureSupport();
sl@0: 	inline const MPictureSupport* PictureSupport() const;
sl@0: 	/**
sl@0: 	 * Returns the interface for clipboard operations, if applicable.
sl@0: 	 */
sl@0: 	inline MClipboardSupport* ClipboardSupport();
sl@0: 	inline const MClipboardSupport* ClipboardSupport() const;
sl@0: 	};
sl@0: 
sl@0: // inline functions
sl@0: 
sl@0: MUnifiedEditor::MStyleSupport* MUnifiedEditor::StyleSupport()
sl@0: 	{
sl@0: 	return static_cast<MStyleSupport*>(Interface(KUidMUnifiedEditorStyleSupport));
sl@0: 	}
sl@0: 
sl@0: const MUnifiedEditor::MStyleSupport* MUnifiedEditor::StyleSupport() const
sl@0: 	{
sl@0: 	return static_cast<MStyleSupport*>(
sl@0: 		const_cast<MUnifiedEditor*>(this)->Interface(KUidMUnifiedEditorStyleSupport));
sl@0: 	}
sl@0: 
sl@0: MUnifiedEditor::MPictureSupport* MUnifiedEditor::PictureSupport()
sl@0: 	{
sl@0: 	return static_cast<MPictureSupport*>(Interface(KUidMUnifiedEditorPictureSupport));
sl@0: 	}
sl@0: 
sl@0: const MUnifiedEditor::MPictureSupport* MUnifiedEditor::PictureSupport() const
sl@0: 	{
sl@0: 	return static_cast<MPictureSupport*>(
sl@0: 		const_cast<MUnifiedEditor*>(this)->Interface(KUidMUnifiedEditorPictureSupport));
sl@0: 	}
sl@0: 
sl@0: MUnifiedEditor::MClipboardSupport* MUnifiedEditor::ClipboardSupport()
sl@0: 	{
sl@0: 	return static_cast<MClipboardSupport*>(Interface(KUidMUnifiedEditorClipboardSupport));
sl@0: 	}
sl@0: 
sl@0: const MUnifiedEditor::MClipboardSupport* MUnifiedEditor::ClipboardSupport() const
sl@0: 	{
sl@0: 	return static_cast<MClipboardSupport*>(
sl@0: 		const_cast<MUnifiedEditor*>(this)->Interface(KUidMUnifiedEditorClipboardSupport));
sl@0: 	}
sl@0: 
sl@0: #endif // __UNIFIED_EDITOR_H__