s60 platform avkon ui resources grids v1 1 en

8/6/2019 s60 Platform Avkon Ui Resources Grids v1 1 En

1/21

S60 Platform: Avkon

UI Resources Grids

S60

p

l

a

t

f

o

r

m

Version 1.1November 2, 2005


2/21

S60 Platform: Avkon UI Resources Grids | 2

Legal Notice

Copyright 2005 Nokia Corporation. All rights reserved.

Nokia and Nokia Connecting People are registered trademarks of Nokia Corporation.Java and all Java-based marks are trademarks or registered trademarks of SunMicrosystems, Inc. Other product and company names mentioned herein may betrademarks or trade names of their respective owners.

Disclaimer

The information in this document is provided as is, with no warranties whatsoever,including any warranty of merchantability, fitness for any particular purpose, or anywarranty otherwise arising out of any proposal, specification, or sample. Furthermore,information provided in this document is preliminary, and may be changed substantiallyprior to final release. This document is provided for informational purposes only.

Nokia Corporation disclaims all liability, including liability for infringement of anyproprietary rights, relating to implementation of information presented in this document.Nokia Corporation does not warrant or represent that such use will not infringe suchrights.

Nokia Corporation retains the right to make changes to this specification at any time,without notice.

License

A license is hereby granted to download and print a copy of this specification forpersonal use only. No other license to any other intellectual property rights is grantedherein.

Version 1.1 | November 2, 2005


3/21


Contents

1. Introduction ......................................................................................................... 52. Grid Architecture................................................................................................. 63. Grid Types............................................................................................................ 7

3.1 Menu Grid........................................................................................................................73.2 Selection Grid..................................................................................................................73.3 Markable Grid..................................................................................................................8

4. Grid Format and Layout...................................................................................... 94.1 Cell Structure ..................................................................................................................94.2 Grid Layout......................................................................................................................9

5. Creating Grid Controls...................................................................................... 115.1 Grid Resource Structures..............................................................................................115.2 Creating Grid Control from a Resource File..................................................................135.3 Creating Grid Control Without a Resource File.............................................................135.4 Creating the Menu Grid.................................................................................................145.5 Creating a Markable Grid..............................................................................................14

6. Managing Grid Layout and Contents .............................................................. 166.1 Setting Up the Cell Structure.........................................................................................166.2 Accessing Selected Items.............................................................................................176.3 Adding Items to the Grid ...............................................................................................186.4 Removing Items from the Grid ......................................................................................186.5 Loading Graphics..........................................................................................................19

7. Terms and Abbreviations ................................................................................. 208. Evaluate This Resource.................................................................................... 21



4/21


Change History

November 9, 2004 Version 1.0 Initial document release

November 2, 2005 Version 1.1 Updated to cover S60 3rd

Edition.

Minor terminology update.



5/21


1 . I n t ro d u c t i o n

Grids are used extensively on the S60 platform to represent a compact view of the data

structure using graphics and/or text. This document introduces readers to grid use on theS60 platform.

Items from the data structure are represented by cells in the grid view. A cell can befurther divided into sub-cells, which contain graphics or text. Depending on the screensize, cell size, and number of items in the data structure, all or some of the cells arevisible concurrently. Grid controls provide users with a mechanism to navigate betweenthe cells. Grids are also scrollable, thus enabling access to all items in the datastructure.

Like other user interface components on the S60 platform, grids follow the Model-View-Controller (MVC) design pattern.

Using listboxes is another common way to represent a set of items on the S60 platform.While grids share a great deal of functionality with listboxes, the fundamental differenceis that a grid may contain more than one item per line, thus providing a more compactview over the data. This compactness comes at a cost: the amount of information peritem in a grid is more limited than in a listbox. Therefore grids are more suitable fordisplaying easily distinguishable items, such as applications or available commands inone application, or items that are naturally represented as a grid, such as a monthlycalendar view.

There are many different types of grids available on the S60 platform. These types aredesigned to fulfill the requirements of different kinds of data structures and use casesrelated to representing a set of items in a compact way.

This document covers the menu grid, the selection grid, and the markable grid. Themenu grid provides users with a collection of available actions and allows them toproceed with one. The selection grid provides a view where users can navigate betweenitems and then select one or more. The markable grid allows users to navigate andselect items, and then execute a command to each of them. Code samples throughoutthis document demonstrate how to create the different types of grids. The screen shotshave been taken from S60 3

