/*

* Copyright (c) 1997-2009 Nokia Corporation and/or its subsidiary(-ies).

* All rights reserved.

* This component and the accompanying materials are made available

* under the terms of "Eclipse Public License v1.0"

* which accompanies this distribution, and is available

* at the URL "http://www.eclipse.org/legal/epl-v10.html".

*

* Initial Contributors:

* Nokia Corporation - initial contribution.

*

* Contributors:

*

* Description: 

*

*/

#ifndef __FRMTLAY_H__

#define __FRMTLAY_H__

#include <e32std.h>

#include <e32base.h>

#include <gdi.h>

#include <txtfrmat.h>

#include <txtetext.h>

#include <frmlaydt.h>

#include <frmparam.h>

#include <frmvis.h>

#include <tagma.h>

class CWindowGc;

class MLayDoc;

class TLayDocTextSource;

class TCursorPosition;

class TLayDocTextSource;

class CTmTextLayout;

class TTmHighlightExtensions;

class MTmSource;

class TTmFormatParamBase;

#ifndef SYMBIAN_ENABLE_SPLIT_HEADERS

#include <frmtlay_internal.h>

#endif

/**

This interface class defines an interface for clients of Form to provided 

implementations of customisation interfaces relating to the source text

document as requried by the internals of Form and Tagma. Its use by

Form clients is optional.

Derived objects of this interface are registered with the CTextLayout 

API and are called from the TLayDocTextSource class at present.

@publishedAll

@released

@see MTmInlineTextSource

*/

class MFormCustomInterfaceProvider

    {

    public:

	/**

	Form uses this method to request an interface implmentation for the

	specified interface Uid. See class description for interfaces covered

	by this API.

	@param aInterfaceId

		The unique identifier for the interface wanted by Form.

	@return 

		Ptr to interface instance or 0 if not supported by client

	*/

	virtual TAny* GetExtendedInterface(const TUid& aInterfaceId) = 0;

    };

/** Parameter used to control which part of a line (top, baseline or bottom) 

should be scrolled to a certain vertical position in a view rectangle. Used 

as a parameter in functions like CTextView::HandleGlobalChangeL() and 

CTextLayout::SetViewL(). The selected part of the line is called the hotspot.

@publishedAll

@released

*/

class TViewYPosQualifier

	{

friend class CTextLayout;

friend class CTextView;

public:

	/** Which part of a line (top, baseline or bottom) should appear at a

	vertical pixel position. */

	enum TPartOfLine

		{

		/** The top pixel is placed at the specified vertical point. */

		EFViewTopOfLine = 1,

		/** The baseline is placed at the specified vertical point. */

		EFViewBaseLine = 0,

		/** The bottom pixel is placed at the specified vertical point. */

		EFViewBottomOfLine = 2	

		};

	/** Whether the top line in the view should be fully visible. */

	enum TFullyVisible

		{

		/** Force a partially visible top line to be fully visible. */

		EFViewForceLineFullyVisible = ETrue,

		/** Do not force a partially visible top line to be fully visible. */

		EFViewDontForceLineFullyVisible = EFalse

		};

public:

	inline TViewYPosQualifier();

	IMPORT_C void SetHotSpot(TPartOfLine aHotSpot);

	IMPORT_C void SetFillScreen(TBool aFillScreen = ETrue);

	IMPORT_C void SetMakeLineFullyVisible(TFullyVisible aMakeLineFullyVisible = EFViewForceLineFullyVisible);

private:

	TPartOfLine iHotSpot;

	TBool iFillScreen;

	TFullyVisible iFullyVisible;

	};

/** 

A structure used to return the results of a reformatting operation.

@see CTextLayout::HandleBlockChangeL()

@publishedAll

@released

*/

class TViewRectChanges

	{

public:

	inline TViewRectChanges();

public:

	/** The vertical coordinate of the top of the first line of reformatted 

	text. */

	TInt iFormattedFrom;

	/** The vertical coordinate of the bottom of the last line of reformatted 

	text. */

	TInt iFormattedTo;

	/** The number of pixels by which text above the reformatted or edited 

	block has scrolled (positive values mean the text moved down). */

	TInt iScrollAtTop;

	/** The number of pixels by which text below the reformatted or edited 

	block has scrolled (positive values mean the text moved down). */

	TInt iScrollAtBottom;

	};

/** 

The cursor or cursor selection within a document.

If the cursor and anchor position differ, the selection covers the text from

the lower to the higher position, not including the character after the higher

position. If the selection is changed (by shift plus arrow keys in many UIs)

the cursor position changes and the anchor remains the same. 

@publishedAll

@released

*/

