<?xml version="1.0" encoding="utf-8"?>

<!-- Copyright (c) 2007-2010 Nokia Corporation and/or its subsidiary(-ies) All rights reserved. -->

<!-- This component and the accompanying materials are made available under the terms of the License 

"Eclipse Public License v1.0" which accompanies this distribution, 

and is available at the URL "http://www.eclipse.org/legal/epl-v10.html". -->

<!-- Initial Contributors:

    Nokia Corporation - initial contribution.

Contributors: 

-->

<!DOCTYPE concept

  PUBLIC "-//OASIS//DTD DITA Concept//EN" "concept.dtd">

<concept id="GUID-1955F591-2D2C-42EE-AF03-7BBBEE1A4005" xml:lang="en"><title>Grid

types</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Grids are in many ways analogous to lists. However, there are some things

worth noticing:</p>

<ul>

<li>In grids, the Arrow left and Arrow right keys are always used for moving

the focus; they cannot be used in any other way that may be possible with

lists. <p/></li>

<li><p>Grid layouts are not as standardized as lists; the layouts must be

designed case by case for the applications. Typically, grid items occupy less

screen space than list items. This results in grid items having fewer elements

than list items. A grid item may in general have one text, or one graphic,

or a text and a graphic.</p></li>

</ul>

<p>The following grid types can be used, and they are analogous to the corresponding

list types:</p>

<table id="GUID-77A41D48-C4F8-4E2D-8BCC-11C8A233EC89"><title>Grid types</title>

<tgroup cols="2">

<colspec colname="col1" colwidth="0.60*"/><colspec colname="col2" colwidth="1.40*"/>

<thead>

<row>

<entry>Grid</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

<entry><p>Menu grid</p></entry>

<entry><p>For selecting one item; no Options menu.</p></entry>

</row>

<row>

<entry><p>Selection grid</p></entry>

<entry><p>Permanent state; can be left pending, the Options menu is available.</p></entry>

</row>

<row>

<entry><p>Markable grid</p></entry>

<entry><p>A selection grid with the marking function.</p></entry>

</row>

</tbody>

</tgroup>

</table>

<p>There are no grid types corresponding to a multi-selection list, a setting

list or a form.</p>

<table id="GUID-00226785-93CC-4514-9327-15EC9C272E18"><title>Default touch

events in grids.</title>

<tgroup cols="3"><colspec colname="col1" colwidth="0.80*"/><colspec colname="col2" colwidth="1.01*"/><colspec colname="col3" colwidth="1.19*"/>

<thead>

<row>

<entry valign="top"><p>User action</p></entry>

<entry valign="top"><p>State change</p></entry>

<entry valign="top"><p>Feedback</p></entry>

</row>

</thead>

<tbody>

<row>

<entry><p>Touch down</p></entry>

<entry><p>No effect</p></entry>

<entry><p>Highlight is shown.</p><p>Tactile: Basic list effect and audio feedback

is provided with touch down event.</p></entry>

</row>

<row>

<entry><p>Touch release</p></entry>

<entry><p>Item is activated</p></entry>

<entry><p>Highlight disappears. </p><p>Tactile: Basic list effect  is provided

with touch release event.</p></entry>

</row>

<row>

<entry><p>Touch down and move outside the grid without releasing the touch

down.</p></entry>

<entry><p>Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging

and flicking</xref> events</p></entry>

<entry><p>Tactile: Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging

and flicking</xref> events.</p></entry>

</row>

<row>

<entry><p>Touch down, move outside and back.</p></entry>

<entry><p>Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging

and flicking</xref> events</p></entry>

<entry><p>Tactile: Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging

and flicking</xref> events.</p></entry>

</row>

<row>

<entry><p>Touch down and move vertically</p></entry>

<entry><p>Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging

and flicking</xref> events</p></entry>

<entry><p>Tactile: Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging

and flicking</xref> events.</p></entry>

</row>

<row>

<entry><p>Touch down and move horizontally</p></entry>

<entry><p>Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging

and flicking</xref> events</p></entry>

<entry>Highlight stays on the item while it is touched and disappears when

moving outside of it.<p>Tactile: Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging

and flicking</xref> events.</p></entry>

</row>

</tbody>

</tgroup>

</table>

<section id="GUID-D51BDE18-D03E-42DC-BC41-551BB0DBBAD7"><title>Using

grids in applications</title><p>The APIs to use for grids are

the <xref format="html" href="specs/guides/Grids_API_Specification/Grids_API_Specification.html" scope="peer">Grids API</xref> and the <xref format="html" href="specs/guides/Lists_API_Specification/Lists_API_Specification.html" scope="peer">Lists API</xref>. For implementation information, see <xref format="html" href="specs/guides/Grids_API_Specification/Grids_API_Specification.html#Grids_API_Specification.topic3" scope="peer">Using the Grids API</xref> and <xref format="html" href="specs/guides/Lists_API_Specification/Lists_API_Specification.html#Lists_API_Specification.topic3" scope="peer">Using the Lists API</xref>.</p><p>The <xref href="GUID-B49E127B-09B1-3A82-B704-56373B4E1F1D.dita"><apiname>CAknGrid</apiname></xref> class

is used to set up the basic parameters of a layout in terms of number of columns

and rows, cell size, and orientation. After this, <xref href="GUID-75F5E010-D30A-37B6-B4B3-A25C1DAEAD52.dita"><apiname>AknListBoxLayouts</apiname></xref> is

used to set up detailed parameters for graphics and text in the cell. The

following cell parameters can be set:</p><ul>

<li><p>Location and size of bitmaps</p></li>

<li><p>Location and size of text string</p></li>

<li><p>Font and its color </p></li>

<li><p>Text align in the allocated space</p></li>

</ul><p>Bitmaps are loaded manually, as an icon array.</p><p>Other parameters

of visual elements (for example, highlighted text color) are used from the

Symbian Developer Platform standard look and feel module; these should not

be overridden unless you've instantiated your own class. </p><p>Several <xref format="html" href="specs/guides/Grids_API_Specification/Grids_API_Specification.html" scope="peer">specialized grid classes</xref> can be found in AVKON.</p><p>Use

the class <xref href="GUID-4A864745-EA9C-3ED6-B3B7-1DF92817A96A.dita"><apiname>CAknCaleMonthStyleGrid</apiname></xref> to show a month view.

The first row shows the day and the first column shows the week number. The

following data can be set for an item:</p><ul>

<li><p>Outlined icon to show border, dimension 21 x 9 pixels</p></li>

<li><p>Marking icon in the bottom right corner of a cell, dimension 5 x 5

pixels</p></li>

<li><p>Two-digit number</p></li>

</ul><p>Use the class <xref href="GUID-D2166870-2ED0-3516-BE88-92FE7E9ED7BA.dita"><apiname>CAknPinbStyleGrid</apiname></xref> to show application

shortcuts in a 5 x 5 cells grid. For every item, an icon is specified that

is displayed in the center of a cell. In addition, two small icons, 13 x 13

pixels, can be specified. The first one is displayed in the top-right corner

for marking. The second one is displayed in the bottom-left corner to show

the target application. </p></section>

</conbody></concept>