Grids API Specification
Changes in Grids API documentation
Changes in Grids API
PurposeGrids are used extensively to represent a compact view
of the data structure using graphics and/or text. This document introduces
readers to grid use. Items from the data structure are represented by cells in the grid view.
A cell can be further divided into sub-cells, which contain graphics or text.
Depending on the screen size, cell size, and number of items in the data structure,
all or some of the cells are visible concurrently. Grid controls provide users
with a mechanism to navigate between the cells. Grids are also scrollable,
thus enabling access to all items in the data structure.
Classification and release informationGrids API is an SDK API.
API descriptionLike other user interface components, grids follow
the Model-View-Controller (MVC) design pattern. Using listboxes is another common way to represent a set of items on the
symbian platform. While grids share a great deal of functionality with listboxes,
the fundamental difference is that a grid may contain more than one item per
line, thus providing a more compact view over the data. This compactness comes
at a cost: the amount of information per item in a grid is more limited than
in a listbox. Therefore grids are more suitable for displaying easily distinguishable
items, such as applications or available commands in one application, or items
that are naturally represented as a grid, such as a monthly calendar view. There are many different types of grids available on the symbian platform.
These types are designed to fulfill the requirements of different kinds of
data structures and use cases related to representing a set of items in a
compact way. This document covers the menu grid, the selection grid, and the markable
grid. The menu grid provides users with a collection of available actions
and allows them to proceed with one. The selection grid provides a view where
users can navigate between items and then select one or more. The markable
grid allows users to navigate and select items, and then execute a command
to each of them. Code samples throughout this document demonstrate how to
create the different types of grids. In addition to having different types of grids, the grid layout itself
can be altered. The number of visible rows and columns can be altered, along
with the presentation and composition of cells. These options are explained
thoroughly with code samples.
Grid architectureGrid controls and listboxes have a great deal in common, thus it is natural
that the base class for the grid controls (
CAknGrid ) inherits
the base class for listboxes CEikListBox . For details in
listboxes, please see the Lists API documentation . Because
grid controls follow the MVC design pattern, the grid control architecture
is divided into three classes: class CAknGrid implements
the controller, class CAknGridView implements the view, and
class CAknGridM implements the model component of the grid
control. The model class
CAknGridM is an abstract class specifying
the interface to the data. The model does not contain any information about
the visual presentation of the data in grid control. It should be noted that
the model class is a C-type class, so, for example, multiple inheritance of
the grid control model is more limited than in the case of listboxes. The view class
CAknGridView is responsible for the visual
appearance of the grid control. It handles rendering of cells and the cursor.
It also performs the mapping of data items to their grid cells. The controller class
CAknGrid acts as the actual user
interface component, communicating with both the model and the view components.
Related APIs
CAknGrid CAknGridM CAknGridView CEikListBox
Grid typesGrids are divided into the following types based on their functionality.
Menu gridThe menu grid is a grid control embedded in a pop-up dialog. It can be
used to provide users with a list of alternatives for performing a desired
operation. Only one item can be selected, and after selection the grid control
is destroyed along with the dialog. Control of the grid is delegated to the pop-up dialog, and its use is similar
to other dialogs on the symbian platform.
Selection gridThe selection grid allows users to select one of the available items. It
is typically used as a navigational component of the user interface, thus
serving a purpose similar to that of selection lists.
Markable gridThe markable grid allows users to select multiple items in the grid. Typically
it is used to perform one operation to each one of the selected items (for
example, to delete messages from a folder in a messaging application). The grid control for the markable grid automatically handles setting and
resetting the marker field in the data structure.
Color selection gridColor selection grid can be used when an application offers to user the
possibility to choose a color in a dialog. There is also a possibility to
select nothing.
GMS style gridThis type of grid can be used to create a photoalbum-like picture grid.
This is a markable grid with two columns displaying a bitmap. The grid is
implemented by the class
CAknGMSStyleGrid .
Related APIs
Grid format and layoutThe grid format is defined much the same way as for listboxes. There are,
however, additional formatting options due to cell composition. The following
section describes the options available for grid layout and cell formatting.
Grid layoutGrids are laid out as a two-dimensional matrix composed of horizontal rows
and vertical columns. The number of rows and columns in a grid control can
be freely specified to suit the needs of different applications. The size
of a cell in a grid can also be freely specified (considering the limitations
of the device’s screen resolution) and is the same for all of the cells. Horizontal
and vertical gaps between cells of the grid can also be specified. As there is no one obvious way to order the cells in a grid, this can be
customized as well. The ordering of cells can be done by selecting either
a horizontal or vertical axis as the primary axis. This axis then determines
the orientation of the grid. The order can be further specified by defining
the ordering (left-right, top-down) in both axes. This combination then defines
the exact ordering of data items in the grid. The scrolling behavior of the grid can also be altered. There are three
types for scrolling behavior at the edge of a grid:
-
Stop. The cursor cannot be moved beyond the edge of grid and thus is stopped
at the edge.
-
Loop. The cursor is moved to the opposite side of the grid. When trying
to move beyond the rightmost item, the cursor is moved to the leftmost item
in the same row.
-
Snake. The behavior is similar to loop, but the cursor is moved to the
next/previous row (or column), if applicable. The snaking scrolling order
is shown in Figure 6.
Cell structureAs mentioned before, cells are composed of one or more sub-cells. These
sub-cells may contain either text or graphics, and can be positioned independently
within the cell. All cells in same grid share the same cell structure. There
are typically one to three sub-cells in one cell. Figure 7 shows the typical components of a grid cell:
-
Sub-cell A contains graphics.
-
Sub-cell B contains text.
-
Sub-cell C contains a marker indicating whether the cell is selected or
not.
The format strings used in conjunction with cell formatting are similar
to those used with listboxes. The strings in the data structure are composed
of tab-delimited fields. These fields are then used to render the sub-cell,
either by using the numeric value of the field as an index to the icon array
to select the graphical icon to be drawn, or by using the Unicode string itself
as the content of the text sub-cell. The format string for item data for the cell in Figure 6 is “
2\tItem\t0 ”:
the first field contains an index to the icon array, the second field contains
the text to be displayed, and the third field is a placeholder for the marker
information. Sub-cells can be located freely within the cell. For different views, some
of the fields present in data can be omitted as well, for example to provide
a text-only view of the grid. The cell structure can be changed dynamically
at run time without the need to modify the model data or to construct the
grid control from scratch.
Related APIs
Use casesThe main use cases of Grids API are:
-
Defining a grid in resource file
-
Setting up the grid cell structure
-
Setting up sub-cell that contains graphics
-
Setting up sub-cell that contains text
-
Creating a selection grid from resource
-
Creating a selection grid with icons runtime
-
Getting the selected cell of a selection grid
-
Selecting a cell in a grid
-
Creating a menu grid
-
Creating a markable grid with icons runtime
-
Mark and unmark an item in a markable grid
-
Getting the marked items of a markable grid
-
Creating a color selection grid
-
Adding a cell to grid
-
Removing a cell from grid
-
Getting the number of cells of grid
-
Offering key events to grid
-
Handling resource events
-
Creating animated highlight
API class structure This diagram shows the general structure of Grids API.
Using Grids API
Defining a grid in resource fileGrid resources are described with the
GRID structure,
as defined in the avkon.rh file: STRUCT GRID { BYTE version = 0; WORD flags = 0; WORD height = 5; // in items WORD width = 10; // in chars LLINK array_id = 0; LTEXT emptytext = ""; LLINK style = 0; }
Important members of this structure are:
-
flags , which describes the type of the grid control to
be created.
-
style , which is a reference to the GRID_STYLE structure
described later.
-
array_id , which is a reference to an ARRAY of
strings describing the data items.
-
emptytext , which contains the text to be shown when there
are no items in the grid.
The grid type is specified in
GRID structure member flags ,
which may contain one of the following predefined values:
-
EAknListBoxMenuGrid , for menu grid type
-
EAknListBoxSelectionGrid , for selection grid type
-
EAknListBoxMarkableGrid , for multiple selection/markable
grid type
The grid style is described with the
GRID_STYLE structure,
defined in avkon.rh: STRUCT GRID_STYLE { WORD layoutflags = 0; WORD primaryscroll = 0; WORD secondaryscroll = 0; WORD itemsinprimaryorient = 0; WORD itemsinsecondaryorient = 0; WORD height = 0; WORD width = 0; WORD gapwidth = 0; WORD gapheight = 0; }
Members in the GRID_STYLE structure can be used as described below.
-
layoutflags : A set of flags describing the orientation
of the grid and the ordering of cells within the axis. Possible values for
orientation are EAknGridHorizontalOrientation or EAknGridVerticalOrientation .
The ordering of cells in the vertical axis is defined by either EAknGridTopToBottom or EAknGridBottomToTop and
in the horizontal axis by either EAknGridLeftToRight or EAknGridRightToLeft .
The symbain platform also provides flag EAknGridLanguageSpecificHorizontalDirection to
provide horizontal ordering based on the language's writing direction.
-
primaryscroll and secondaryscroll : Scrolling
behavior within the primary and secondary axes of the grid. The following
values are defined for use with these fields:
|
|
EScrollFollowsItemsAndStops
|
Snakes. Stops when scrolling beyond the first or last cell.
|
EScrollFollowsItemsAndLoops
|
Snakes. Loops to the first cell when scrolling beyond the last cell
and vice versa.
|
EScrollFollowsGrid
|
Loops.
|
EScrollStops
|
Stops.
|
-
itemsinprimaryorient and itemsinsecondaryorient :
Number of cells in primary and secondary axes.
-
width and height : Size of cell in pixels.
-
gapwidth and gapheight : Size of gap
between cells in pixels.
Note, that resource based definition of grid style is not recommended as
S60 on symbian platform supports multiple resolutions. Items contained in the grid can also be specified in the resource file.
The
array_id member of the GRID structure
is a reference to an ARRAY that contains items of type LBUF . The following resource definition defines a selection grid and its contents.
The resulting grid will be similar to the one shown in Figure 3. RESOURCE GRID r_selectiongrid { array_id = r_selectiongrid_items; flags = EAknListBoxSelectionGrid; style = r_selectiongrid_style; }
RESOURCE GRID_STYLE r_selectiongrid_style { layoutflags = EAknGridHorizontalOrientation | EAknGridLeftToRight | EAknGridTopToBottom; primaryscroll = EAknGridFollowsItemsAndLoops; secondaryscroll = EAknGridFollowsItemsAndLoops; itemsinprimaryorient = 3; itemsinsecondaryorient = 3; gapwidth = 5; gapheight = 5; width = 60; height = 60; }
RESOURCE ARRAY r_selectiongrid_items { items = { LBUF { txt = "Item0"; }, LBUF { txt = "Item1"; }, LBUF { txt = "Item2"; }, LBUF { txt = "Item3"; }, LBUF { txt = "Item4"; } }; }
Related APIs
ARRAY EAknGridBottomToTop EAknGridHorizontalOrientation EAknGridLanguageSpecificHorizontalDirection EAknGridLeftToRight EAknGridRightToLeft EAknGridTopToBottom EAknGridVerticalOrientation EAknListBoxMarkableGrid EAknListBoxMenuGrid EAknListBoxSelectionGrid EScrollFollowsGrid EScrollFollowsItemsAndLoops EScrollFollowsItemsAndStops EScrollStops GRID GRID_STYLE LBUF array_id emptytext flags gapheight gapwidth height itemsinprimaryorient itemsinsecondaryorient layoutflags primaryscroll secondaryscroll style width
Setting up the grid cell structureAs mentioned before, the cells of a grid are composed of one or more sub-cells.
This sub-cell structure must be set up before the grid control can be used.
As per the MVC design pattern, the view component of the grid control is responsible
for providing the visual presentation of the cells. Therefore the low-level
manipulation of cell structure can be made with the item drawer class. However,
the symbian platform also provides utility class
AknListBoxLayouts to
simplify the setup of the cell structure for grid controls. Class AknListBoxLayouts provides
a few static methods for grids.
AknListBoxLayouts::SetupStandardGrid() sets up the background
and foreground color settings to their default values.
Setting up sub-cell that contains graphics
AknListBoxLayouts::SetupFormGfxCell() is used to set up
the sub-cell that contains graphics. AknListBoxLayouts::SetupFormGfxCell(*iGrid, // Reference to grid control iGrid->ItemDrawer(), // Pointer to the item drawer 0, // Column index 0, // Left position 0, // Top position 0, // Right – unused 0, // Bottom – unused 50, // Width 32, // Height TPoint(0,0), // Start position TPoint(32, 32)); // End position
The following parameters must be provided when setting up a graphics sub-cell:
-
Reference to the grid itself and pointer to the grid's item drawer.
-
Column index – The field number in a tab-delimited data string to be used
to get the index to graphics.
-
Left and top positions – The number of pixels relative to the left-hand
and top sides of the cell.
-
The width and height of the graphic in pixels.
-
Start and end positions – The coordinates describing the area of the bitmap
to be drawn.
Related APIs
AknListBoxLayouts::SetupFormGfxCell()
Setting up sub-cell that contains text
AknListBoxLayouts::SetupFormTextCell() is used to set
up the sub-cell that contains text. AknListBoxLayouts::SetupFormTextCell(*iGrid, // Reference to grid iGrid->ItemDrawer(),// Pointer to the item drawer 1, // Column index LatinBold12(), // Font 215, // Color (215 = black) 0, // Left margin 0, // Right margin – unused 50 - 3, // Baseline 50, // Text width CGraphicsContext::ECenter, // Text alignment TPoint(0, 32), // Start position TPoint(50, 50)); // End position
The following parameters must be provided when setting up a text sub-cell:
-
Reference to the grid itself and a pointer to the grid's item drawer.
-
Column index. The field number in a tab-delimited data string to be used
to get the index to graphics.
-
Font used to render the text.
-
Color of the text. Index to an 8-bit palette used for the user interface
(entries 0-215 are known as Web-safe colors.
-
Left margin position. Position in pixels relative to the left-hand side
of the cell.
-
Baseline position.
-
Width of the text.
-
Alignment of the text.
-
Start and end position. The coordinates describing the text area.
Related APIs
AknListBoxLayouts::SetupFormTextCell()
Related APIs
AknListBoxLayouts AknListBoxLayouts::SetupStandardGrid()
Creating a selection grid from resourceGrid controls can be easily created from resource definitions. The resource
file used to create the grid should have both the resource definition for
the grid and the definition of the grid item array. In this example a simple
grid is created which cells have only text items. The grid is created from
resource defined in
Defining a grid in resource file.
Note, that AknListBoxLayouts::SetupFormTextCell() must be
called to define the layout of the text in the cell. For details on cell layout
please see Setting up the grid cell structure. To create a selection grid with text from code, follow these steps:
-
Create a grid instance.
-
Set the grid's container window. Since the grid is a non window-owning
control, its parent control is passed as a parameter, providing a window for
the listbox to draw to.
-
Construct the selection grid using its resource identifier.
-
Set the text layout of grid sub-cell using
AknListBoxLayouts::SetupFormTextCell() method.
-
Activate the grid.
class MyContainer : public CCoeControl { CAknGrid* iGrid; }
void MyContainer::ConstructL() { // Create grid iGrid = new( ELeave ) CAknGrid; iGrid->SetContainerWindowL( *this ); TResourceReader rr; // initialize resource reader, passing resource id as parameter iEikonEnv->CreateResourceReaderLC( rr, R_SELECTIONGRID ); // Construct grid from resource iGrid->ConstructFromResourceL( rr ); CleanupStack::PopAndDestroy(); // rr
// Setup the layout of the text in the cell. AknListBoxLayouts::SetupFormTextCell( *iGrid, iGrid->ItemDrawer(), 0, LatinBold16(), 0, 0, 0, 30, 0, CGraphicsContext::ECenter, TPoint(0,0), TPoint(0,0) ); // Activate grid iGrid->SetRect( Rect() ); iGrid->ActivateL(); }
Related APIs
AknListBoxLayouts::SetupFormTextCell()
Creating a selection grid with icons runtimeCreating grids without a resource file is not much more complicated than
creating them with a resource file. Most of the steps used to create grid
control are same in both cases. In this example a 3x3 grid is created each
grid contains an icon and a text. To create a selection grid with icons and text from code, follow these
steps:
-
Create a grid instance an a grid model instance. Set the grid's model
with the created model.
-
Use flag
EAknListBoxSelectionGrid to construct a selection
grid.
-
Set the grid's container window. Since the grid is a non window-owning
control, its parent control is passed as a parameter, providing a window for
the listbox to draw to.
-
Set the grid layout using
CAknGrid::SetLayoutL() .
-
Add cell item strings and icons to grid. Cell item string must be formatted
to contain the indexes of the icons in the icon array.
-
Set the layout of text and icon in the grid sub-cell using
AknListBoxLayouts::SetupFormGfxCell() and AknListBoxLayouts::SetupFormTextCell() methods.
-
Activate the grid.
Note that the order of the icons in the icon array (local variable
iconArray of
the method AddGridIconsL() ) defines their indexes in the
cell item string (0\tItem1 ). In this example, the first icon
added to the icon list will be indexed as zero (0 ), and the
next item, as one (1 ). The first column in the cell item
string defines the index of the icon to be displayed for the specific cell
item, the second column defines the text of the cell. The cell icons are loaded from a AVKON's bitmap file and appended to the
icon array and added to grid. class MyContainer : public CCoeControl { CAknGrid* iGrid; CAknGridM* iGridModel; }
void MyContainer::ConstructL() { … CreateWindowL(); // Create grid iGrid = new( ELeave ) CAknGrid; // Create grid model iGridModel = new( ELeave ) CAknGridM; // Construct grid iGrid->SetContainerWindowL( *this ); iGrid->SetModel( iGridModel ); iGrid->ConstructL( this, EAknListBoxSelectionGrid );
// Set grid layout, and scrolling iGrid->SetLayoutL( EFalse, ETrue, ETrue, 3/*rows*/ , 3/*columns*/, TSize( 70, 70 )/*cellsize*/, 10/*wspace*/, 10/*hspace*/ ); iGrid->SetPrimaryScrollingType( CAknGridView::EScrollIncrementLineAndLoops ); iGrid->SetSecondaryScrollingType( CAknGridView::EScrollIncrementLineAndLoops ); AknListBoxLayouts::SetupStandardGrid( *iGrid ); // Accesses grid model`s item array CDesCArray *gridItemArray = static_cast<CDesCArray*>( iGridModel->ItemTextArray() ); // Adds formatted cell item strings to grid including the indexes of icons in icon array. gridItemArray->AppendL( _L("0\tItem1") ); gridItemArray->AppendL( _L("1\tItem2") ); gridItemArray->AppendL( _L("2\tItem3") ); gridItemArray->AppendL( _L("0\tItem4") ); gridItemArray->AppendL( _L("1\tItem5") ); gridItemArray->AppendL( _L("2\tItem6") ); gridItemArray->AppendL( _L("0\tItem7") ); gridItemArray->AppendL( _L("1\tItem8") ); gridItemArray->AppendL( _L("2\tItem9") ); gridItemArray->AppendL( _L("0\tItem10") ); iGrid->HandleItemAdditionL(); // Adds ICONS from AVKON`s bitmap file AddGridIconsL(); // Set the layout of icon in grid cell AknListBoxLayouts::SetupFormGfxCell( *iGrid, iGrid->ItemDrawer(), 0 /*Column index*/, 10 /*Left pos*/, 10 /*Top pos*/, 0 /*unused*/, 0 /*unused*/, 40 /*Icon width*/, 40 /*Icon height*/, TPoint(0,0) /*Start pos*/, TPoint(0,0) /*End pos*/ ); // Set the layout of text in grid cell AknListBoxLayouts::SetupFormTextCell( *iGrid, iGrid->ItemDrawer(), 1 /*Column index*/, LatinBold16() /*Font type*/, 0 /*color*/, 0 /*Left margin*/, 0 /*unused*/, 65 /*Baseline*/, 0 /*Text width*/, CGraphicsContext::ECenter /*Text alignment*/, TPoint(0,0) /*Start pos*/, TPoint(0,0) /*End pos*/); // Activate grid iGrid->SetRect( Rect() ); iGrid->ActivateL(); … }
void MyContainer::AddGridIconsL() { CArrayPtr<CGulIcon*> iconArray = new( ELeave ) CAknIconArray( 1 ); CleanupStack::PushL( iconArray ); CFbsBitmap* addressIcon = NULL; CFbsBitmap* addressIconMask = NULL; CFbsBitmap* emailIcon = NULL; CFbsBitmap* emailIconMask = NULL; CFbsBitmap* faxIcon = NULL; CFbsBitmap* faxIconMask = NULL; AknIconUtils::CreateIconLC( addressIcon, addressIconMask, KAvkonBitmapFile, EMbmAvkonQgn_prop_nrtyp_address, EMbmAvkonQgn_prop_nrtyp_address_mask ); CGulIcon* addressListIcon = CGulIcon::NewL( addressIcon, addressIconMask ); CleanupStack::Pop( 2 ); // addressIcon, addressIconMask CleanupStack::PushL( addressListIcon ); iconArray->AppendL( addressListIcon ); AknIconUtils::CreateIconLC( emailIcon, emailIconMask, KAvkonBitmapFile, EMbmAvkonQgn_prop_nrtyp_email, EMbmAvkonQgn_prop_nrtyp_email_mask ); CGulIcon* emailListIcon = CGulIcon::NewL( emailIcon, emailIconMask ); CleanupStack::Pop( 2 ); // emailIcon, emailIconMask CleanupStack::PushL( emailListIcon ); iconArray->AppendL( emailListIcon ); AknIconUtils::CreateIconLC( faxIcon, faxIconMask, KAvkonBitmapFile, EMbmAvkonQgn_prop_nrtyp_fax, EMbmAvkonQgn_prop_nrtyp_fax_mask ); CGulIcon* faxListIcon = CGulIcon::NewL( faxIcon, faxIconMask ); CleanupStack::Pop( 2 ); // emailIcon, emailIconMask CleanupStack::PushL( faxListIcon ); iconArray->AppendL( faxListIcon );
iGrid->ItemDrawer()->ColumnData()->SetIconArray( iconArray ); // faxListIcon, emailListIcon, addressListIcon, iconArray CleanupStack::Pop( 4 ); iGrid->HandleItemAdditionL(); }
Related APIs
0 0\tItem1 1 AddGridIconsL() AknListBoxLayouts::SetupFormGfxCell() AknListBoxLayouts::SetupFormTextCell() CAknGrid::SetLayoutL() EAknListBoxSelectionGrid iconArray
Getting the selected cell of a selection gridThe menu and selection grids allow selection of one cell on the grid. The
grid instance contains the index of its currently selected cell. The index
of the currently selected cell on the menu and selection grids can be retrieved
by the following code: TInt currentIndex = iGrid->CurrentDataIndex();
Selecting a cell in a gridGrid cells can be also selected, so the selected grid is highlighted. In
this example, the second item is selected, and highlighted in the grid. iGrid->SetCurrentItemIndex( 1 );
Creating a menu gridThe menu grid is a grid control that is embedded in a pop-up dialog. This
adds a few more steps to the process of creating and using the menu grid control. Before calling the
ConstructL() method of the grid control,
the pop-up dialog must be instantiated. In this example a grid with small
icon is put into the popup dialog. To create a menu grid with small icon, follow these steps:
-
Create a grid instance an a grid model instance. Set the grid's model
with the created model.
-
Create a
CAknPopupList dialog instance, passing the created
grid instance as a parameter.
-
Construct the grid, passing the dialog instance as a parent control.
-
Set the grid layout using
CAknGrid::SetLayoutL() .
-
Add cell icons to grid. Cell item string must be formatted to contain
the indexes of the icons in the icon array.
-
Set the layout of icon in the grid sub-cell using
AknListBoxLayouts::SetupFormGfxCell() methods.
-
Execute the dialog.
Note that the order of the icons in the icon array (local variable
iconArray of
method AddGridIconsL() ) will define their indexes in the
cell item string (0\t ). In this example, the first icon added
to the icon list will be indexed as zero (0 ), and the next
item, as one (1 ). The first column in the cell item string
defines the index of the icon to be displayed for the specific cell item. The cell icons are loaded from a AVKON's bitmap file and appended to the
icon array and added to grid. class MyContainer : public CCoeControl { … CAknGrid* iGrid; CAknGridM* iGridModel; … }
void MyContainer::ConstructL() { … // Create grid iGrid = new( ELeave ) CAknGrid; // Create grid model iGridModel = new( ELeave ) CAknGridM; // Create popup dialog CAknPopupList* popupList = CAknPopupList::NewL( iGrid, R_AVKON_SOFTKEYS_SELECT_BACK ); CleanupStack::PushL( popupList ); // Set title of dialog popupList->SetTitleL( _L("Menu grid") ); // Construct grid iGrid->SetModel( iGridModel ); iGrid->ConstructL( popupList, EAknListBoxMenuGrid ); // Set grid layout, and scrolling iGrid->SetLayoutL( EFalse, ETrue, ETrue, 5/*rows*/ , 3/*columns*/, TSize( 30, 30 )/*cellsize*/, 10/*wspace*/, 10/*hspace*/ ); iGrid->SetPrimaryScrollingType( CAknGridView::EScrollIncrementLineAndLoops ); iGrid->SetSecondaryScrollingType( CAknGridView::EScrollIncrementLineAndLoops ); // Accesses grid model`s item array CDesCArray *gridItemArray = static_cast<CDesCArray*>( iGridModel->ItemTextArray() ); // Adds formatted items to grid. gridItemArray->AppendL( _L("0\t") ); gridItemArray->AppendL( _L("1\t") ); gridItemArray->AppendL( _L("2\t") ); gridItemArray->AppendL( _L("0\t") ); gridItemArray->AppendL( _L("1\t") ); gridItemArray->AppendL( _L("2\t") ); gridItemArray->AppendL( _L("0\t") ); gridItemArray->AppendL( _L("1\t") ); gridItemArray->AppendL( _L("2\t") ); gridItemArray->AppendL( _L("0\t") ); iGrid->HandleItemAdditionL(); // Adds icons from AVKON`s image file AddGridIconsL(); // Set the layout of icon in grid cell AknListBoxLayouts::SetupFormGfxCell( *iGrid, iGrid->ItemDrawer(), 0 /*Column index*/, 2 /*Left pos*/, 5 /*Top pos*/, 0 /*unused*/, 0 /*unused*/, 20 /*Icon width*/, 20 /*Icon height*/, TPoint(0,0) /*Start pos*/, TPoint(0,0) /*End pos*/ ); // Execute dialog TInt popupOk = popupList->ExecuteLD(); CleanupStack::Pop(); // popupList … }
void MyContainer::AddGridIconsL() { CArrayPtr<CGulIcon*> iconArray = new( ELeave ) CAknIconArray( 1 ); CleanupStack::PushL( iconArray ); CFbsBitmap* addressIcon = NULL; CFbsBitmap* addressIconMask = NULL; CFbsBitmap* emailIcon = NULL; CFbsBitmap* emailIconMask = NULL; CFbsBitmap* faxIcon = NULL; CFbsBitmap* faxIconMask = NULL; AknIconUtils::CreateIconLC( addressIcon, addressIconMask, KAvkonBitmapFile, EMbmAvkonQgn_prop_nrtyp_address, EMbmAvkonQgn_prop_nrtyp_address_mask ); CGulIcon* addressListIcon = CGulIcon::NewL( addressIcon, addressIconMask ); CleanupStack::Pop( 2 ); // addressIcon, addressIconMask CleanupStack::PushL( addressListIcon ); iconArray->AppendL( addressListIcon ); AknIconUtils::CreateIconLC( emailIcon, emailIconMask, KAvkonBitmapFile, EMbmAvkonQgn_prop_nrtyp_email, EMbmAvkonQgn_prop_nrtyp_email_mask ); CGulIcon* emailListIcon = CGulIcon::NewL( emailIcon, emailIconMask ); CleanupStack::Pop( 2 ); // emailIcon, emailIconMask CleanupStack::PushL( emailListIcon ); iconArray->AppendL( emailListIcon ); AknIconUtils::CreateIconLC( faxIcon, faxIconMask, KAvkonBitmapFile, EMbmAvkonQgn_prop_nrtyp_fax, EMbmAvkonQgn_prop_nrtyp_fax_mask ); CGulIcon* faxListIcon = CGulIcon::NewL( faxIcon, faxIconMask ); CleanupStack::Pop( 2 ); // emailIcon, emailIconMask CleanupStack::PushL( faxListIcon ); iconArray->AppendL( faxListIcon );
iGrid->ItemDrawer()->ColumnData()->SetIconArray( iconArray ); // faxListIcon, emailListIcon, addressListIcon, iconArray CleanupStack::Pop( 4 ); iGrid->HandleItemAdditionL(); }
Related APIs
0 0\t 1 AddGridIconsL() AknListBoxLayouts::SetupFormGfxCell() CAknGrid::SetLayoutL() CAknPopupList ConstructL() iconArray
Creating a markable grid with icons runtimeCreating grids without a resource file is not much more complicated than
creating them with a resource file. Most of the steps used to create grid
control are same in both cases. In this example a 3x3 grid is created each
grid contains an icon and a text, and selected grid cells can be marked. To create a markable grid with icons and text from code, follow these steps:
-
Create a grid instance and a grid model instance. Set the grid`s model
with the created model.
-
Use flag
EAknListBoxMarkableGrid to construct a selection
grid.
-
Set the grids's container window. Since the grid is a non window-owning
control, its parent control is passed as a parameter, providing a window for
the listbox to draw to.
-
Set the grid layout using
CAknGrid::SetLayoutL() .
-
Add cell item strings and icons to grid. Cell item string must be formatted
to contain the indexes of the cell icons, mark icon in the icon array.
-
Set the layout of icon subcell, mark icon subcell and text subcell using
AknListBoxLayouts::SetupFormGfxCell() and AknListBoxLayouts::SetupFormTextCell() methods.
-
Activate the grid.
Note that the order of the icons in the icon array (local variable
iconArray of
method AddGridIconsL() ) defines their indexes in the cell
item string (‘0\t\tItem1 ’). In this example, the first icon added to the icon list is indexed as zero
(
0 ), and the next item, as one (1 ). The
first icon in the iconarray is the mark icon for the cell, the other icons
are cell icons. The first column in the cell item string defines the index of the icon
to be displayed in the cell, the second column defines the index of the mark
icon and the third column defines the text of the cell. The mark icon index in the cell item string is initially empty (‘
1\t\tItem1 ’),
because that column is changed from code to mark a cell, using the mark icon
index of icon array. The method SetItemMarkPosition() sets
which column defines the mark icon index in cell item string, and the method SetItemMarkReplacement() sets
what index to replace in that column. In this example the second column defines the mark icon index, and the
mark icon is the first icon in the icon array. So to mark a cell the following
is needed. // Set the second column of cell as markable icon index iGrid->ItemDrawer()->SetItemMarkPosition(1);
// Set the item mark replacement string iGrid->ItemDrawer()->SetItemMarkReplacement( _L("0") );
// Don't display all items as marked initially iGrid->ItemDrawer()->SetItemMarkReverse( ETrue );
After defining which column defines the mark icon index in cell item string,
if a cell is marked, its cell item string looks like this: ‘
1\t0\tItem1 ’. The mark icons and cell icons are loaded from a AVKON's bitmap file and
appended to the icon array and added to grid. class MyContainer : public CCoeControl { … CAknGrid* iGrid; CAknGridM* iGridModel; … }
void MyContainer::ConstructL() { … CreateWindowL(); // Create grid iGrid = new( ELeave ) CAknGrid; // Create grid model iGridModel = new( ELeave ) CAknGridM; // Construct grid iGrid->SetContainerWindowL( *this ); iGrid->SetModel( iGridModel ); iGrid->ConstructL( this, EAknListBoxMarkableGrid );
// Set grid layout, and scrolling iGrid->SetLayoutL( EFalse, ETrue, ETrue, 3/*rows*/ , 3/*columns*/, TSize( 70, 70 )/*cellsize*/, 10/*wspace*/, 10/*hspace*/ ); iGrid->SetPrimaryScrollingType( CAknGridView::EScrollIncrementLineAndLoops ); iGrid->SetSecondaryScrollingType( CAknGridView::EScrollIncrementLineAndLoops ); AknListBoxLayouts::SetupStandardGrid( *iGrid ); // Accesses grid model`s item array CDesCArray *gridItemArray = static_cast<CDesCArray*>( iGridModel->ItemTextArray() ); // Adds formatted cell item strings to grid. gridItemArray->AppendL( _L("1\t\tItem1") ); gridItemArray->AppendL( _L("2\t\tItem2") ); gridItemArray->AppendL( _L("3\t\tItem3") ); gridItemArray->AppendL( _L("1\t\tItem4") ); gridItemArray->AppendL( _L("2\t\tItem5") ); gridItemArray->AppendL( _L("3\t\tItem6") ); gridItemArray->AppendL( _L("1\t\tItem7") ); gridItemArray->AppendL( _L("2\t\tItem8") ); gridItemArray->AppendL( _L("3\t\tItem9") ); gridItemArray->AppendL( _L("1\t\tItem10") ); iGrid->HandleItemAdditionL(); // Adds ICONS from AVKON`s image file AddGridIconsL(); // Set the layout of icon in grid cell AknListBoxLayouts::SetupFormGfxCell( *iGrid, iGrid->ItemDrawer(), 0 /*Column index*/, 10 /*Left pos*/, 10 /*Top pos*/, 0 /*unused*/, 0 /*unused*/, 40 /*Icon width*/, 40 /*Icon height*/, TPoint(0,0) /*Start pos*/, TPoint(0,0) /*End pos*/ ); // Set the layout of mark icon in grid cell AknListBoxLayouts::SetupFormGfxCell( *iGrid, iGrid->ItemDrawer(), 1 /*Column index*/, 50 /*Left pos*/, 0 /*Top pos*/, 0 /*unused*/, 0 /*unused*/, 20 /*Icon width*/, 20 /*Icon height*/, TPoint(0,0) /*Start pos*/, TPoint(0,0) /*End pos*/ ); // Set the layout of text in grid cell AknListBoxLayouts::SetupFormTextCell( *iGrid, iGrid->ItemDrawer(), 2 /*Column index*/, LatinBold16() /*Font type*/, 0 /*color*/, 0 /*Left margin*/, 0 /*unused*/, 65 /*Baseline*/, 0 /*Text width*/, CGraphicsContext::ECenter /*Text alignment*/, TPoint(0,0) /*Start pos*/, TPoint(0,0) /*End pos*/); // Set index of the placeholder field iGrid->ItemDrawer()->SetItemMarkPosition(1);
// Set the item mark replacement string iGrid->ItemDrawer()->SetItemMarkReplacement( _L("0") );
// Don't display all items as marked initially iGrid->ItemDrawer()->SetItemMarkReverse( ETrue ); // Mark the second item in the grid iGrid->View()->SelectItemL( 1 ); // Activate grid iGrid->SetRect( Rect() ); iGrid->ActivateL(); … }
void MyContainer::AddGridIconsL() { CArrayPtr<CGulIcon*> iconArray = new( ELeave ) CAknIconArray( 1 ); CleanupStack::PushL( iconArray ); CFbsBitmap* gridMarkIcon = NULL; CFbsBitmap* gridMarkIconMask = NULL; CFbsBitmap* addressIcon = NULL; CFbsBitmap* addressIconMask = NULL; CFbsBitmap* emailIcon = NULL; CFbsBitmap* emailIconMask = NULL; CFbsBitmap* faxIcon = NULL; CFbsBitmap* faxIconMask = NULL; AknIconUtils::CreateIconLC( gridMarkIcon, gridMarkIconMask, KAvkonBitmapFile, EMbmAvkonQgn_indi_marked_grid_add, EMbmAvkonQgn_indi_marked_grid_add_mask ); CGulIcon* markIcon = CGulIcon::NewL( gridMarkIcon, gridMarkIconMask ); CleanupStack::Pop( 2 ); // gridMarkIcon, gridMarkIconMask CleanupStack::PushL( markIcon ); iconArray->AppendL( markIcon ); AknIconUtils::CreateIconLC( addressIcon, addressIconMask, KAvkonBitmapFile, EMbmAvkonQgn_prop_nrtyp_address, EMbmAvkonQgn_prop_nrtyp_address_mask ); CGulIcon* addressListIcon = CGulIcon::NewL( addressIcon, addressIconMask ); CleanupStack::Pop( 2 ); // addressIcon, addressIconMask CleanupStack::PushL( addressListIcon ); iconArray->AppendL( addressListIcon ); AknIconUtils::CreateIconLC( emailIcon, emailIconMask, KAvkonBitmapFile, EMbmAvkonQgn_prop_nrtyp_email, EMbmAvkonQgn_prop_nrtyp_email_mask ); CGulIcon* emailListIcon = CGulIcon::NewL( emailIcon, emailIconMask ); CleanupStack::Pop( 2 ); // emailIcon, emailIconMask CleanupStack::PushL( emailListIcon ); iconArray->AppendL( emailListIcon ); AknIconUtils::CreateIconLC( faxIcon, faxIconMask, KAvkonBitmapFile, EMbmAvkonQgn_prop_nrtyp_fax, EMbmAvkonQgn_prop_nrtyp_fax_mask ); CGulIcon* faxListIcon = CGulIcon::NewL( faxIcon, faxIconMask ); CleanupStack::Pop( 2 ); // emailIcon, emailIconMask CleanupStack::PushL( faxListIcon ); iconArray->AppendL( faxListIcon );
iGrid->ItemDrawer()->ColumnData()->SetIconArray( iconArray ); // faxListIcon, emailListIcon, addressListIcon, markIcon, iconArray CleanupStack::Pop( 5 ); iGrid->HandleItemAdditionL(); }
Related APIs
0 0\t\tItem1 1 1\t0\tItem1 1\t\tItem1 AddGridIconsL() AknListBoxLayouts::SetupFormGfxCell() AknListBoxLayouts::SetupFormTextCell() CAknGrid::SetLayoutL() EAknListBoxMarkableGrid SetItemMarkPosition() SetItemMarkReplacement() iconArray
Mark and unmark an item in a markable gridThis example shows how to change the mark states of a markable grid cell. // Marks the second cell of the grid iGrid->View()->SelectItemL(1); // Unmarks the first cell of the grid iGrid->View()->DeselectItem(0);
Getting the marked items of a markable gridMarkable grids allow multiple cells to be selected, as well as one cell
or none at all. An array of the indexes of the selected cells can be requested
from these grids. The indexes are returned by the grid as an array of type
CSelectionIndexArray ,
which is essentially just a typedef of CArrayFix . The following
code example demonstrates how to retrieve the array of selected items from
a markable grid: // Get the selected item indexes an array const CArrayFix<TInt> *selectedIndexes = iGrid->SelectionIndexes();
// Make sure the array is not null (no items) if ( selectedIndexes != NULL ) { // Loop through the selected cell indexes for ( TInt index=0; index < selectedIndexes->Count(); index++ ) { // Get the index of the selected cell TInt selectedItemIndex = (*selectedIndexes)[index]; // now do something with the index } }
Related APIs
CArrayFix CSelectionIndexArray
Creating a color selection gridIn this example, a color selection grid is created, with four colors, and
the green color is selected initially. … TBool noneExist = ETrue; TBool noneChosen = EFalse; TRgb colour = KRgbGreen; // Select green color initially CArrayFixFlat<TRgb*> colours = new( ELeave ) CArrayFixFlat<TRgb*> ( 6 );
// Adds colors to grid colours->AppendL( KRgbBlack ); colours->AppendL( KRgbDarkGray ); colours->AppendL( KRgbGreen ); colours->AppendL( KRgbYellow ); // Create the color selection dialog CAknColourSelectionGrid* dialog = CAknColourSelectionGrid::NewL( colours, noneExist, noneChosen, colour ); dialog->ExecuteLD(); // Cleanup colours->Reset(); delete colours; …
Adding a cell to gridNew cells are added to the grid by appending a new cell item string to
the grid`s cell item array. First, the grid cell item array is retrieved from
the grid. A new cell item string is then appended to the existing grid cell
item array and the grid is requested to handle the addition of a new cell
item. The
HandleItemAdditionL() method handles the grid redrawing
and repositions the selection in a sensible state. The following example code adds a new cell item string to a grid: // Get grid cell item array MDesCArray* textArray = iGrid->Model()->ItemTextArray(); CDesCArray* cellItemStringArray = static_cast<CDesCArray>( textArray ); cellItemStringArray->AppendL(( _L("1\t\tItem11") ) ); // Update grid iGrid->HandleItemAdditionL();
Related APIs
Removing a cell from gridTo remove cells from the grid, first the listbox item array must be get
from the grid. Cells are deleted from the cell list array by specifying the
index of the cell to be deleted and the number of cells to be deleted. The
grid is requested to handle the cell deletion and redraw itself to show the
changes. The following example code removes the fifth cell from a grid: // Get grid cell item array MDesCArray* textArray = iGrid->Model()->ItemTextArray(); CDesCArray* cellItemStringArray = static_cast<CDesCArray*>( textArray ); // Delete fifth cell cellItemStringArray->Delete( 5, 1 ); // Handle item deletion and reposition grid highlight AknListBoxUtils::HandleItemRemovalAndPositionHighlightL( iGrid, 5, ETrue ); // Redraw grid iGrid->DrawNow();
Multiple contiguous items can also be deleted by specifying the count of
the contiguous items to be deleted as the second parameter of the
Delete() method.
In the example above, only the fifth item is deleted by specifying the count
as one (1 ).
Related APIs
Getting the number of cells of gridThis example shows how to get the number of listbox items. TInt gridItems = iGrid->Model()->NumberOfItems();
Offering key events to gridIf the grid is a component of a compound control, it is needed to inform
the grid about key events. It is simply forwarding the event to the grid from
the component's
OfferKeyEventL() method. TKeyResponse MyContainer::OfferKeyEventL(const TKeyEvent& aKeyEvent, TEventCode aType) { return iGrid->OfferKeyEventL( aKeyEvent, aType ); }
Related APIs
Handling resource eventsIf a custom grid is created or it is needed to handle situations where
the theme is changed and grid needs to display different icons,
HandleResourceChange() must
be implemented. void MyContainer::HandleResourceChange( TInt aType ) { // Call base class first CAknSingleGraphicStyleListBox::HandleResourceChange( aType ); if ( aType == KAknsMessageSkinChange ) { // Handle skin change here... } }
Related APIs
Creating animated highlightIf the current skin supports animated highlight, it is only visible on
grid if the focus is set to grid. This example shows how to set the focus
on grid.
iGrid is a pointer to CAknGrid . void MyContainer::FocusChanged( TDrawNow aDrawNow ) { CCoeControl::FocusChanged( aDrawNow ); if( iGrid ) { iGrid->SetFocus( IsFocused(), aDrawNow ); } }
Related APIs
Error handlingGrids uses standard Symbian platform error reporting mechanism. Possible panic
circumstances and panic codes are indicated in class or method descriptions. Leaves and system wide error codes as function return values are used if
the error is recoverable. A client application can handle these errors similarly
as a normal Symbian platform application. Exception handling is not needed, except when setting up a layout in the
SizeChanged() method,
which needs to allocate memory.
Related APIs
Memory overheadThe amount of reserved memory for grid depend on the application, but despite
the application the amount of reserved memory is relatively small.
Limitations of the APINone.
Glossary
Abbreviations
Grids API abbreviations
API |
Application Programming Interface |
AVKON
|
Symbian extensions and modifications to Uikon and other parts of the Symbian
platform application framework.
|
MVC
|
Model-View-Controller (design pattern)
|
Copyright ©2010 Nokia Corporation and/or its subsidiary(-ies). All rights reserved. License: EPL
|