Class CListItemDrawer

CListItemDrawer

Support

Supported from 6.0

Description

Draws individual list box items for a CListBoxView.

The items may optionally be markable.

Writing derived classes:

This class may be derived from to provide a different appearance for a list box.

Derivation

CBase Base class for all classes to be instantiated on the heap CListItemDrawer Draws individual list box items for a CListBoxView

Defined in CListItemDrawer:
BackColor(), CListItemDrawer(), ClearFlags(), ClearRect(), DimmedBackColor(), DimmedTextColor(), DrawActualItem(), DrawFrame(), DrawItem(), DrawItemMark(), ECurrent, EDrawMarkSelection, EDrawOnlyActiveSelection, EEmphasized, EMask, EPaintedSelection, ESelected, Flags(), Font(), Gc(), HighlightedBackColor(), HighlightedTextColor(), ItemWidthInPixels(), MarkColor(), MarkColumn(), MarkGutter(), MatcherCursorAscent(), MatcherCursorRect(), MinimumCellSize(), Properties(), ResetGc(), SetBackColor(), SetData(), SetDimmedBackColor(), SetDimmedTextColor(), SetDrawMark(), SetFlags(), SetGc(), SetHighlightedBackColor(), SetHighlightedTextColor(), SetItemCellSize(), SetMarkColumnWidth(), SetMarkGutter(), SetSymbolFont(), SetTextColor(), SetVerticalInterItemGap(), SetViewRect(), SetupGc(), TFlags, TListItemAttribute, TextColor(), VerticalInterItemGap(), iBackColor, iData, iDimmedBackColor, iDimmedTextColor, iDrawMark, iGc, iHighlightedBackColor, iHighlightedTextColor, iItemCellSize, iMarkColor, iMarkColumnWidth, iMarkGutter, iTextColor, iViewRect, ~CListItemDrawer()

Inherited from CBase:
operator new()

See also:

• CListBoxView
• CEikListBox

protected: CListItemDrawer();

Description

Constructs a list item drawer.

Note that the graphics context is not yet set; initialisation may be completed with SetGc().

~CListItemDrawer();

Description

Destructor.

void SetItemCellSize(const TSize& aSizeInPixels);

Description

Sets the item cell size.

The cell size is the on-screen size of the entire item, including its text and its item mark.

Parameters

Const TSize& aSizeInPixels New size for the item cell.

virtual void SetViewRect(const TRect& aRect);

Description

Sets the viewing rectangle for this item drawer.

This value is not used by CListItemViewer, but may be used by its derived classes; see iViewRect.

Parameters

Const TRect& aRect New value for iViewRect.

virtual void SetGc(CWindowGc* aGc);

Description

Sets the graphics context which this object uses for drawing.

Parameters

CWindowGc* aGc Pointer to the context to use.

CWindowGc* Gc() const;

Description

Gets the graphics context. See iGc.

Return value

CWindowGc* This object's graphics context.

protected: virtual void ResetGc() const;

Description

Resets the pen style, brush style, brush colour etc. to suitable starting values for this class.

This function is called after every drawing operation.

protected: void SetupGc(TInt aItemIndex) const;

Description

Sets up the graphics context for the specified item.

Parameters

TInt aItemIndex The item for which the graphics context will be set up.

virtual void DrawItem(TInt aItemIndex, TPoint aItemRectPos,
     TBool aSelected, TBool aItemIsCurrent, TBool aViewIsEmphasized,
    TBool aViewIsDimmed) const;

Description

Draws the entire item.

This function is called by the list box view. As implemented in CListItemDrawer, this function draws the item text using DrawActualItem(), and an item mark using DrawItemMark().

Parameters

TInt aItemIndex Index of the item to draw. TPoint aItemRectPos Position of the rectangle to draw. TBool aSelected Whether the item is selected. TBool aItemIsCurrent Whether the item is current. TBool aViewIsEmphasized Whether the list box view has the emphasised flag set (see CListBoxView::SetEmphasized()). TBool aViewIsDimmed Whether the list box view has its dimmed flag set (see CListBoxView::SetDimmed()).

static void DrawFrame(CWindowGc& aGc,const TRect& aRect,TInt aFlags);

Description

Draws the frame.

Uses the colours set with the fonts and colour functions described above.

Parameters

CWindowGc& aGc The graphics context to use to draw the frame. const TRect& aRect The frame’s rectangle. TInt aFlags The item drawer flags.

virtual void ClearRect(const TRect& aRect) const;

Description

Clears the specified rectangle of this object's graphics context.

Parameters

const TRect& aRect Rectangle to clear.

