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