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

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

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

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

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

     6 <!-- Initial Contributors:

     7     Nokia Corporation - initial contribution.

     8 Contributors: 

     9 -->

    10 <!DOCTYPE concept

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

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

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

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

    15 worth noticing:</p>

    16 <ul>

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

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

    19 lists. <p/></li>

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

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

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

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

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

    25 </ul>

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

    27 list types:</p>

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

    29 <tgroup cols="2"><colspec colname="col1"/><colspec colname="col2"/>

    30 <thead>

    31 <row>

    32 <entry>Grid</entry>

    33 <entry>Description</entry>

    34 </row>

    35 </thead>

    36 <tbody>

    37 <row>

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

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

    40 </row>

    41 <row>

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

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

    44 </row>

    45 <row>

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

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

    48 </row>

    49 </tbody>

    50 </tgroup>

    51 </table>

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

    53 list or a form.</p>

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

    55 events in grids.</title>

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

    57 <thead>

    58 <row>

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

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

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

    62 </row>

    63 </thead>

    64 <tbody>

    65 <row>

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

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

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

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

    70 </row>

    71 <row>

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

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

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

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

    76 </row>

    77 <row>

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

    79 down.</p></entry>

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

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

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

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

    84 </row>

    85 <row>

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

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

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

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

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

    91 </row>

    92 <row>

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

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

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

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

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

    98 </row>

    99 <row>

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

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

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

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

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

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

   106 </row>

   107 </tbody>

   108 </tgroup>

   109 </table>

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

   111 grids in C++ 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="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknGrid.html" format="application/java-archive"><codeph>CAknGrid</codeph></xref> class is used to set up the basic parameters of

   112 a layout in terms of number of columns and rows, cell size, and orientation.

   113 After this, <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classAknListBoxLayouts.html" format="application/java-archive"><codeph>AknListBoxLayouts</codeph></xref> is

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

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

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

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

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

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

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

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

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

   123 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

   124 the class <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknCaleMonthStyleGrid.html" format="application/java-archive"><codeph>CAknCaleMonthStyleGrid</codeph></xref> to show a month view. The first row shows the day and the first column shows

   125 the week number. The following data can be set for an item:</p><ul>

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

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

   128 pixels</p></li>

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

   130 </ul><p>Use the class <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknPinbStyleGrid.html" format="application/java-archive"><codeph>CAknPinbStyleGrid</codeph></xref> to show application shortcuts in a 5 x 5 cells grid. For every item, an

   131 icon is specified that is displayed in the center of a cell. In addition,

   132 two small icons, 13 x 13 pixels, can be specified. The first one is displayed

   133 in the top-right corner for marking. The second one is displayed in the bottom-left

   134 corner to show the target application. </p></section>

   135 </conbody></concept>