protected: virtual void DrawActualItem(TInt aItemIndex, const TRect& aActualItemRect, TBool aItemIsCurrent, TBool aViewIsEmphasized, TBool aViewIsDimmed) const = 0;

Description

Draws item text.

This function is called by CListItemDrawer::DrawItem() with appropriate arguments. Its purpose is to draw the actual item — everything other than the item mark — into the graphics context.

Parameters

TInt aItemIndex Which item to draw. const TRect& aActualItemRect Where the item should be drawn. TBool aItemIsCurrent Whether the item is current. TBool aViewIsEmphasized Whether the list box view is emphasised. TBool aViewIsDimmed Whether the list box view is dimmed. TBool aItemIsSelected Whether the list box item is selected.

virtual TInt ItemWidthInPixels(TInt aItemIndex) const;

Description

Gets the width of the specified item.

Parameters

TInt aItemIndex The index of the item whose width is to be returned.

Return value

TInt The width of the item. This is 0 in CListItemDrawer.

virtual TSize MinimumCellSize() const;

Description

Gets the minimum cell size.

Return value

TSize The minimum size for a cell. This is TSize(0, 0) in CListItemDrawer.

void SetVerticalInterItemGap(TInt aGapInPixels);

Description

Sets the vertical gap between items in the list.

Parameters

TInt aGapInPixels New value for the vertical gap between items in pixels.

protected: TInt VerticalInterItemGap() const;

Description

Gets the vertical gap between items in pixels.

Return value

TInt The vertical gap between items in pixels.

Description

A list item drawer can draw a mark alongside each item in the list.

void SetDrawMark(TBool aDrawMark);

Description

Sets whether item tick marks are drawn.

If the draw mark flag iDrawMark is set, DrawItem() leaves space for the marks column to the left of the text column, and DrawItemMark() draws the item marks.

Parameters

TBool aDrawMark New value for iDrawMark.

virtual void DrawItemMark(TBool aSelected, TBool aViewIsDimmed,const TPoint& aMarkPos) const;

Description

Draws an item tick mark.

A tick mark is used in multiple selection lists to indicate an item is selected.

This function is invoked by the framework to draw an item mark if iDrawMark is set. The mark should be drawn into this list item drawer's graphics context; by default, DrawItemMark() draws a tick using the standard symbol font.

This function does not need to be re-implemented for derived classes which do not draw item marks.

Parameters

TBool aSelected Whether the item to draw for is selected. TBool aViewIsDimmed Whether the item is dimmed. const TPoint& aMarkPos Position of the mark.

virtual void SetMarkColumnWidth(TInt aWidthInPixels);

Description

Sets the width of the column containing the mark.

Parameters

TInt aWidthInPixels New width for the mark column.

TInt MarkColumn() const;

Description

Gets the width of the item tick mark column.

Return value

TInt Width of the item tick mark column.

virtual void SetMarkGutter(TInt aGapInPixels);

Description

Sets the width of the gap between the column containing the lists item marks and the text column.

Parameters

TInt aGapInPixels New gap size.

TInt MarkGutter() const;

Description

Gets the width of the gap between the column containing the list's item marks and the text column.

Return value

TInt Size of the inter-column gutter.

TRgb MarkColor() const;

Description

Gets the colour used to draw tick marks.

A tick mark usually indicates that an item is selected.

Return value

TRgb The tick mark colour.

Notes:

• This function was made public in v6.1 (previously it was protected).

Description

List item drawers can represent the current position in an incremental match (see CEikListBox) by drawing a cursor at the appropriate location. Derived classes that deal with text and want to support incremental matching in list boxes need to redefine these functions.

virtual TRect MatcherCursorRect(const TDesC& aMatchableText, TInt aCharPos, TInt aItemCellYPos) const;

Description

Gets a rectangle describing where the matcher cursor should be drawn.

The default behaviour is to return an uninitialised TRect.

Parameters

const TDesC& aMatchableText The text of the currently matched string. TInt aCharPos The position in the string of the character just matched in the current incremental match. TInt aItemCellYPos Y position of the item cell.

Return value

TRect Where the cursor should be drawn.

virtual TInt MatcherCursorAscent() const;

Description

Gets the ascent of the matcher cursor.

This is obtained for the item at index aCurrentItemIndex determined from the ascent of the font used for that item.

The function returns 0 by default.

Return value

TInt Height of the matcher cursor.

Description

These functions alter the display of the list item drawer.

void SetData(CListBoxData* aData);

Description

Sets the font storage data for the item drawer and transfers ownership of that data.

Parameters

CListBoxData* aData Font storage data.

void SetSymbolFont(const CFont* aFont);

Description

Sets the symbol font use by this item drawer.

The symbol font is used to draw the standard tick item marks.

Parameters

