Grids API: Using Grids API

Defining a grid in resource file

Grid 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:

The grid type is specified in GRID structure member flags, which may contain one of the following predefined values:

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.

Flag value Description
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.

Note, that resource based definition of grid style is not recommended as S60 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"; }
		};
	}

Setting up the grid cell structure

As 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 S60 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:

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:

Creating a selection grid from resource

Grid 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:

  1. Create a grid instance.
  2. 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.
  3. Construct the selection grid using its resource identifier.
  4. Set the text layout of grid sub-cell using AknListBoxLayouts::SetupFormTextCell() method.
  5. 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();
     }

Creating a selection grid with icons runtime

Creating 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:

  1. Create a grid instance an a grid model instance. Set the grid's model with the created model.
  2. Use flag EAknListBoxSelectionGrid to construct a selection grid.
  3. 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.
  4. Set the grid layout using CAknGrid::SetLayoutL().
  5. 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.
  6. Set the layout of text and icon in the grid sub-cell using AknListBoxLayouts::SetupFormGfxCell() and AknListBoxLayouts::SetupFormTextCell() methods.
  7. 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();
    }

Getting the selected cell of a selection grid

The 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 grid

Grid 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 grid

The 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:

  1. Create a grid instance an a grid model instance. Set the grid's model with the created model.
  2. Create a CAknPopupList dialog instance, passing the created grid instance as a parameter.
  3. Construct the grid, passing the dialog instance as a parent control.
  4. Set the grid layout using CAknGrid::SetLayoutL().
  5. Add cell icons to grid. Cell item string must be formatted to contain the indexes of the icons in the icon array.
  6. Set the layout of icon in the grid sub-cell using AknListBoxLayouts::SetupFormGfxCell() methods.
  7. 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();
    }

Creating a markable grid with icons runtime

Creating 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:

  1. Create a grid instance and a grid model instance. Set the grid`s model with the created model.
  2. Use flag EAknListBoxMarkableGrid to construct a selection grid.
  3. 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.
  4. Set the grid layout using CAknGrid::SetLayoutL().
  5. 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.
  6. Set the layout of icon subcell, mark icon subcell and text subcell using AknListBoxLayouts::SetupFormGfxCell() and AknListBoxLayouts::SetupFormTextCell() methods.
  7. 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();
    }

Mark and unmark an item in a markable grid

This 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 grid

Markable 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
        }
    }

Creating a color selection grid

In 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 grid

New 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();

Removing a cell from grid

To 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).

Getting the number of cells of grid

This example shows how to get the number of listbox items.

TInt gridItems = iGrid->Model()->NumberOfItems();

Offering key events to grid

If 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 );
    }

Handling resource events

If 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...
        }
    }

Creating animated highlight

If 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 );
        }
    }

Error handling

Grids uses standard Symbian OS 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.

Memory overhead

The 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 API

None.

Copyright © Nokia Corporation 2001-2008
Back to top