<?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>
</conbody></concept>