class TCursorSelection

	{

public:

	inline TCursorSelection();

	inline TCursorSelection(TInt aCursorPos,TInt aAnchorPos);

	inline void SetSelection(TInt aCursorPos,TInt aAnchorPos);

	inline TInt LowerPos() const;

	inline TInt HigherPos() const;

	inline TInt Length() const;

public:

	/** The cursor position. */

	TInt iCursorPos;

	/** The anchor position. */

	TInt iAnchorPos;

	};

/** 

Parameters used by functions that draw text.

An object of this class is passed to CTextLayout::DrawL() and to

InvertRangeL(). The draw context includes the view rectangle, the graphics

context, the background colour and the margin widths.

You only need to use this class directly when you are using a CTextLayout

object which is not owned by a CTextView object.

@publishedAll

@released

*/

class TDrawTextLayoutContext

	{

private:

	enum TDrawMode

		{

		EFDrawText=0x001,

		EFDrawGraphics=0x002,

		EFUseClippingRect=0x004,

		EFUseWindowGc=0x008,

		EFUseGcClear=0x020,

		EFUseBackgroundColor=0x040,

		EFUseOverrideTextColor=0x080,

		EFParagraphFillTextOnly=0x100,

		EFAllFlags=0xfff

		};

public:

	IMPORT_C TDrawTextLayoutContext();

	IMPORT_C void SetGc(CGraphicsContext* aGc,CGraphicsContext* aPictureGc=NULL);

	IMPORT_C void SetBitmapGc(CBitmapContext* aGc,CBitmapContext* aPictureGc=NULL);

	IMPORT_C void SetWindowGc(CWindowGc* aGc,CWindowGc* aPictureGc=NULL);

	IMPORT_C void SetDrawToEveryPixel(TBool aDrawToEveryPixel);

	IMPORT_C void SetTextColorOverride(const TRgb *aOverrideColor);

	IMPORT_C void SetDrawTextOnly();

	IMPORT_C void SetDrawGraphicsOnly();

	IMPORT_C void SetDrawTextAndGraphics();

	IMPORT_C void SetClipping(TBool aClipping);

	// deprecated 7.0 

	IMPORT_C void SetParagraphFillTextOnly(TBool aFillTextOnly);

//Enquiry functions

	IMPORT_C const TRgb* TextOverrideColor() const;

	IMPORT_C CGraphicsContext* PrimaryGc() const;

	IMPORT_C CGraphicsContext* PictureGc() const;

	IMPORT_C TBool UseClippingRect() const;

	IMPORT_C TBool UseGcClear() const;

	IMPORT_C TBool DrawText() const;

	IMPORT_C TBool DrawGraphics() const;

	IMPORT_C TBool UseBackgroundColor() const;

	// deprecated 7.0

	IMPORT_C TBool ParagraphFillTextOnly() const;

//Physical dimensions

	IMPORT_C TRect TextArea() const;

	IMPORT_C TInt DisplayHeight() const;

	IMPORT_C TPoint TopLeftTextArea() const;

	IMPORT_C TRect TotalMargin() const;

	IMPORT_C TRect LabelMargin() const;

	IMPORT_C TBool IsLabelMargin() const;

	IMPORT_C TRect GutterMargin() const;

	IMPORT_C TBool IsGutterMargin() const;

	IMPORT_C TPoint TopLeftText() const;

	IMPORT_C void WindowToText(TPoint& aWinPos) const;

	IMPORT_C void WindowToText(TRect& aRect) const;

	IMPORT_C void TextToWindow(TPoint& aTextAreaPos) const;

	IMPORT_C void TextToWindow(TRect& aRect) const;

	TBool UseWindowGc() const;

	void SetDrawMode(TUint aDrawMode);

	TUint DrawMode() const;

public:

	/** The view rectangle (specified in window coordinates). This is used to 

	set the	area in which text can be drawn. Text can only be drawn within the 

	intersection between the text area and the aDrawRect parameter passed to 

	CTextLayout::DrawL() or InvertRangeL(). */

	TRect iViewRect;

	/** The label margin width. By default zero. Must have the same value as 

	the label margin width as set in the text layout object. */

	TInt iLabelMarginWidth;

	/** The gutter margin width (also known as the line cursor margin width). 

	By default	zero. */

	TInt iGutterMarginWidth;

	/** The horizontal offset between window coordinates and text layout 

	coordinates. */

	TInt iTextStartX;

	/** The background colour for the view rectangle. The background colour is 

	used to fill the parts of the view rectangle in which text cannot appear, 

	for example, below the last line of the document and in the label, line 

	cursor and left	text margins. */

	TLogicalRgb iBackgroundColor;

private:

	CGraphicsContext* iGc;

	CGraphicsContext* iPictureGc;

	TLogicalRgb iOverrideTextColor;

	TUint iDrawMode;

	};

