<?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-1AA32C40-CDE0-4627-A634-7C07BB1ED67B" xml:lang="en"><title>Forms</title><prolog><metadata><keywords/></metadata></prolog><conbody>
<p>A form is a specific kind of selection list, where all items (fields)
have some editable content. </p>
<p>A form can be in the View state or in the Edit state. The item
layouts and functionality are different in these states:</p>
<ul>
<li><p>In the View state, the items are not editable. The form functions
and looks exactly like a similar selection list. Items can be selected
to perform an application-specific function. </p></li>
<li><p>In the Edit state, the user can edit all the fields. Forms
can contain text fields (alphanumeric or numeric content), pop-up
fields and sliders.</p></li>
</ul>
<p>Forms work with single tap. The view state of the form follows
list behavior. Edit state works with single tap but it has the highlight
always visible to indicate the active form item. Note that the entire
form component item should be touch sensitive in normal state. This
means that even if the user does not touch the edit field but instead
the field header, the item is still activated.</p>
<p>The user can switch from the View state to the Edit state using
the Edit command in the Options menu. In the Edit state, the contents
of the form can be accepted using the right softkey labeled as Done.
The form then returns to the View state.</p>
<fig id="GUID-A2BD480A-8FF8-46D2-8C2D-1C300761BBEF">
<title>An example form</title>
<image href="GUID-783161AE-708E-4FB4-8219-EEC0F9939E9B_d0e55932_href.png" placement="inline"/>
</fig>
<p>The following table lists the default touch events for forms:</p>
<table id="GUID-9342F902-5F33-4A51-BCCB-258C4AADAC8C"><title>Default
touch events for forms</title>
<tgroup cols="3"><colspec colname="col1" colwidth="0.80*"/><colspec colname="col2" colwidth="1.03*"/><colspec colname="col3" colwidth="1.17*"/>
<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 nameend="col3" namest="col1"><p><b>In Edit State</b></p></entry>
</row>
<row>
<entry><p>Touch down on item</p></entry>
<entry><p>No change</p></entry>
<entry><p>Highlight is shown on the item and focus shifts to the item.</p><p>Tactile: Basic list effect and audio feedback is provided with
touch down event.</p><note> Only form-specific feedback is provided.
No sensitive edit feedback provided on editor item in the form.</note></entry>
</row>
<row>
<entry><p>Touch release on item</p></entry>
<entry><p>Item is activated.</p><p>When the user moves a cursor to
a text field, the cursor is placed at the end of the text in the field.
If the field is empty, the cursor is placed at the beginning of the
field.</p><p>Touch release on a radio button list item selects the
item and closes the pop-up.</p></entry>
<entry><p>Highlight remains on the item.</p><p>In case of a radio
button list, highlight stays on the full list, and not on any single
selection item.</p><p>Tactile: Basic list effect provided with release
event.</p></entry>
</row>
<row>
<entry><p>Touch down and hold on item</p></entry>
<entry><p>Inactive</p></entry>
<entry><p>Tactile: No effect</p></entry>
</row>
<row>
<entry><p>Touch down and move inside form</p></entry>
<entry><p>Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging and flicking</xref> events</p></entry>
<entry><p>Highlight remains on the item that is currently active,
when the user starts to move.</p><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 outside the form without releasing touch.</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 release outside the radio button list</p></entry>
<entry><p>Radio button list is closed.</p></entry>
<entry><p>Tactile: Pop-up effect is provided with touch down event.</p></entry>
</row>
<row>
<entry nameend="col3" namest="col1"/>
</row>
<row>
<entry nameend="col3" namest="col1"><p><b>In View State</b></p></entry>
</row>
<row>
<entry><p>Touch down on item</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 the touch down event.</p></entry>
</row>
<row>
<entry><p>Touch release</p></entry>
<entry><p>One of the following occurs:<ul>
<li><p>Item is activated.</p></li>
<li><p>Item get editable.</p></li>
<li><p>Item opens context specific <b>Options</b> menu.</p></li>
</ul></p></entry>
<entry><p>Highlight disappears.</p><p>Tactile: Basic list effect is
provided with touch release event.</p><p>If the touch release opens
a pop-up, the pop-up open effect is provided with the touch release.
If theme effects are ON, then increasing long touch effect with touch
release is provided.</p></entry>
</row>
<row>
<entry><p>Touch down and hold</p></entry>
<entry><p>Inactive</p></entry>
<entry><p>Tactile: No effect</p></entry>
</row>
<row>
<entry><p>Touch down and move inside form</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 outside the form without releasing touch.</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>
</tbody>
</tgroup>
</table>
<section id="GUID-CB9AC4F2-4C2B-49AA-9FCE-E9EA7209CC50"><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><p>Typically, a form will
be derived from the class <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknForm.html" format="application/java-archive"><codeph>CAknForm</codeph></xref> and the methods <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknForm.html#b90bd30d42503d5f0464e9ff1ce3b830" format="application/java-archive"><codeph>SaveFormDataL()</codeph></xref> and <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknForm.html#6ff9f54d5d8a08da0c6f6574389b787a" format="application/java-archive"><codeph>DoNotSaveFormData()</codeph></xref> will be implemented by
the developer. These are called when users switch from edit mode to
view mode and are prompted by the form as to whether they wish to
save their modifications.</p><p>For customization, the class <codeph>CAknForm</codeph> provides a single-line or double-line layout and
it is possible to use icons on forms. </p><p>In the following example,
the form is pushed on the cleanup stack before <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknForm.html#a7108b30a367ecb940f57e0dd35973bd" format="application/java-archive"><codeph>ConstructL()</codeph></xref> (a potentially leaving method)
is called, and popped off before <xref href="jar:GUID-759FBC7F-5384-4487-8457-A8D4B76F6AA6.jar!/html/classCAknDialog.html#2bb826c038d23806445872d768e7d151" format="application/java-archive"><codeph>ExecuteLD()</codeph></xref>. </p><codeblock xml:space="preserve">CAknExFormAdd* form = new(ELeave) CAknExFormAdd;
CleanupStack::PushL(form);
form-&gt;ConstructL();
CleanupStack::Pop();
form-&gt;ExecuteLD(R_AKNEXFORM_TEXT_FIELD_DIALOG);
</codeblock></section>
</conbody><related-links>
<linklist><title>Related APIs</title>
<link format="html" href="specs/guides/Dialogs_API_Specification/Dialogs_API_Specification.html" scope="peer"><linktext>Dialogs API</linktext></link>
</linklist>
</related-links></concept>