sl@0: /*
sl@0: * Copyright (c) 2003-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 __TXTLAYDC_H__
sl@0: #define __TXTLAYDC_H__
sl@0: 
sl@0: #include <e32std.h>
sl@0: 
sl@0: class CParaFormat;
sl@0: class TCharFormat;
sl@0: class CPicture;
sl@0: 
sl@0: 
sl@0: class MLayDoc
sl@0: /** 
sl@0: Specifies the interface for providing the information needed by the text 
sl@0: layout engine to lay out a text object. 
sl@0: 
sl@0: Examples of derived classes are CRichText and CGlobalText.
sl@0: 
sl@0: At the heart of the interface are two interrogation functions; one gives the 
sl@0: paragraph formatting for a document position, and the other gives a pointer 
sl@0: descriptor to a series of contiguous characters with identical character 
sl@0: formatting, and their character formatting. This information is sufficient 
sl@0: for the layout engine to find the formatting and content of an entire document.
sl@0: 
sl@0: The constructor for the layout engine (CTextLayout) is prototyped as:
sl@0: static CTextLayout *NewL(MLayDoc *aDoc,TInt aWrapWidth);
sl@0: By viewing the text object purely in terms of the MLayDoc interface, the layout 
sl@0: engine is insulated from any editable text implementation issues.
sl@0: @see static CTextLayout *NewL(MLayDoc *aDoc,TInt aWrapWidth)
sl@0: @publishedAll
sl@0: @released
sl@0: */
sl@0: 	{
sl@0: 	// Defines interface for extracting content & format information from text source.
sl@0: 	// Designed to be 'mixed-in' with other classes.
sl@0: 	//
sl@0: public:
sl@0: 	
sl@0: 	/** Used as a parameter to the PictureHandleL() function to control whether 
sl@0: 	picture data should be loaded into memory or not. */
sl@0: 	enum TForcePictureLoad 
sl@0: 		{
sl@0: 		/** Do not load the picture data into memory. */
sl@0: 		EForceLoadFalse,
sl@0: 		/** Load the picture data into memory. */
sl@0: 		EForceLoadTrue
sl@0: 		};
sl@0: public:
sl@0: 		
sl@0: 	/** Gets the the number of characters in the document.
sl@0: 	
sl@0: 	@return The number of characters contained in the document. */
sl@0: 	virtual TInt LdDocumentLength()const=0;  // Does not include final document terminator
sl@0: 
sl@0: 	/** Gets the document position of the start of the paragraph containing a 
sl@0: 	specified position.
sl@0: 	
sl@0: 	@param aCurrentPos A valid document position. On return contains the 
sl@0: 	document position of the first character in the paragraph. 
sl@0: 	@return The number of characters skipped in scanning to the start of the 
sl@0: 	paragraph. */
sl@0: 	virtual TInt LdToParagraphStart(TInt& aCurrentPos)const=0;
sl@0: 		
sl@0: 	/** Gets the effective paragraph formatting which applies to the paragraph 
sl@0: 	which contains a specified document position. On return, aFormat is filled 
sl@0: 	with values for all paragraph format attributes.
sl@0: 	
sl@0: 	@param aFormat On return, filled with the paragraph's effective paragraph 
sl@0: 	formatting. 
sl@0: 	@param aPos Any document position within the paragraph of interest. */
sl@0: 	virtual void GetParagraphFormatL(CParaFormat* aFormat,TInt aPos)const=0;
sl@0: 	
sl@0: 	/** Gets a constant pointer descriptor to a portion of the text object with 
sl@0: 	constant character formatting. The view starts at the document position 
sl@0: 	specified, and ends at: 
sl@0: 	
sl@0: 	the last character which shares the same character formatting (rich text 
sl@0: 	only), or
sl@0: 	
sl@0: 	the end of the document, or
sl@0: 	
sl@0: 	the end of the segment, if segmented storage is being used
sl@0: 	
sl@0: 	whichever occurs first. 
sl@0: 	
sl@0: 	Also fills a character format object with the character formatting of the 
sl@0: 	range of characters.
sl@0: 	
sl@0: 	@param aView On return, a constant pointer to a portion of the text. 
sl@0: 	@param aFormat On return, contains the character formatting of the text. 
sl@0: 	@param aStartPos The start position for the view. Must be a valid document 
sl@0: 	position, or a panic occurs. */
sl@0: 	virtual void GetChars(TPtrC& aView,TCharFormat& aFormat,TInt aStartPos)const=0;	
sl@0: 
sl@0: 	/** Gets the size of a picture located at a specified document position.
sl@0: 	
sl@0: 	Note: The global text implementation of this function always returns 
sl@0: 	KErrNotFound because global text does not support pictures.
sl@0: 	
sl@0: 	@param aSize On return, contains the size of the picture located at aPos.
sl@0: 	@param aPos Document position of the picture. 
sl@0: 	@return KErrNotFound if there is no picture at the specified document 
sl@0: 	position, KErrNone if there is. */
sl@0: 	virtual TInt GetPictureSizeInTwips(TSize& aSize, TInt aPos)const=0;
sl@0: 
sl@0: 	/** Gets a pointer to the picture located at a specified document position, 
sl@0: 	if one exists. If the picture is not in memory, the function loads it (if 
sl@0: 	the second argument has a value of EForceLoadTrue).
sl@0: 	
sl@0: 	Note: The global text implementation of this function always returns NULL 
sl@0: 	because global text does not support pictures.
sl@0: 	
sl@0: 	@param aPos Document position of the picture character. 
sl@0: 	@param aForceLoad If the picture is not loaded into memory, EForceLoadTrue 
sl@0: 	loads it using the picture factory; EForceLoadFalse does not, and in this 
sl@0: 	case, the function returns NULL. 
sl@0: 	@return A pointer to the picture located at aPos. NULL if aPos does not 
sl@0: 	specify a picture character, or if there is a picture at aPos which is not 
sl@0: 	in memory, and the second argument is EForceLoadFalse. */
sl@0: 	virtual CPicture* PictureHandleL(TInt aPos,TForcePictureLoad aForceLoad=EForceLoadTrue)const=0;
sl@0: 
sl@0: 	/** Tests whether a page break occurs within a range of characters. A page 
sl@0: 	table should have been set up first: see CPlainText::SetPageTable().
sl@0: 	
sl@0: 	@param aPos The document position from which to begin searching for a page 
sl@0: 	break.
sl@0: 	@param aLength The number of characters to search for a page break, 
sl@0: 	beginning at aPos. The default is zero. 
sl@0: 	@return ETrue if a page break occurs within the specified range, otherwise 
sl@0: 	EFalse. */
sl@0: 	virtual TBool EnquirePageBreak(TInt aPos,TInt aLength=0)const=0;
sl@0: 	
sl@0: 	/** This function should be implemented by text objects which support 
sl@0: 	paragraph labels. Each paragraph may have at most one label. By default, 
sl@0: 	the functions provided by MLayDoc apply to the main body of text. This 
sl@0: 	function is provided to change this so that the MLayDoc object is an 
sl@0: 	individual paragraph label, (each of which is treated as a separate 
sl@0: 	document). Paragraph labelling has not been implemented by global or rich 
sl@0: 	text.
sl@0: 	
sl@0: 	This function should select the paragraph label associated with the 
sl@0: 	paragraph containing document position aPos (aPos is a document position 
sl@0: 	in the main document).
sl@0: 	
sl@0: 	@param aPos A document position within a paragraph. This paragraph's label 
sl@0: 	should be set as the main MLayDoc document. 
sl@0: 	@return Should return EFalse if the paragraph has no label, in which case 
sl@0: 	the function has no effect, ETrue otherwise. */
sl@0: 	virtual TBool SelectParagraphLabel(TInt aPos)=0;
sl@0: 
sl@0: 	/** Cancels a paragraph label selection made by a call to 
sl@0: 	SelectParagraphLabel() so that the main document reverts back to the main 
sl@0: 	body of text. */
sl@0: 	virtual void CancelSelectLabel()=0;
sl@0: 	
sl@0: 	/** This function is reserved for future purpose.
sl@0: 	It should not be used externally for now.
sl@0: 	@internalAll */
sl@0: 	IMPORT_C virtual void MLayDoc_Reserved_1();
sl@0: 	};
sl@0: 
sl@0: #endif
sl@0: