CAknGrid Class Reference

API published in: S60 1st Ed

Link against: avkon.lib

Capability Information

Required Capabilities

None

#include <akngrid.h>

Inherits CEikListBox.

Inherited by CAknCaleMonthStyleGrid, CAknGMSStyleGrid, CAknPinbStyleGrid, and CAknQdialStyleGrid.

Detailed Description

Application grid handling class from Avkon.

Provides support for ordering application grids items.


Public Member Functions
IMPORT_C	CAknGrid ()
	Base class default constructor.
virtual IMPORT_C	~CAknGrid ()
	Destructor.
IMPORT_C void	SetModel (CAknGridM *aModel)
	This function gives `CAknGridM` class pointer to `CAknGrid` class.
IMPORT_C void	ConstructL (const CCoeControl *aParent, TInt aFlags=0)
	This is Symbian default constructor.
IMPORT_C void	ConstructFromResourceL (TResourceReader &aReader)
	The `ConstructFromResourceL` function needs to be called in case resource data is used.
IMPORT_C void	SetLayoutL (TBool aVerticalOrientation, TBool aLeftToRight, TBool aTopToBottom, TInt aNumOfItemsInPrimaryOrient, TInt aNumOfItemsInSecondaryOrient, TSize aSizeOfItems, TInt aWidthOfSpaceBetweenItems=0, TInt aHeightOfSpaceBetweenItems=0)
	Sets the orientation of the grid, either vertical or horizontal, the ordering of the data and the size of the primary dimension of the grid.
IMPORT_C void	SetLayoutFromResourceL (TResourceReader &aReader)
	Sets the layout from a resource.
IMPORT_C void	SetPrimaryScrollingType (CAknGridView::TScrollingType aScrollingType)
	Sets the movement of the cursor with respect to scrolling when the end item in the current row or column, whichever is the primary orientation of the data items, is encountered.
IMPORT_C void	SetSecondaryScrollingType (CAknGridView::TScrollingType aSecondaryScrolling)
	Sets the movement of the cursor with respect to scrolling when the end item in the secondary dimension of the grid is encountered.
IMPORT_C void	SetStartPositionL (TPoint aGridStartPosition)
	Sets the starting position of the data within the grid.
IMPORT_C TInt	CurrentDataIndex () const
	`CurrentDataIndex` retrieves the index of the selection.
IMPORT_C void	SetCurrentDataIndex (TInt aDataIndex)
	Moves the cursor to the required grid data index.
IMPORT_C TInt	IndexOfPosition (TPoint aGridPosition) const
	The grid position function.
IMPORT_C TPoint	PositionAtIndex (TInt aItemIndex) const
	The grid position function.
IMPORT_C CFormattedCellListBoxItemDrawer *	ItemDrawer () const
	Item drawer.
IMPORT_C void	SetEmptyGridTextL (const TDesC &aText)
	Function sets a grid text to the data item.
const TDesC *	EmptyGridText () const
	This function sets the empty grid text.
virtual IMPORT_C CListBoxView *	MakeViewClassInstanceL ()
	This function creates a new object and returns pointer to it.
IMPORT_C void	SetColumnWidth (TInt aColumnWidth)
	This function sets the column width of the grid.
IMPORT_C TInt	ColumnWidth () const
	This function gives a width of the column.
virtual IMPORT_C void	UpdateScrollBarsL ()
	This function updates the scrollbars, including item position.
IMPORT_C void	HandleItemAdditionL ()
	This function should be called after one or more items have been added to the grid.
IMPORT_C void	HandleItemRemovalL ()
	This function should be called after one or more items have been removed from the grid.
virtual IMPORT_C TKeyResponse	OfferKeyEventL (const TKeyEvent &aKeyEvent, TEventCode aType)
	This function is from `CEikAppUi`, handles key events.
IMPORT_C void	SetItemHeightL (TInt aHeight)
	This function sets the row height of the grid.
IMPORT_C void	SizeChanged ()
	This function handles size changes.
IMPORT_C CTextListBoxModel *	Model () const
	This function creates a new object and returns pointer to `CTextListBoxModel` class.
IMPORT_C void	SetRect (const TRect &aRect)
	This function handles viewable rectangle.
virtual IMPORT_C void	HandleViewRectSizeChangeL ()
	This function is called when the grid's items, item's data and scroll bars has been changed.
virtual IMPORT_C void	SetTopItemIndex (TInt aItemIndex) const
	This function sets top item index.
virtual IMPORT_C void	HandleResourceChange (TInt aType)
	This function handles resource changes.