rdEdition.

In addition to having different types of grids, the grid layout itself can be altered. Thenumber of visible rows and columns can be altered, along with the presentation andcomposition of cells. These options are explained thoroughly with code samples.



6/21


2 . G r i d A rc h i te c tu re

Grid 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 listboxesCEikListBox. Because grid controls follow the MVC design pattern, the grid controlarchitecture is divided into three classes: class CAknGrid implements the controller,class CAknGridView implements the view, and class CAknGridM implements the modelcomponent of the grid control.

The model class CAknGridM is an abstract class specifying the interface to the data. Themodel does not contain any information about the visual presentation of the data in gridcontrol. 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 oflistboxes.

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 dataitems to their grid cells.

The controller class CAknGrid acts as the actual user interface component,communicating with both the model and the view components.

Figure 1: Class hierarchy



7/21


3 . Gr id Types

The S60 platform provides several grid types, which are introduced in this chapter.

3.1 Menu Grid

Figure 2: Menu grid

The menu grid is a grid control embedded in a pop-up dialog. It can be used to provideusers with a list of alternatives for performing a desired operation. Only one item can beselected, 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 otherdialogs on the S60 platform.

3.2 Selection Grid

Figure 3: Selection grid

The 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 ofselection lists.



8/21


3.3 Markable Grid

Figure 4: Markable grid

The markable grid allows users to select multiple items in the grid. Typically it is used toperform one operation to each one of the selected items (for example, to deletemessages from a folder in a messaging application).

The grid control for the markable grid automatically handles setting and resetting themarker field in the data structure.



9/21


4 . G r i d F o rm a t a n d L a yo u t

The 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 theoptions available for grid layout and cell formatting.

4.1 Cell Structure

As mentioned before, cells are composed of one or more sub-cells. These sub-cells maycontain either text or graphics, and can be positioned independently within the cell. Allcells in same grid share the same cell structure. There are typically one to three sub-cells in one cell.

AC

B

Figure 5: Cell structure

Figure 5 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 withlistboxes. The strings in the data structure are composed of tab-delimited fields. Thesefields are then used to render the sub-cell, either by using the numeric value of the fieldas an index to the icon array to select the graphical icon to be drawn, or by using theUnicode string itself as the content of the text sub-cell.

The format string for item data for the cell in Figure 5 is 2\t1 Item\t0: the first fieldcontains 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 fieldspresent in data can be omitted as well, for example to provide a text-only view of thegrid. The cell structure can be changed dynamically at run time without the need tomodify the model data or to construct the grid control from scratch.

4.2 Grid Layout

Grids are laid out as a two-dimensional matrix composed of horizontal rows and verticalcolumns. The number of rows and columns in a grid control can be freely specified tosuit the needs of different applications. The size of a cell in a grid can also be freelyspecified (considering the limitations of the devices screen resolution) and is the same

for all of the cells. Horizontal and vertical gaps between cells of the grid can also bespecified.



10/21


As there is no one obvious way to order the cells in a grid, this can be customized aswell. The ordering of cells can be done by selecting either a horizontal or vertical axis asthe primary axis. This axis then determines the orientation of the grid. The order can befurther specified by defining the ordering (left-right, top-down) in both axes. Thiscombination will then define the exact ordering of data items in the grid.

The scrolling behavior of the grid can also be altered. There are three types for scrollingbehavior at the edge of a grid:

Stop. The cursor cannot be moved beyond the edge of grid and thus isstopped at the edge.

Loop. The cursor is moved to the opposite side of the grid. When trying tomove beyond the rightmost item, the cursor is moved to the leftmost item inthe same row.

Snake. The behavior is similar to loop, but the cursor is moved to thenext/previous row (or column), if applicable. The snaking scrolling order isshown in Figure 6.

Figure 6: Snaking scrolling order



11/21


5 . C re a t i n g G r i d C o n t ro l s

5.1 Grid Resource Structures

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 charsLLINK 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 dataitems.

emptytext, which contains the text to be shown when there are no items inthe 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 (see Section 3.1, Menu Grid)

EAknListBoxSelectionGrid for selection grid type (see Section 3.2,Selection Grid)

