<?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-A5756C5F-9C93-4949-8B60-03DCA1BAF683" xml:lang="en"><title>Form items</title><prolog><metadata><keywords/></metadata></prolog><conbody>

<p>Form items can either be displayed or hidden (for empty items that

contain no data) in a form's View state. </p>

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

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

more than one line in the Edit state, but in the View state it is

truncated to the first line.</p>

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

with commands in the <uicontrol>Options</uicontrol> menu.</p>

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

text and a graphical part; however, all items in one form must have

the same column layout (see <xref href="GUID-CB548959-A1D6-4585-B8E3-B09E37E0CB43.dita">List layouts</xref> for detailed information about layouts). Field label cannot be directly

edited even if the form is in Edit state. However, it is possible

to let the user edit the label text when the form is in edit state.

User can choose to edit the label with an option, which can be found

in the <b>Options</b> menu.</p>

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

table:</p>

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

field types</title>

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

<thead>

<row>

<entry>Field</entry>

<entry>Description</entry>

</row>

</thead>

<tbody>

<row>

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

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

data. It can be edited directly using the usual editing functions

when the form is in the Edit state. The text field can expand to more

than one lines if necessary.</p><p>In the View state, a text field

looks identical to a corresponding list item.</p></entry>

</row>

<row>

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

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

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

to a list item; the text is the current value of the field. In the

Edit state, it has a distinct look that identifies the field as a

pop-up list.</p><p>To edit an item in the Edit state, the user can

press the Selection key or with single tap (in devices supporting

touch), which opens a menu list that contains the available values.

The highlight is on the current value. When the list is open, the

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

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

field may also allow the user to enter a textual value in addition

to the pre-defined values. In this case, the last option is named

for example <b>Other</b>, and selecting it opens a Data query.</p><p>See figure below.</p></entry>

</row>

<row>

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

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

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

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

Edit state, the value of the slider is immediately adjustable using

the Arrow left and Arrow right keys.</p></entry>

</row>

</tbody>

</tgroup>

</table>

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

<title>Pop-up field</title>

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

</image>

</fig>

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

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

and down like in a list. The highlight in the Edit state is different

from the highlight in the View state, acting as a visual cue. The

cursor blinks in the text field that is in focus. There is no need

to save each field separately; the user can browse and modify the

fields in any order and then accept all modifications. During the

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

follows:</p>

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

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

key events in editing state of a form</title>

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

<thead>

<row>

<entry>Key</entry>

<entry>Action</entry>

</row>

</thead>

<tbody>

<row>

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

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

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

</row>

<row>

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

<entry><ul>

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

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

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

</ul></entry>

</row>

<row>

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

<entry><ul>

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

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

</ul></entry>

</row>

<row>

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

<entry><p>Opens the <b>Options</b> menu (in a form without the <b>Options</b> menu, the left softkey is <b>Done</b>).</p></entry>

</row>

<row>

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

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

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

</row>

<row>

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

<entry><ul>

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

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

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

</ul></entry>

</row>

<row>

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

<entry><ul>

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

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

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

</ul></entry>

</row>

<row>

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

<entry><ul>

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

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

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

</ul></entry>

</row>

<row>

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

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

</row>

</tbody>

</tgroup>

</table>

<section id="GUID-E6A426E6-FC7E-4620-9CAE-BA9214AC17F8"><title>Using forms in 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, 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>