IMPORT_C void	FocusChanged (TDrawNow aDrawNow)
	Indicates whether the control should be redrawn now.
IMPORT_C void	HandlePointerEventL (const TPointerEvent &aPointerEvent)
	Handling of pointer event within the `CEikListBox`.
Protected Member Functions
virtual IMPORT_C TInt	HorizontalNudgeValue () const
	This function scroll horizontal by one column when the left/right scroll arrows (i.e.
virtual IMPORT_C TInt	HorizScrollGranularityInPixels () const
	This function gets the granularity for horizontal scrolls.
virtual IMPORT_C void	AdjustTopItemIndex () const
	This function called by various functions of this class to ensure that the top item index is always a sane value.
virtual IMPORT_C void	HandleDragEventL (TPoint aPointerPos)
	This function handles drag events.
virtual IMPORT_C void	RestoreClientRectFromViewRect (TRect &aClientRect) const
	This function calculates the client area.
virtual IMPORT_C TInt	AdjustRectHeightToWholeNumberOfItems (TRect &aRect) const
	This function rounds down the height of the rectangle (if necessary) so that only a whole number of items can be displayed inside the list box.
virtual IMPORT_C void	UpdateScrollBarThumbs () const
	Updates the position of grids scroll bars’ thumbs to reflect the vertical position of selector.
virtual IMPORT_C TInt	CountComponentControls () const
	Gets a count of the component controls of this grid.
virtual IMPORT_C TTypeUid::Ptr	MopSupplyObject (TTypeUid aId)
	From `MObjectProvider`.
IMPORT_C void	MoveToNextOrPreviousItemL (TPoint aPoint)
	Moves to the next or previous item on the grid.
virtual IMPORT_C void	CalcGridSizeL ()
	This protected function used by functions to check/alter the dimensions of the grid as data items are added or removed or the size of the items are altered.
virtual IMPORT_C void	CreateItemDrawerL ()
	Creates a formatted list item drawer.
virtual IMPORT_C void	HandleScrollEventL (CEikScrollBar *aScrollBar, TEikScrollEvent aEventType)
	From `MEikScrollBarObserver`.

Constructor & Destructor Documentation

IMPORT_C CAknGrid::CAknGrid

(

)

Base class default constructor.

Returns:: A pointer to a new CAknGrid object.

virtual IMPORT_C CAknGrid::~CAknGrid ( ) [virtual]

Destructor.

Member Function Documentation

virtual IMPORT_C TInt CAknGrid::AdjustRectHeightToWholeNumberOfItems ( TRect & aRect ) const [protected, virtual]

This function rounds down the height of the rectangle (if necessary) so that only a whole number of items can be displayed inside the list box.

Parameters:

aRect

Rectangle parameter.

Reimplemented from CEikListBox.

virtual IMPORT_C void CAknGrid::AdjustTopItemIndex ( ) const [protected, virtual]

This function called by various functions of this class to ensure that the top item index is always a sane value.

The implementation in CEikListBox tries to ensure the minimum amount of white space at the bottom of the list box. Note that this function does not affect the current item index.

Reimplemented from CEikListBox.

virtual IMPORT_C void CAknGrid::CalcGridSizeL ( ) [protected, virtual]

This protected function used by functions to check/alter the dimensions of the grid as data items are added or removed or the size of the items are altered.

It also assumes that SetLayoutL has been called. This will not leave if scrollbars have both been turned off. If a leave occurs the framework generates a Symbian Leave code.

IMPORT_C TInt CAknGrid::ColumnWidth

(

)

const

This function gives a width of the column.

Returns:: A width of the column.

IMPORT_C void CAknGrid::ConstructFromResourceL

(

TResourceReader &

aReader

)

The ConstructFromResourceL function needs to be called in case resource data is used.

Usually, the CAknGridM class object is instantiated automatically during the construction phase of the CAknGrid object. If an application programmer provides their own grid model class, the application programmer must instantiate their own grid model class object and give it to the CAknGrid object using the SetModel function before calling the ConstructL/ConstructFromResourceL function. If a leave occurs the framework generates a Symbian Leave code.

Parameters:

aReader

Construct controls from resource file.

IMPORT_C void CAknGrid::ConstructL	(	const CCoeControl *	aParent,
		TInt	aFlags = `0`
	)	`[virtual]`

This is Symbian default constructor.

The ConstructL function needs to be called in case resource data is not used. If a leave occurs the framework generates a Symbian Leave code.

Parameters:

	aPatent	A CCoeControl pointer.
	aFlags	Parameter for `CEikListBox` constructor. If the parameter is missing default value is 0.

Reimplemented from CEikListBox.

virtual IMPORT_C TInt CAknGrid::CountComponentControls ( ) const [protected, virtual]

Gets a count of the component controls of this grid.

Returns:: The number of component controls.

Reimplemented from CEikListBox.

virtual IMPORT_C void CAknGrid::CreateItemDrawerL ( ) [protected, virtual]

Creates a formatted list item drawer.

If a leave occurs the framework generates a Symbian Leave code.

IMPORT_C TInt CAknGrid::CurrentDataIndex

(

)

const

CurrentDataIndex retrieves the index of the selection.

In grids, you should use this method instead of CEikListBox::CurrentItemIndex(), when you are manipulating data stored in the grid's ItemTextArray. While CurrentItemIndex() returns the same value as CurrentItemIndex() on most phones, there will be difference in some language variants where text reading/writing direction is different from left-to-right.

Returns:: A current position of highlight.

const TDesC * CAknGrid::EmptyGridText ( ) const [inline]

This function sets the empty grid text.

Returns:: A pointer to the grid text descriptor.

IMPORT_C void CAknGrid::FocusChanged ( TDrawNow aDrawNow ) [virtual]

Indicates whether the control should be redrawn now.

If ENoDrawNow, the function has no immediately effect. EDrawNow redraw control immediately.

Reimplemented from CEikListBox.

virtual IMPORT_C void CAknGrid::HandleDragEventL ( TPoint aPointerPos ) [protected, virtual]

This function handles drag events.

If a leave occurs the framework generates a Symbian Leave code.

Parameters:

aPointerPos The position of the TPointerEvent for which this handler is invoked.

Reimplemented from CEikListBox.

IMPORT_C void CAknGrid::HandleItemAdditionL

(

)

This function should be called after one or more items have been added to the grid.

If a leave occurs the framework generates a Symbian Leave code.

Reimplemented from CEikListBox.

IMPORT_C void CAknGrid::HandleItemRemovalL

(

)

This function should be called after one or more items have been removed from the grid.

If a leave occurs the framework generates a Symbian Leave code.

Reimplemented from CEikListBox.

IMPORT_C void CAknGrid::HandlePointerEventL ( const TPointerEvent & aPointerEvent ) [virtual]

Handling of pointer event within the CEikListBox.

Used for e.g. selecting an item from the list box.

Parameters:

aPointerEvent

Details of the pointer event that is being handled.

Reimplemented from CEikListBox.

Reimplemented in CAknGMSStyleGrid, CAknPinbStyleGrid, CAknQdialStyleGrid, and CAknCaleMonthStyleGrid.

virtual IMPORT_C void CAknGrid::HandleResourceChange ( TInt aType ) [virtual]

This function handles resource changes.

Parameters:

aType

Message type.

Reimplemented from CEikListBox.

virtual IMPORT_C void CAknGrid::HandleScrollEventL	(	CEikScrollBar *	aScrollBar,
		TEikScrollEvent	aEventType
	)	`[protected, virtual]`

From MEikScrollBarObserver.

This function handles scroll events caused by scroll bar. It updates grid's view by event and new thumb position.

Parameters:

	aScrollBar	pointer to scroll bar sent this event
	aEventType	type of event

Reimplemented from CEikListBox.

virtual IMPORT_C void CAknGrid::HandleViewRectSizeChangeL ( ) [virtual]

This function is called when the grid's items, item's data and scroll bars has been changed.

This implementation ensures that the current item is visible after resize. If a leave occurs the framework generates a Symbian Leave code.

Reimplemented from CEikListBox.

virtual IMPORT_C TInt CAknGrid::HorizontalNudgeValue ( ) const [protected, virtual]

This function scroll horizontal by one column when the left/right scroll arrows (i.e.

the nudge buttons) are tapped.

Returns:: A nudge value when the buttons are pressed.

Reimplemented from CEikListBox.

virtual IMPORT_C TInt CAknGrid::HorizScrollGranularityInPixels ( ) const [protected, virtual]

This function gets the granularity for horizontal scrolls.

The granularity is the minimum size of a horizontal move of the client area.

Returns:: A grain size for horizontal scrolling in pixels.

Reimplemented from CEikListBox.

IMPORT_C TInt CAknGrid::IndexOfPosition

(

TPoint

aGridPosition

)

const

The grid position function.

Gives the data index by using grid's position. The position must be given from the top left corner. If the function returns -1 the item's position is invalid.

Parameters:

aGridPosition

The data item's co-ordinate values.

Returns:: Activated item's index value.

IMPORT_C CFormattedCellListBoxItemDrawer* CAknGrid::ItemDrawer

(

)

const

Item drawer.

Gets the pointer to the grid class.

Returns:: A pointer to CFormattedCellListBoxItemDrawer object.

virtual IMPORT_C CListBoxView* CAknGrid::MakeViewClassInstanceL ( ) [virtual]

This function creates a new object and returns pointer to it.

If the leave occurs the framework generates a Symbian Leave code.

Returns:: A pointer to CListBoxView class.

Reimplemented from CEikListBox.

Reimplemented in CAknGMSStyleGrid.

IMPORT_C CTextListBoxModel* CAknGrid::Model

(

)

const

This function creates a new object and returns pointer to CTextListBoxModel class.

Returns:: A pointer to CTextListBoxModel object.

Reimplemented from CEikListBox.

virtual IMPORT_C TTypeUid::Ptr CAknGrid::MopSupplyObject ( TTypeUid aId ) [protected, virtual]

From MObjectProvider.

Retrieves an object of the same type as that encapsulated in aId. This function is used to allow controls to ask their owners for access to other objects that they own.

Parameters:

aId

An encapsulated object type ID.

Returns:: Encapsulates the pointer to the object provided. Note that the encapsulated pointer may be NULL.

IMPORT_C void CAknGrid::MoveToNextOrPreviousItemL ( TPoint aPoint ) [protected]

Moves to the next or previous item on the grid.

If a leave occurs the framework generates a Symbian Leave code.

Parameters:

aPoint

Co-ordinate object parameter.

virtual IMPORT_C TKeyResponse CAknGrid::OfferKeyEventL	(	const TKeyEvent &	aKeyEvent,
		TEventCode	aType
	)	`[virtual]`

This function is from CEikAppUi, handles key events.

If a leave occurs the framework generates a Symbian Leave code.

Parameters:

	aKeyEvent	Event to handled.
	aType	of the key event.

Returns:: Response code ( EKeyWasConsumed, EKeyWasNotConsumed )

Reimplemented from CEikListBox.

Reimplemented in CAknGMSStyleGrid.

IMPORT_C TPoint CAknGrid::PositionAtIndex

(

TInt

aItemIndex

)

const

The grid position function.

Gives the data item's co-ordinate values by using item's index value.

Parameters:

aItemIndex

The data item's index value.

Returns:: TPoint co-ordinate values of active item.

virtual IMPORT_C void CAknGrid::RestoreClientRectFromViewRect ( TRect & aClientRect ) const [protected, virtual]

This function calculates the client area.

This method is called by various functions of this class to recalculate the extent of the client area from iViewRect. This implementation takes into account any rounding of the viewing rectangle made to fit a whole number of items.

Parameters:

aClientRect

On return contains a size for the client area in pixels.

Reimplemented from CEikListBox.

IMPORT_C void CAknGrid::SetColumnWidth

(

TInt

aColumnWidth

)

This function sets the column width of the grid.

Column width cannot be set in a horizontal grid since the number of columns in the grid is defined by the initialising call to SetLayoutL. The column width cannot be larger than the width of the viewing rectangle.

Parameters:

aColumnWidth

A parameter defines a width of the column.

IMPORT_C void CAknGrid::SetCurrentDataIndex

(

TInt

aDataIndex

)

Moves the cursor to the required grid data index.

Parameters:

aDataIndex

Data index value.

IMPORT_C void CAknGrid::SetEmptyGridTextL

(

const TDesC &

aText

)

Function sets a grid text to the data item.

If a leave occurs the framework generates a Symbian Leave code.

Parameters:

aText

Descriptor parameter.

IMPORT_C void CAknGrid::SetItemHeightL ( TInt aHeight ) [virtual]

This function sets the row height of the grid.

Row height cannot be set in a vertical grid since the number of rows in the grid is defined by the initialising call to SetLayoutL. The row height cannot be larger than the height of the viewing rectangle. If a leave occurs the framework generates a Symbian Leave code.

Parameters:

aHeight

The height of the item's rows.

Reimplemented from CEikListBox.

IMPORT_C void CAknGrid::SetLayoutFromResourceL

(

TResourceReader &

aReader

)

Sets the layout from a resource.

Layout includes orientation (either vertical or horizontal), horizontal and vertical direction of numbering, the number of items in the primary and secondary orientation, and the primary and secondary scrolling types. If a leave occurs the framework generates a Symbian Leave code.

Parameters:

aReader

Constructs controls from a resource file.

IMPORT_C void CAknGrid::SetLayoutL	(	TBool	aVerticalOrientation,
		TBool	aLeftToRight,
		TBool	aTopToBottom,
		TInt	aNumOfItemsInPrimaryOrient,
		TInt	aNumOfItemsInSecondaryOrient,
		TSize	aSizeOfItems,
		TInt	aWidthOfSpaceBetweenItems = `0`,
		TInt	aHeightOfSpaceBetweenItems = `0`
	)

Sets the orientation of the grid, either vertical or horizontal, the ordering of the data and the size of the primary dimension of the grid.

The value for the parameter aNumOfItemsInPrimaryOrient must be greater than zero since this determines the number of items (be it rows or columns) in the primary orientation of the grid. If a leave occurs the framework generates a Symbian Leave code.

Parameters:

	aVerticalOrientation	Items vertical orientation.
	aLeftToRight	`ETrue` left to right.
	aTopToBottom	`ETrue` top to bottom.
	aNumOfItemsInPrimaryOrient	Number of items in primary orient.
	aNumOfItemsInSecondaryOrient	Number of items in Secondary orient.
	aSizeOfItems	Item size.
	aWidthOfSpaceBetweenItems	=0 Width of space between items.
	aHeightOfSpaceBetweenItems	=0 Height of space between items.

IMPORT_C void CAknGrid::SetModel

(

CAknGridM *

aModel

)

This function gives CAknGridM class pointer to CAknGrid class.

Parameters:

aModel Pointer to CAknGridM class.

IMPORT_C void CAknGrid::SetPrimaryScrollingType

(

CAknGridView::TScrollingType

aScrollingType

)

Sets the movement of the cursor with respect to scrolling when the end item in the current row or column, whichever is the primary orientation of the data items, is encountered.

The movement maybe either stop, loop back to same row or column or move onto the next logical data item in the sequence.

Parameters:

aScrollingType

Items scrolling type enum definition.

IMPORT_C void CAknGrid::SetRect

(

const TRect &

aRect

)

This function handles viewable rectangle.

Parameters:

aRect

Rectangle parameter.

IMPORT_C void CAknGrid::SetSecondaryScrollingType

(

CAknGridView::TScrollingType

aSecondaryScrolling

)

Sets the movement of the cursor with respect to scrolling when the end item in the secondary dimension of the grid is encountered.

The movement maybe either stop, loop back back to same row or column or move onto the next logical data item in the sequence.

Parameters:

aSecondaryScrolling

Secondary scrolling type enum definition.

IMPORT_C void CAknGrid::SetStartPositionL

(

TPoint

aGridStartPosition

)

Sets the starting position of the data within the grid.

A blank page cannot be accessed (since cannot move into empty cells) so a totally blank page is the same as if the page never existed since the user cannot scroll into it. For this reason it is suggested that the start position be no more than one page into the grid. If a leave occurs the framework generates a Symbian Leave code.

Parameters:

aGridStartPosition

Parameter manipulate the grid's starting position.

virtual IMPORT_C void CAknGrid::SetTopItemIndex ( TInt aItemIndex ) const [virtual]

This function sets top item index.

Parameters:

aItemIndex

Item index value.

Reimplemented from CEikListBox.

IMPORT_C void CAknGrid::SizeChanged ( ) [virtual]

This function handles size changes.

This routine assumes that SetLayoutL has been called to set up the grid.

Reimplemented from CEikListBox.

Reimplemented in CAknGMSStyleGrid, CAknPinbStyleGrid, CAknQdialStyleGrid, and CAknCaleMonthStyleGrid.

virtual IMPORT_C void CAknGrid::UpdateScrollBarsL ( ) [virtual]

This function updates the scrollbars, including item position.

This function is called when the size of the scrollbars or data changes. If the leave occurs the framework generates a Symbian Leave code.

Reimplemented from CEikListBox.

virtual IMPORT_C void CAknGrid::UpdateScrollBarThumbs ( ) const [protected, virtual]

Updates the position of grids scroll bars’ thumbs to reflect the vertical position of selector.

Reimplemented from CEikListBox.

The documentation for this class was generated from the following file:

akngrid.h

CAknGrid Class Reference

Capability Information

Detailed Description

Public Member Functions

Protected Member Functions

Constructor & Destructor Documentation

Member Function Documentation