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