/*
* Copyright (c) 2006-2007 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: Definition of CHuiTextVisual. CHuiTextVisual is a visual
* that draws text.
*
*/
#ifndef __HUITEXTVISUAL_H__
#define __HUITEXTVISUAL_H__
#include <e32base.h>
#include <AknsItemID.h>
#include <uiacceltk/HuiVisual.h>
#include <uiacceltk/HuiSkin.h>
#include <uiacceltk/HuiGc.h>
/* Forward declarations. */
class CHuiControl;
class CHuiTextMesh;
class THuiTextStyle;
class CAknPictographInterface;
class CHuiPictographAnimator;
/**
* Text visual shows one or more lines of text.
*
* @todo Escape sequences for formatting (font, colors) will be supported.
* @todo Changing text style with escape sequences.
*/
NONSHARABLE_CLASS(CHuiTextVisual) : public CHuiVisual
{
public:
/* Types. */
enum TLineWrap
{
/** Lines must be broken manually with line break characters.
If the visual does not use clipping, long text lines will
go outside the visual. This is the default mode. */
ELineWrapManual,
/** Lines that do not fit in the visual's content area are truncated
with an ellipsis (...). */
ELineWrapTruncate,
/** Lines are broken to the visual's content area. */
ELineWrapBreak
};
enum TLineSpacingUnits
{
/** Line spacing is given in pixels */
EPixels,
/** Line spacing is given in twips */
ETwips
};
/* Constructors and destructor. */
/** @beginAPI */
/**
* Constructs and appends a new text visual to the owner control.
*
* @param aOwnerControl Control that will own the new visual.
*
* @return The new visual.
*/
IMPORT_C static CHuiTextVisual* AddNewL(CHuiControl& aOwnerControl,
CHuiLayout* aParentLayout = 0);
/** @endAPI */
/**
* Constructor.
*/
CHuiTextVisual(MHuiVisualOwner& aOwner);
/**
* Second-phase constructor.
*/
void ConstructL();
/**
* Destructor.
*/
virtual ~CHuiTextVisual();
/* Methods. */
/** @beginAPI */
/**
* Set the text shown in the visual. The text may contain formatting
* codes to change the size, color, and alignment of the text.
*
* @param aText Descriptor containing the text.
*/
IMPORT_C void SetTextL(const TDesC& aText);
/**
* Returns the text of the visual.
*/
IMPORT_C const TDesC& Text() const;
/**
* Sets the alignment of the text visual.
*/
IMPORT_C void SetAlign(THuiAlignHorizontal aAlignHorizontal,
THuiAlignVertical aAlignVertical);
/**
* Sets the line spacing for multiline text visual when the text wraps around.
*
* @param aLineSpacing Line spacing between lines in multiline text visual.
* @parem aUnits Defines the units of the line spacing.
* @see TLineSpacingUnits.
*/
IMPORT_C void SetLineSpacing(TInt aLineSpacing, TLineSpacingUnits aUnits = EPixels);
/**
* Sets the default text style of the text visual. This style describes the size
* and color of the rendered text.
*
* @param aStyle Text style.
* @param aBackgroundType Text background type. Affects the color of
* the text. Defaults to EHuiBackgroundTypeLight
* (ie, black text will be used).
*/
IMPORT_C void SetStyle(THuiPreconfiguredTextStyle aStyle,
THuiBackgroundType aBackgroundType = EHuiBackgroundTypeLight);
/**
* Sets the default text style of the text visual. This style describes the style
* the text is rendered with. The text style has to be created with the text style
* manager. If the given text style does not exist, the text style is reverted back
* to default text style.
* @see CHuiTextStyleManager
*
* @param aTextStyleId Text style ID provided by the text style manager.
*/
IMPORT_C void SetTextStyle(TInt aTextStyleId);
/**
* Accesses the text style of the text visual.
*
* If a value has been set by SetFontId which is not in THuiTextStyle, then
* this will return EHuiTextStyleNotAHuiStyle
*/
IMPORT_C THuiPreconfiguredTextStyle Style() const;
/**
* Accesses the text style id of the text visual, including non-predefined styles
*
* @return text style id
*/
IMPORT_C TInt TextStyle() const;
/**
* Sets the maximum number of lines displayed by the text visual.
* The default is KMaxTInt.
*/
IMPORT_C void SetMaxLineCount(TInt aMaxLineCount);
/**
* Determines the maximum number of line displayed by the text visual.
*/
IMPORT_C TInt MaxLineCount() const;
/**
* Determines the visual's line wrapping mode.
*
* @return Line wrapping mode.
*/
IMPORT_C TLineWrap Wrapping() const;
/**
* Sets the line wrapping mode.
*
* @param aWrap Line wrapping mode.
*/
IMPORT_C void SetWrapping(TLineWrap aWrap);
/**
* Determines the background type of the text visual. This was set with a
* call to SetStyle().
*/
IMPORT_C THuiBackgroundType BackgroundType() const;
inline THuiTimedPoint& Offset()
{
return iOffset;
}
inline const THuiTimedPoint& Offset() const
{
return iOffset;
}
/**
* Determines the size of the text in the visual.
* Text must have been updated / or drawn to be able
* to use these extents.
*
* @return Size of the text in pixels, or TSize(0,0) if
* text is undefined or the mesh hasn't been updated.
*
* @see UpdateMeshL()
*/
IMPORT_C TSize TextExtents() const;
/**
* Prepares text for drawing. Updates the text max line
* width according to the wrapping parameters, sets the
* text style and updates the text mesh.
*
* @see UpdateMeshL()
*/
IMPORT_C virtual TBool PrepareDrawL();
/**
* Sets the color of the text.
*
* @param aColor Text color.
*/
IMPORT_C void SetColor(const TRgb& aColor);
/**
* Sets the color of the text via skin id.
*
* @param aID Skin-id of the color group to use
* @param aIndex Index within the color group
*/
IMPORT_C void SetColor(const TAknsItemID& aID,const TInt aIndex);
/**
* Get the extents of a block of characters given the visual's
* current font style.
*
* Gets the local pixel extents of a block of text within
* this text visual.
*
* Note that these extents do not take into account line breaks,
* so it will only return accurate results on single lines of text.
*
* @param aStart The starting character of the substring.
* @param aEnd The end character of the substring.
*/
IMPORT_C TRect SubstringExtents(TUint aStart, TUint aEnd) const;
/**
* @deprecated Use CHuiDropShadow
*
* Enables or disables the text shadow.
* The text shadow is a special implementation
* of shadow that looks good with text. If this value is
* false, then the text will not have a shadow.
* This method will also reset iShadow opacity to 0 or 1.
*
* @param aDoEnable True enables shadows, false disables.
*/
IMPORT_C void EnableShadow(TBool aDoEnable);
/**
* Sets highlighting for a part of Text
*
* @param aStart Startng index of Highlighted text.
* @param aEnd Ending index of Highlighted text.
* @param aHighlightColor Background color of highlighted text.
* @param aHightlightColor Font color of Highlighted text.
*/
IMPORT_C void SetHighlightRange(TInt aStart, TInt aEnd, TRgb& aHighlightColor, TRgb& aHighlightTextColor);
/** @endAPI */
/**
* Draw the text visual.
*/
virtual void DrawSelf(CHuiGc& aGc, const TRect& aDisplayRect) const;
/**
* Returns true if the text has changed and needs redrawing.
*/
virtual TBool Changed() const;
/**
* Clear the changed flag of the visual, ie, the text has been redrawn.
*/
virtual void ClearChanged();
void NotifySkinChangedL();
void GetClassName(TDes& aName) const
{
aName = _L("CHuiTextVisual");
}
void ExpandRectWithContent(TRect& aRect) const;
/**
* Updates the text mesh within this text visual.
* Updates the text font and the text itself (possibly
* renders the text to a bitmap), if needed, and
* recalculates the text extents.
*/
void UpdateMeshL() const;
IMPORT_C void UpdateMeshL(const TDesC8& aBuffer);
private:
private:
/** Line wrapping mode. */
TLineWrap iLineWrapping;
/** Horizontal alignment. */
THuiAlignHorizontal iAlignHorizontal;
/** Vertical alignment. */
THuiAlignVertical iAlignVertical;
/** The text of drawn in the visual. */
HBufC* iText; // Owned
/** ETrue if the mesh has been updated. */
mutable TBool iMeshUpdated;
/** ETrue, if the extents have been updated. */
mutable TBool iExtentsUpdated;
/** ETrue, if the font and style has been updated. */
mutable TBool iFontUpdated;
/** Text mesh containing the text in a format suitable for
efficient drawing. */
CHuiTextMesh* iTextMesh;
/** Default text style. Affects both font and other features of the text */
THuiPreconfiguredTextStyle iStyle;
/** Text background type. Affects text style. */
THuiBackgroundType iBackgroundType;
/** Offset to the text position. */
THuiTimedPoint iOffset;
TRgb iFontColor;
TAknsItemID iFontColorId;
TInt iFontColorIndex;
TBool iFontColorValid;
/** Pictograph drawing interface */
CAknPictographInterface* iPictographInterface;
/** Pictograph animator */
CHuiPictographAnimator* iPictographAnimator;
TInt iHighlightStart;
TInt iHighlightEnd;
TRgb iHighlightColor;
TRgb iHighlightTextColor;
public:
// @deprecated Use CHuiDropShadow
THuiTimedValue iShadow;
};
#endif // __HUITEXTVISUAL_H__