EAknListBoxMarkableGrid for multiple selection/markable grid type (seeSection 3.3, Markable Grid)

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 theordering of cells within the axis. Possible values for orientation are

EAknGridHorizontalOrientation orEAknGridVerticalOrientation .The ordering of cells in the vertical axis is defined by either



12/21


EAknGridTopToBottom orEAknGridBottomToTop and in the horizontalaxis by eitherEAknGridLeftToRight orEAknGridRightToLeft . The S60platform also provides flagEAknGridLanguageSpecificHorizontalDirection to provide horizontalordering based on the languages writing direction.

primaryscroll and secondaryscroll: Scrolling behavior within theprimary and secondary axes of the grid. The following values are defined foruse with these fields:

Flag value Description

EScrollFollowsItemsAndStops Snakes. Stops when scrolling beyond thefirst or last cell.

EScrollFollowsItemsAndLoops Snakes. Loops to the first cell whenscrolling beyond the last cell and viceversa.

EScrollFollowsGrid Loops.

EScrollStops Stops.

itemsinprimaryorient and itemsinsecondaryorient : Number of cellsin primary and secondary axes.

width and height: Size of cell in pixels.

gapwidth and gapheight: Size of gap between cells in pixels.

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 typeLBUF.

The following resource definition defines a selection grid and its contents. The resultinggrid 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 = 50;height = 50;

}



13/21


RESOURCE ARRAY r_selectiongrid_items{items =

{LBUF { txt = "0\tItem 0"; },LBUF { txt = "1\tItem 1"; },LBUF { txt = "2\tItem 2"; },LBUF { txt = "3\tItem 3"; },LBUF { txt = "0\tItem 4"; },LBUF { txt = "1\tItem 5"; },LBUF { txt = "2\tItem 6"; }};

}

5.2 Creating Grid Control from a Resource File

Grid controls can be easily created from resource definitions. The resource file used tocreate the grid should have both the resource definition for the grid and the definition ofthe grid item array.

Creation of grid control from a resource file is a five-step process:

1. Create CAknGrid instance:iGrid = new( ELeave ) CAknGrid;

2. Set the container window for grid control:iGrid->SetContainerWindowL( *this );

3. Instantiate the resource reader for the grid resource:TResourceReader reader;CEikonEnv::Static()->CreateResourceReaderLC(reader, gridResource);

4. Call ConstructFromResourceL for the grid object:

iGrid->ConstructFromResourceL(reader); 5. Set up the sub-cell structure (see Section 6.1, Setting Up the Cell Structure) and

load graphics (Section 6.5, Loading Graphics), if needed.

5.3 Creating Grid Control Without a Resource File

Creating grids without a resource file is not much more complicated than creating themwith a resource file. Most of the steps used to create grid control are same in both cases.There is, however, one extra step to apply grid style that would otherwise have beenread from the resource definition.

Creation of grid control without a resource file:

1. Create CAknGrid instance:iGrid = new( ELeave ) CAknGrid;

2. Set the container window for grid control:iGrid->SetContainerWindowL( *this );

3. Create a model and attach it to grid control:iGridM = new( ELeave ) CAknGridM;iGrid->SetModel( iGridM );

4. Call ConstructL for the grid object:TInt gridFlags = EAknListBoxSelectionGrid;iGrid->ConstructL( this, gridFlags);



14/21


5. Apply grid style:TScrollingType iVerticalScrollingType =

CAknGridView::EScrollIncrementLineAndLoops;TScrollingType iHorizontalScrollingType =

CAknGridView::EScrollIncrementLineAndLoops;

TBool iVerticalOrientation = EFalse;TBool iTopToBottom = ETrue;TBool iLeftToRight = ETrue;

iGrid->SetLayoutL( iVerticalOrientation,iLeftToRight, iTopToBottom,iNumOfRows, iNumOfColumns,iCellSize );

iGrid->SetPrimaryScrollingType( iVerticalScrollingType );iGrid->SetSecondaryScrollingType( iHorizontalScrollingType );

6. Set up the sub-cell structure (see Section 6.1, Setting Up the Cell Structure) andload graphics (Section 6.5, Loading Graphics), if needed.

5.4 Creating the Menu Grid

The menu grid is a grid control that is embedded in a pop-up dialog. This adds a fewmore 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 beinstantiated:

