Symbian3/PDK/Source/GUID-A5756C5F-9C93-4949-8B60-03DCA1BAF683.dita
changeset 1 25a17d01db0c
child 5 f345bda72bc4
--- /dev/null	Thu Jan 01 00:00:00 1970 +0000
+++ b/Symbian3/PDK/Source/GUID-A5756C5F-9C93-4949-8B60-03DCA1BAF683.dita	Fri Jan 22 18:26:19 2010 +0000
@@ -0,0 +1,162 @@
+<?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></keywords></metadata></prolog><conbody>
+<p>Empty items (that contain no data) can be hidden in a form's View state.
+However, this is not a requirement; forms can be designed either way, whichever
+is better for the given application.</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 Options 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).</p>
+<p>The following item types can be used in a form:</p>
+<ul>
+<li><p>Text field (alphanumeric or numeric content) </p></li>
+<li><p>Pop-up field </p></li>
+<li><p>Slider</p></li>
+</ul>
+<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>
+<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"></colspec><colspec colname="col2"></colspec>
+<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>
+<p>The field types 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"></colspec><colspec colname="col2"></colspec>
+<thead>
+<row>
+<entry>Field</entry>
+<entry>Description</entry>
+</row>
+</thead>
+<tbody>
+<row>
+<entry><p>Text field</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, 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_d0e81272_href.png" scale="40" placement="inline"></image>
+</fig>
+<section><title>Using forms in C++ applications</title><p>The
+API to use for creating forms is the Form
+API. For implementation information, see Using
+the Form API.</p></section>
+</conbody></concept>
\ No newline at end of file