/** 

An abstract class which specifies the protocol for customising the way text

and its background are drawn.

Common uses for this are to implement custom highlighting or to draw a 

background bitmap. You must create an object of a class derived from this class 

and call CTextLayout::SetCustomDraw(), passing a pointer to the object. All of 

these functions have default implementations. Your class can override any of the

virtual functions listed below.

@publishedAll

@released

*/

class MFormCustomDraw

	{

	public:

	class TParam

	/**

	Parameters used by several custom draw functions

	@publishedAll

	@released

	*/

			{

		public:

		TParam(CGraphicsContext& aGc,MGraphicsDeviceMap& aMap,const TPoint& aTextLayoutTopLeft,const TRect& aDrawRect):

			iGc(aGc), iMap(aMap), iTextLayoutTopLeft(aTextLayoutTopLeft), iDrawRect(aDrawRect) { }

		CGraphicsContext& iGc;

		MGraphicsDeviceMap& iMap;

		const TPoint& iTextLayoutTopLeft;

		const TRect& iDrawRect;

		};

	class TLineInfo

	/** 

	Contains the line metrics.

	@publishedAll

	@released

	*/

			{

		public:

		TLineInfo(const TRect& aOuterRect,const TRect& aInnerRect,TInt aBaseline):

			iOuterRect(aOuterRect), iInnerRect(aInnerRect), iBaseline(aBaseline) { }

		const TRect& iOuterRect;

		const TRect& iInnerRect;

		TInt iBaseline;

		};

	IMPORT_C virtual void DrawBackground(const TParam& aParam,const TRgb& aBackground,TRect& aDrawn) const;

	IMPORT_C virtual void DrawLineGraphics(const TParam& aParam,const TLineInfo& aLineInfo) const;

	IMPORT_C virtual void DrawText(const TParam& aParam,const TLineInfo& aLineInfo,const TCharFormat& aFormat,

								   const TDesC& aText,const TPoint& aTextOrigin,TInt aExtraPixels) const;

	IMPORT_C virtual TRgb SystemColor(TUint aColorIndex,TRgb aDefaultColor) const;

	IMPORT_C virtual void DrawText(const TParam& aParam,const TLineInfo& aLineInfo,const TCharFormat& aFormat,

								   const TDesC& aText,const TInt aStart, const TInt aEnd, const TPoint& aTextOrigin,TInt aExtraPixels) const;

	IMPORT_C virtual void MFormCustomDraw_Reserved_2();

	};

/** 

An interface class that can be derived from to implement custom line breaking.

Custom line breaking allows the Text Views line wrapping algorithm to break

lines in any way. For instance, it may be used to avoid the jagged white space

at the right edge of text windows caused by normal line wrapping on a small

screen.

All of these functions have a default implementation. To change the default

behaviour, a pointer to an object that overrides any or all of the functions

in the interface needs to be passed to the function CTextLayout::SetCustomWrap().

@since 6.2

@see CTextLayout::SetCustomWrap()

@publishedAll

@released

*/

class MFormCustomWrap

	{

public:

	IMPORT_C virtual TUint LineBreakClass(TUint aCode,TUint& aRangeStart,TUint& aRangeEnd) const;

	IMPORT_C virtual TBool LineBreakPossible(TUint aPrevClass,TUint aNextClass,TBool aHaveSpaces) const;

	IMPORT_C virtual TBool GetLineBreakInContext(const TDesC& aText,TInt aMinBreakPos,TInt aMaxBreakPos,

												 TBool aForwards,TInt& aBreakPos) const;

	IMPORT_C virtual TBool IsHangingCharacter(TUint aChar) const;

private:

	IMPORT_C virtual void MFormCustomWrap_Reserved_1();

	IMPORT_C virtual void MFormCustomWrap_Reserved_2();	

	};

/** 

Mixin class used to customize visible appearance of invisible characters 

such as a paragraph mark or a tab.

@see CTextView::SetCustomInvisibleCharacterRemapper()

@publishedAll

@released

*/

class MFormCustomInvisibleCharacterRemapper

	{

public:

	IMPORT_C static TUint DefaultMapping(TUint aChar, const TNonPrintingCharVisibility aNonPrintingCharVisibility, const TLayDocTextSource& aLayDoc);

	/** 

	Allows custom remapping of invisible characters.

	Called by TLayDocTextSource::Map() if it has been created and registered 

	with TLayDocTextSource using CTextLayout::SetInvisibleCharacterRemapper().

	Unless there is a specific reason for doing otherwise it is recommended 

	that where this function has not remapped a given character it should 

	pass it to DefaultMapping() to let it try.

	@param aChar

		Invisible character to be remapped

	@param aDesiredVisibilities

		Current state of flags showing visibility of invisible characters

	@param aLayDoc

		Const ref to the calling CLayDocTextSource

	@return

		The replacement character if remapping has taken place, else return original character

	*/

	virtual TUint Remap(TUint aChar, const TNonPrintingCharVisibility aNonPrintingCharVisibility, const TLayDocTextSource& aLayDoc) = 0;

	};