// Create an instance of popup dialogCAknPopupList* popupList = CAknPopupList::NewL( iGrid,

R_AVKON_SOFTKEYS_SELECT_BACK );CleanupStack::PushL(popupList);

// Set title for the popup dialogpopupList->SetTitleL(_L("Menu grid"));

The second phase constructor of the menu grid is then called:

iGrid->ConstructL( popupList, CEikListBox::ELeftDownInViewRect );

After completing the other steps required for setting up the grid control, the menu gridcan be used through the pop-up dialog instance:

TInt popupOk = popupList->ExecuteLD();CleanupStack::Pop(); // popupList

5.5 Creating a Markable Grid

Markable grids automatically manage the state of the cells. The mark placeholder indexand the item mark replacement string must be specified to enable this feature:

// Set index of the placeholder fieldiGrid->ItemDrawer()->SetItemMarkPosition(2);

// Set the item mark replacement string_LIT(KMarkOnValue, "1");iGrid->ItemDrawer()->SetItemMarkReplacement(KMarkOnValue);

// Dont display all items as marked initiallyiGrid->ItemDrawer()->SetItemMarkReverse(ETrue);

In order to get the mark to appear in the cell, it must be defined as a graphic sub-cell. Inaddition, two icons are needed in the icon array, one for the marked and one for the



15/21


unmarked state. The placeholder field in items in the data structure should initiallycontain the index to the unmarked state icon, and the item mark replacement stringshould contain the index to the marked state icon.



16/21


6 . M a n a g i n g G r i d L a yo u t a n d C o n te n ts

6.1 Setting Up the Cell Structure

As mentioned before, the cells of a grid are composed of one or more sub-cells. Thissub-cell structure must be set up before the grid control can be used. As per the MVCdesign pattern, the view component of the grid control is responsible for providing thevisual presentation of the cells. Therefore the low-level manipulation of cell structure canbe made with the item drawer class. However, the S60 platform also provides utilityclass 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 andforeground color settings to their default values.

// Setup text foreground and background colors to defaultAknListBoxLayouts::SetupStandardGrid( *iGrid );

AknListBoxLayouts::SetupFormGfxCell is used to set up the sub-cellthat contains graphics.

// Setup the graphics subcellAknListBoxLayouts::SetupFormGfxCell(

*iGrid, // Reference to grid controliGrid->ItemDrawer(), // Pointer to the item drawer0, // Column index0, // Left position0, // Top position0, // Right - unused

0, // Bottom - unused50, // Width32, // HeightTPoint(0,0), // Start positionTPoint(32, 32)); // End position

The following parameters must be provided when setting up a graphics sub-cell:

o Reference to the grid itself and pointer to the grids item drawer.

o Column index The field number in a tab-delimited data string to beused to get the index to graphics.

o Left and top positions The number of pixels relative to the left-hand andtop sides of the cell.

o The width and height of the graphic in pixels.

o Start and end positions The coordinates describing the area of thebitmap to be drawn.

AknListBoxLayouts::SetupFormTextCell is used to set up the sub-cellthat contains text.

// Setup the text subcellAknListBoxLayouts::SetupFormTextCell(

*iGrid, // Reference to gridiGrid->ItemDrawer(), // Pointer to the item drawer1, // Column indexLatinBold12(), // Font



17/21


215, // Color (215 = black)0, // Left margin0, // Right margin - unused50 - 3, // Baseline50, // Text widthCGraphicsContext::ECenter, // Text alignmentTPoint(0, 32), // Start positionTPoint(50, 50)); // End position

The following parameters must be provided when setting up a text sub-cell:

o Reference to the grid itself and a pointer to the grids item drawer.

o Column index The field number in a tab-delimited data string to beused to get the index to graphics.

o Font used to render the text.

o Color of the text Index to an 8-bit palette used for the user interface(entries 0-215 are known as Web-safe colors; for a complete list, see the

Series 60 UI Style Guide, Appendix A).

o Left margin position Position in pixels relative to the left-hand side ofthe cell.

o Baseline position.

o Width of the text.

o Alignment of the text.

o Start and end position The coordinates describing the text area.

6.2 Accessing Selected Items

Menu grids and selection grids allow one item to be selected. The index of the selecteditem can be retrieved from the grid control instance with the following code:

TInt currentItem = iGrid->CurrentDataIndex();

Markable grids allow more than one item to be selected at once. The selection status ofindividual items can be obtained from the view component of the grid control. Thefollowing code iterates through items, and calls method HandleSelectedItemL foreach selected item:

// Get number of items in gridTInt items = iGridM->NumberOfData();

// Get pointer to grid view componentCListBoxView* view = iGrid->View();

// Iterate through items and handle selected itemsfor(TInt i = 0; i < items; i++ )

{if(view->ItemIsSelected(i))

{HandleSelectedItemL(i);}

}



18/21


6.3 Adding Items to the Grid

Adding items to the grid is done the same way as with listboxes. The procedure containsthree steps:

Obtaining a pointer to the item array from the grid model component.

Adding the items to the array.

Notifying the grid control about the item addition.

The following code will append four items to the grid:

// Get the text array for itemsMDesCArray *array = iGridM->ItemTextArray();CDesCArray *cArray = static_cast(array);

// Format string for markable grid_LIT(KFormatString, "%d\tItem %d\t0");

// Create 4 itemsfor(TInt i = 0; i < 4; i++)

{TBuf buf;TInt iconIndex = i+2;buf.Format(KFormatString, iconIndex, i);cArray->AppendL(buf);}

// Notify the grid control of item additioniGrid->HandleItemAdditionL();

6.4 Removing Items from the Grid

Removing items from the grid is done much the same way as with listboxes. Theprocedure contains three steps:

Obtaining a pointer to the item array from the grid model component.

Removing the desired items from the array.

Notifying the grid control about the item removal.

The following code will remove the currently selected item from the selection grid:

// Get currently selected data item indexTInt currentItem = iGrid->CurrentDataIndex();

// Get the text array for itemsMDesCArray* array = iGridM->ItemTextArray();CDesCArray* cArray = static_cast(array);

// Delete currently selected itemcArray->Delete(currentItem, 1);

// Handle item deletioniGrid->HandleItemRemovalL();



19/21


6.5 Loading Graphics

The procedure to load graphics to a grid control is similar to that of listboxes.

The following code loads one icon from avkon.mbm and attaches it to the grid control:

// Create icon array with granularity of 1 iconCArrayPtr< CGulIcon >* icons = new(ELeave) CAknIconArray(1);CleanupStack::PushL( icons );

_LIT(KMbmPath, "Z:\\system\\data\\avkon.mbm");

// Load the bitmap for mail iconCFbsBitmap* bitmap = iEikonEnv->CreateBitmapL( KMbmPath,

EMbmAvkonQgn_note_mail);CleanupStack::PushL( bitmap );

// Load the mask for mail iconCFbsBitmap* mask = iEikonEnv->CreateBitmapL( KMbmPath,

EMbmAvkonQgn_note_mail_mask );

CleanupStack::PushL( mask );

// Append the mail icon to icon arrayicons->AppendL( CGulIcon::NewL( bitmap, mask ) );CleanupStack::Pop(2); // bitmap, mask

// Attach icon array to grids item draweriGrid->ItemDrawer()->FormattedCellData()->SetIconArrayL( icons );

CleanupStack::Pop(); // icons



20/21


7 . Te rm s a n d A b b re v i a t i o n s

Term orabbreviation

Meaning

ARRAY A resource structure that holds a variable-length array of otherresource structures.

LBUF A resource structure that holds one leading-byte-count, no-terminating-null string.

MBM Multi-bitmap. A bitmap (file) containing multiple bitmaps.

MVC Model-View-Controller (design pattern).



21/21



8 . E va l u a te T h i s R e s o u rc e

Please spare a moment to help us improve documentation quality and recognize the

resources you find most valuable, by rating this resource.
http://www.forum.nokia.com/main/1%2C%2C90%2C00.html?surveyId=2563969f-fe7f-424e-9062-5580e0981800/S60_Platform_Avkon_UI_Resources_v1_0_en.ziphttp://www.forum.nokia.com/main/1%2C%2C90%2C00.html?surveyId=2563969f-fe7f-424e-9062-5580e0981800/S60_Platform_Avkon_UI_Resources_v1_0_en.zip

s60 platform avkon ui resources grids v1 1 en

Documents