/*
* Copyright (c) 2006 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: Text visual
*
*/
#ifndef C_ALFTEXTVISUAL_H
#define C_ALFTEXTVISUAL_H
class TAknsItemID;
class TRgb;
#include <alf/alfvisual.h>
#include <alf/alftextstylemanager.h>
#include <alf/alfgc.h>
#include <AknFontSpecification.h>
#include <AknFontIdOffsets.hrh>
/** Background type suggestions.
*
* These enums suggest which sort of background is under the visual,
* in order for it to be rendered in an appropriate colour.
* A dark background means that the text will be rendered in white, and a
* light background means that the text will be black.*/
enum TAlfBackgroundType
{
/** background beneath the font is light. */
EAlfBackgroundTypeLight,
/** background beneath the font is dark. */
EAlfBackgroundTypeDark
};
/**
* Text visual for text drawing.
* Text visual shows one or more lines of text.
*
* @code
* CAlfTextVisual* textVisual = CAlfTextVisual::AddNewL( control );
* textVisual->SetTextL( _L( "Hello" ) ); *
* @endcode
*
* @lib alfclient.lib
* @since S60 v3.2
*/
class CAlfTextVisual : public CAlfVisual
{
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. */
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
};
/**
* Constructor, which gives ownership to the control.
*
* @param aOwnerControl The control
* @param aParentLayout If given, the parent layout.
* @return New instance. Ownership NOT transreffed (owned by control)
*/
IMPORT_C static CAlfTextVisual* AddNewL(CAlfControl& aOwnerControl,
CAlfLayout* aParentLayout = 0);
/**
* Constructor.
*/
IMPORT_C CAlfTextVisual();
/**
* Second-phase constructor.
*/
IMPORT_C void ConstructL(CAlfControl& aOwner);
/**
* Destructor.
*/
IMPORT_C virtual ~CAlfTextVisual();
/**
* 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.
*
* @return The text.
*/
IMPORT_C const TDesC& Text() const;
/**
* Sets the default text style of the text visual. This style describbes the size
* and colour of the rendered text. Parameters passed here can be overridden by
* call to SetFontSpec().
* @see SetFontSpec()
*
* @param aStyle Text style.
* @param aBackgroundType Text background type. Affects the color of
* the text. Defaults to EAlfBackgroundTypeLight
* (ie, black text will be used).
*/
IMPORT_C void SetStyle(
TAlfPreconfiguredTextStyle aStyle,
TAlfBackgroundType aBackgroundType = EAlfBackgroundTypeLight);
/**
* 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 CAlfTextStyleManager
*
* @param aTextStyleId Text style ID provided by the text style manager.
*/
IMPORT_C void SetTextStyle(TInt aTextStyleId);
/**
* Sets the alignment of the text visual.
*
* @param aAlignHorizontal Horizontal alignment.
* @param aAlignVertical Vertical alignment.
*/
IMPORT_C void SetAlign(TAlfAlignHorizontal aAlignHorizontal,
TAlfAlignVertical 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);
/**
* 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;
/**
* 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 TRect SubstringExtents(TUint aStart, TUint aEnd) const;
/**
* Accesses the text style of the text visual.
*
* @deprecated
*
* @return the text style, but only valid if the text style corresponds to a preconfigured
* text style
*/
IMPORT_C TAlfPreconfiguredTextStyle Style();
/**
* Accesses the text style id of the text visual.
*
* @note This API should be used in preference to @c Style
*
* @return the text style id, this can be used to access the actual text style,
* see @c CAlfTextStyleManager::TextStyle
*/
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 TAlfBackgroundType BackgroundType();
/**
* @deprecated Use CAlfDropShadow
*
* Returns shadow opacity.
*
* @return Shadow opacity
*/
IMPORT_C TAlfTimedValue ShadowOpacity();
/**
* @deprecated Use CAlfDropShadow
*
* Sets shadow opacity.
* Changes the opacity of the text soft shadow.
* Currently SetShadowStrength is only implemented in the OpenGL renderer,
* and will have no effect in BitGDI.
*
* @param aShadowOpacity Shadow opacity
* @see EnableShadow
*/
IMPORT_C void SetShadowOpacity(const TAlfTimedValue& aShadowOpacity);
/**
* Sets the color of the text.
*
* @param aColor Text color.
*/
IMPORT_C void SetColor(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);
/**
* Sets the color of the text via skin id.
*
* @param aTextColorTable Skin-id name of the color group to use
* @param aColorIndex Index within the color group
*/
IMPORT_C void SetColor(const TDesC& aTextColorTable,const TDesC& aColorIndex);
/**
* @deprecated Use CAlfDropShadow
*
* Enables or disables the text shadow.
* The rasterized 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 rasterized shadow.
*
* @param aDoEnable True enables rasterized shadows, false disables.
* @see SetShadowOpacity
* @see ShadowOpacity
*/
IMPORT_C void EnableShadow(TBool aDoEnable);
/**
* Sets offset for the text.
*
* @param aOffset text offset.
*/
IMPORT_C void SetOffset(const TAlfTimedPoint& aOffset);
/**
* Gets offset for the text.
*
* @return text offset.
*/
IMPORT_C TAlfTimedPoint Offset() const;
/**
* From CAlfVisual
* @see CAlfVisual
*/
IMPORT_C void RemoveAndDestroyAllD();
IMPORT_C void UpdateChildrenLayout(TInt aTransitionTime = 0);
IMPORT_C CAlfVisual* FindTag(const TDesC8& aTag);
/**
* Sets highlighting for a part of Text
* Start and end index of text to be highlighted, are ordinal indices.
* In case of multiple language, bidirectional text (e.g. English + Arabic),
* mixed text selection for highlight, might give strange results.
* e.g.TextVisual text : "E n g l i s h c i b a r A" ( Arabic script is
* read/written from right to left. Assume 'c i b a r A' is Arabic script )
* and highlight range : 5-9.
* Expected result : "i s h" and "r A" should get highlighted
* Actual Result: "i s h c i"
* Hence, it is recommended to use different text visuals in case of selection of
* bidirectional 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);
/** Internal utils */
void PrepareForUpdateMesh();
void UpdateMesh(TBool aSynchronousUpdate = EFalse);
void ReleaseMesh();
protected:
/**
* From CAlfVisual
* @see CAlfVisual
*/
IMPORT_C void DoRemoveAndDestroyAllD();
IMPORT_C void PropertyOwnerExtension(const TUid& aExtensionUid, TAny** aExtensionParams);
private:
struct TTextVisualPrivateData;
TTextVisualPrivateData* iTextVisualData;
};
#endif // C_ALFTEXTVISUAL_H