const CFont* aFont The font to use.

CFont* Font(TInt aItemIndex) const;

Description

Gets the font for the specified item.

The function returns NULL if no font storage data has been set.

Parameters

TInt aItemIndex The index of the item for which the font is returned.

Return value

CFont* The item's font.

void SetBackColor(TRgb aColor);

Description

Sets the colour used to draw the background for non-highlighted items.

Parameters

TRgb aColor The background colour.

TRgb BackColor() const;

Description

Gets the colour used to draw the background for non-highlighted items.

Return value

TRgb The background colour.

void SetHighlightedBackColor(TRgb aColor);

Description

Sets the colour used to draw the background for highlighted items.

Parameters

TRgb aColor The highlighted background colour.

TRgb HighlightedBackColor() const;

Description

Gets the colour used to draw the background for highlighted items.

Return value

TRgb The highlighted background colour.

void SetDimmedTextColor(TRgb aColor);

Description

Sets the colour used to draw dimmed text.

Parameters

TRgb aColor The dimmed text colour.

TRgb DimmedTextColor() const;

Description

Gets the colour used to draw dimmed text.

Return value

TRgb The dimmed text colour.

void SetDimmedBackColor(TRgb aColor);

Description

Sets the colour used to draw the background for dimmed items.

Parameters

TRgb aColor The background colour for dimmed items.

TRgb DimmedBackColor() const;

Description

Gets the colour used to draw the background for dimmed items.

Return value

TRgb The background colour for dimmed items.

void SetHighlightedTextColor(TRgb aColor);

Description

Sets the colour used to draw highlighted text.

Parameters

TRgb aColor The highlighted text colour.

TRgb HighlightedTextColor() const;

Description

Gets the colour used to draw highlighted text.

Return value

TRgb The highlighted text colour.

void SetTextColor(TRgb aColor);

Description

Sets the colour used to draw non-highlighted text.

Parameters

TRgb aColor The text colour.

TRgb TextColor() const;

Description

Gets the colour used to draw non-highlighted text.

Return value

TRgb The text colour.

void SetFlags(TInt aFlags);

Description

Sets the item drawer flags.

Parameters

TInt aFlags The new item drawer flags.

TInt Flags() const;

Description

Gets the item drawer flags.

Return value

TInt The item drawer flags.

void ClearFlags(TInt aFlags);

Description

Clears the specified item drawer flags.

Parameters

TInt aFlags The item drawer flags.

TListItemProperties Properties(TInt aItemIndex) const;

Description

Gets the colour and style properties of the specified item.

Parameters

TInt aItemIndex The index of the item for which properties are obtained.

Return value

TListItemProperties The item's properties.

TSize iItemCellSize;

Description

Size of the entire area to be drawn.

TInt iMarkGutter;

Description

Width of the gutter between the item mark column and the rest of the item cell.

TInt iMarkColumnWidth;

Description

Width of the item mark column

TRect iViewRect;

Description

Viewing rectangle.

TBool iDrawMark;

Description

Whether or not to draw item marks and the mark gutter.

TRgb iBackColor;

Description

Background colour for non-highlighted items.

TRgb iHighlightedBackColor;

Description

Background colour for highlighted items.

CWindowGc* iGc;

Description

The graphics context in which items are drawn.

CListBoxData* iData

Description

The list box data.

TRgb iDimmedBackColor

Description

Background colour for dimmed items.

TRgb iDimmedTextColor

Description

Colour for dimmed text.

TRgb iHighlightedTextColor

Description

Colour for highlighted text.

TRgb iMarkColor

Description

Colour for tick marks.

TRgb iTextColor

Description

Text colour.

TFlags enum

Description

Provides list box attributes for handling multiple selections. These flags can be set using the CListItemDrawer::SetFlags function.

EDrawMarkSelection If set, specifies the inclusion of a gap into which a tick mark can be drawn if the item is selected. This is used in the following CListItemDrawer class functions: DrawItem() DrawItemMark() SetDrawMark() EPaintedSelection If set, draws a highlight over a selected list item. This is used in the CTextListItemDrawer::DoDrawItemText() function. EDrawOnlyActiveSelection This flag is not supported.

TListItemAttribute

Description

Provides attributes for list items.

ECurrent Highlight for current text. EEmphasized Highlight for text when the listbox view is emphasized.This is used in the following CListBoxView class functions: DrawItem(), DrawMatcherCursor(), SetEmphasized(). ESelected Highlight for text that is selected. This is used in the following functions: CColumnListBoxItemDrawer::DrawItemText(), CHierarchicalListItemDrawer::DrawActualItem(), CDirContentsListItemDrawer::DrawActualItem(). EMask Sum of all the above attributes.