/** 

Text layout.

CTextLayout is the lowest-level text formatting class in the Text Views API. It

obtains text and formatting attributes via the MLayDoc interface class and

formats the text to a certain width.

It has functions for drawing the text and performing hit-detection that is,

converting x-y coordinates to document positions, and vice versa. It defines

many public functions that are not generally useful, but are called by the

higher-level CTextView class, or exist only for the convenience of closely

associated classes like the printing and pagination systems. These are

identified in the documentation by the text "not generally useful".

When using the CTextLayout class, you must be aware of what functions have

previously been called. For example:

1) Formatting and scrolling functions must not be called if a CTextView object

owns the CTextLayout object, because the CTextView object may be reformatting

the CTextLayout object asynchronously by means of an active object, or may hold

some state information about the CTextLayout object that would be invalidated

by reformatting. These functions are identified in the documentation by the

text "Do not use if a CTextView object owns this CTextLayout object.".

2) Functions that raise out of memory exceptions can leave the object in an

inconsistent state; these functions can be identified as usual by their

trailing L. When this occurs, it is necessary to discard the formatting

information by calling DiscardFormat().

3) Some functions change formatting parameters like the wrap width or band

height, but do not reformat to reflect the change. These functions are

identified in the documentation by the text "Reformat needed". 

@publishedAll

@released

*/

class CTextLayout: public CBase

	{

friend class CTestTextLayout;

public:

	/**Flags used by CTextLayout::SetViewL(). Whether to reformat and redraw.*/

	enum TDiscard

		{

		/** Discard all formatting; redraw. */

		EFViewDiscardAllFormat = TRUE,

		/** Do not discard all formatting; redraw. */

		EFViewDontDiscardFormat = FALSE

		};

	/** Indicates whether blank space should scroll.

	Used by several CTextView and CTextLayout scrolling functions. */

	enum TAllowDisallow

		{

		/** Allow blank space to scroll. */

		EFAllowScrollingBlankSpace = TRUE,

		/** Disallow blank space from scrolling. */

		EFDisallowScrollingBlankSpace = FALSE

		};

	enum									// flags for HandleCharEditL

		{

		/** Insert a character, (not a paragraph delimiter). */

		EFCharacterInsert,

		/** Insert a paragraph delimiter. */

		EFParagraphDelimiter,

		/** Delete single character to the left. */

		EFLeftDelete,

		/** Delete single character to the right. */

		EFRightDelete

		};

	enum

		{

		/** A value greater than any possible display height indicates that the

		entire visible area, at least, was scrolled, and so there is no point

		in blitting text; a full redraw is needed.

		 */

		EFScrollRedrawWholeScreen = CLayoutData::EFLargeNumber,

		/** The maximum line width when wrapping is unset. */

		EFMaximumLineWidth = CLayoutData::EFBodyWidthForNoWrapping,

		};

	enum

		{

		/** Wrapping off; overrides the paragraph format. */

		EFAllParagraphsNotWrapped = TRUE,

		/** Wrapping on, unless CParaFormat::iWrap is false. */

		EFParagraphsWrappedByDefault = FALSE

		};

	/** Amount to format. Used by CTextLayout::SetAmountToFormat(). */

	enum TAmountFormatted

		{

		/** Format the whole document. */

		EFFormatAllText = FALSE,

		/** Format the visible band only. */

		EFFormatBand = TRUE,

		};

	enum TScrollFlags

		{

		EFScrollOnlyToTopsOfLines = 1

		};

	/** Formatting information. */

	enum TCurrentFormat

		{

		 /** Returned by some CTextLayout enquiry functions to indicate that no

		formatting has taken place so that the requested value cannot be

		calculated. */

		EFNoCurrentFormat = -1,

		/** Returned by CTextLayout::ParagraphHeight() when the paragraph is not formatted. */

		EFNotInCurrentFormat = 0

		};

public:

	class TRangeChange

	/** 

	Specifies the range of characters involved when setting or clearing a

	text selection.

	This class is used in the CTextLayout::Highlight() function. The following

	code demonstrates how it should be used to clear an existing highlight and

	set a new one:

	@code 

	CTextLayout::TRangeChange oldHighlight(anchorPos, old_cursorPos,

	CTextLayout::TRangeChange::EClear); // existing highlight