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-A5756C5F-9C93-4949-8B60-03DCA1BAF683" xml:lang="en"><title>Form

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

    14 <p>Empty items (that contain no data) can be hidden in a form's View state.

    15 However, this is not a requirement; forms can be designed either way, whichever

    16 is better for the given application.</p>

    17 <p>Unlike ordinary list items, the form items may have different sizes in

    18 the layout but only in the Edit state. A long data field may occupy more than

    19 one line in the Edit state, but in the View state it is truncated to the first

    20 line.</p>

    21 <p>The user may be able to add and remove form items. This is done with commands

    22 in the Options menu.</p>

    23 <p>Form items always have a label. The label has a text part, or a text and

    24 a graphical part; however, all items in one form must have the same column

    25 layout (see <xref href="GUID-CB548959-A1D6-4585-B8E3-B09E37E0CB43.dita">List layouts</xref> for

    26 detailed information about layouts). Field label cannot be directly edited

    27 even if the form is in Edit state. However, it is possible to let the user

    28 edit the label text when the form is in edit state. User can choose to edit

    29 the label with an option, which can be found in the <b>Options</b> menu.</p>

    30 <p>The form field types that can be used are described in the following table:</p>

    31 <table id="GUID-A22394D3-9C39-4DC2-8A65-255F985F97E9"><title> Form field types</title>

    32 <tgroup cols="2"><colspec colname="col1" colwidth="0.30*"/><colspec colname="col2" colwidth="1.70*"/>

    33 <thead>

    34 <row>

    35 <entry>Field</entry>

    36 <entry>Description</entry>

    37 </row>

    38 </thead>

    39 <tbody>

    40 <row>

    41 <entry><p>Text field (alphanumeric or numeric content)</p></entry>

    42 <entry><p>A text field contains some type of numeric or alphanumeric data.

    43 It can be edited directly using the usual editing functions when the form

    44 is in the Edit state. The text field can expand to more than one lines if

    45 necessary.</p><p>In the View state, a text field looks identical to a corresponding

    46 list item.</p></entry>

    47 </row>

    48 <row>

    49 <entry><p>Pop-up field</p></entry>

    50 <entry><p>A pop-up field offers the possibility to choose one value from a

    51 pre-defined list. In the View state, a pop-up field looks identical to a list

    52 item; the text is the current value of the field. In the Edit state, it has

    53 a distinct look that identifies the field as a pop-up list.</p><p>To edit

    54 an item in the Edit state, the user can press the Selection key or with single

    55 click (in tap enabled devices), which opens a menu list that contains the

    56 available values. The highlight is on the current value. When the list is

    57 open, the softkeys are <b>OK</b> and <b>Cancel</b>, as usual with a menu list.

    58 Both the softkeys return to the Edit state in the form.</p><p>A pop-up field

    59 may also allow the user to enter a textual value in addition to the pre-defined

    60 values. In this case, the last option is named for example <b>Other</b>, and

    61 selecting it opens a Data query.</p><p>See figure below.</p></entry>

    62 </row>

    63 <row>

    64 <entry><p>Slider</p></entry>

    65 <entry><p>With a slider, the user can adjust a numeric value (although it

    66 is not necessary to present the actual value to the user as a number). In

    67 the View state, the item is presented as a textual item. In the Edit state,

    68 the value of the slider is immediately adjustable using the Arrow left and

    69 Arrow right keys.</p></entry>

    70 </row>

    71 </tbody>

    72 </tgroup>

    73 </table>

    74 <fig id="GUID-AA0170E3-BBB2-478A-A9A1-24C48BCF917F">

    75 <title>Pop-up field</title>

    76 <image href="GUID-DC4E42CA-2A65-44D7-8DBE-386F60F998A0_d0e64122_href.png" scale="40" placement="inline"/>

    77 </fig>

    78 <p>Any combination of these types is possible within one form.</p>

    79 <p>When a form is in the Edit state, the user can move the focus up and down

    80 like in a list. The highlight in the Edit state is different from the highlight

    81 in the View state, acting as a visual cue. The cursor blinks in the text field

    82 that is in focus. There is no need to save each field separately; the user

    83 can browse and modify the fields in any order and then accept all modifications.

    84 During the browsing of a form in the Edit state, the keypad functions are

    85 as follows:</p>

    86 <p>The field types are described in the following table:</p>

    87 <table id="GUID-437191CE-D3E0-4CFB-875C-9C308B18F7E9"><title>Default key events

    88 in editing state of a form</title>

    89 <tgroup cols="2"><colspec colname="col1" colwidth="0.30*"/><colspec colname="col2" colwidth="1.70*"/>

    90 <thead>

    91 <row>

    92 <entry>Key</entry>

    93 <entry>Action</entry>

    94 </row>

    95 </thead>

    96 <tbody>

    97 <row>

    98 <entry><p>Arrow up / down</p></entry>

    99 <entry><p>Move the focus between form items (when in a text field, move the

   100 cursor within an item line by line).</p></entry>

   101 </row>

   102 <row>

   103 <entry><p>Arrow left / right</p></entry>

   104 <entry><ul>

   105 <li><p>In a pop-up field: change the value without opening the list. </p></li>

   106 <li><p>In a text field: move the cursor character by character. </p></li>

   107 <li><p>In a slider: adjust the slider value.</p></li>

   108 </ul></entry>

   109 </row>

   110 <row>

   111 <entry><p>Selection key</p></entry>

   112 <entry><ul>

   113 <li><p>In a pop-up field: opens the list. </p></li>

   114 <li><p>In a text field: opens the context sensitive <b>Options</b> menu or

   115 no action.</p></li>

   116 </ul></entry>

   117 </row>

   118 <row>

   119 <entry><p>Left softkey (Options)</p></entry>

   120 <entry><p>Opens the <b>Options</b> menu (in a form without the <b>Options</b> menu,

   121 the left softkey is <b>Done</b>).</p></entry>

   122 </row>

   123 <row>

   124 <entry><p>Right softkey (Done)</p></entry>

   125 <entry><p>Accepts the contents and returns to the previous state (in a form

   126 without the Options menu, the right softkey is Cancel.)</p></entry>

   127 </row>

   128 <row>

   129 <entry><p>Clear</p></entry>

   130 <entry><ul>

   131 <li><p>Pop-up: ignored. </p></li>

   132 <li><p>Text: deletes characters. </p></li>

   133 <li><p>Slider: ignored.</p></li>

   134 </ul></entry>

   135 </row>

   136 <row>

   137 <entry><p>Edit</p></entry>

   138 <entry><ul>

   139 <li><p>Pop-up: ignored. </p></li>

   140 <li><p>Text: opens the editing menu; selects text. </p></li>

   141 <li><p>Slider: ignored.</p></li>

   142 </ul></entry>

   143 </row>

   144 <row>

   145 <entry><p>Numeric keypad</p></entry>

   146 <entry><ul>

   147 <li><p>Pop-up: ignored. </p></li>

   148 <li><p>Text: input. </p></li>

   149 <li><p>Slider: ignored.</p></li>

   150 </ul></entry>

   151 </row>

   152 <row>

   153 <entry><p>Other keys</p></entry>

   154 <entry><p>The default action of the key.</p></entry>

   155 </row>

   156 </tbody>

   157 </tgroup>

   158 </table>

   159 <section id="GUID-E6A426E6-FC7E-4620-9CAE-BA9214AC17F8"><title>Using

   160 forms in C++ applications</title><p>The API to use for creating forms is the <xref format="html" href="specs/guides/Form_API_Specification/Form_API_Specification.html" scope="peer">Form API</xref>. For implementation information,

   161 see <xref format="html" href="specs/guides/Form_API_Specification/Form_API_Specification.html#Form_API_Specification.topic3" scope="peer">Using the Form API</xref>.</p></section>

   162 </conbody></concept>