|
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-1AA32C40-CDE0-4627-A634-7C07BB1ED67B" xml:lang="en"><title>Forms</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
13 <p>A form is a specific kind of selection list, where all items (fields) have |
|
14 some editable content. </p> |
|
15 <p>A form can be in the View state or in the Edit state. The item layouts |
|
16 and functionality are different in these states:</p> |
|
17 <ul> |
|
18 <li><p>In the View state, the items are not editable. The form functions and |
|
19 looks exactly like a similar selection list. Items can be selected to perform |
|
20 an application-specific function. </p></li> |
|
21 <li><p>In the Edit state, the user can edit all the fields. Forms can contain |
|
22 text fields (alphanumeric or numeric content), pop-up fields and sliders.</p></li> |
|
23 </ul> |
|
24 <p>Forms work with single click. The view state of the form follows list behavior. |
|
25 Edit state works with single click but it has the highlight always visible |
|
26 to indicate the active form item. Note that the entire form component item |
|
27 should be touch sensitive in normal state. This means that even if the user |
|
28 does not touch the edit field but instead the field header, the item is still |
|
29 activated.</p> |
|
30 <p>The user can switch from the View state to the Edit state using the Edit |
|
31 command in the Options menu. In the Edit state, the contents of the form can |
|
32 be accepted using the right softkey labeled as Done. The form then returns |
|
33 to the View state.</p> |
|
34 <fig id="GUID-A2BD480A-8FF8-46D2-8C2D-1C300761BBEF"> |
|
35 <title>An example form</title> |
|
36 <image href="GUID-783161AE-708E-4FB4-8219-EEC0F9939E9B_d0e63641_href.png" placement="inline"/> |
|
37 </fig> |
|
38 <p>The following table lists the default touch events for forms:</p> |
|
39 <table id="GUID-9342F902-5F33-4A51-BCCB-258C4AADAC8C"><title>Default touch |
|
40 events for forms</title> |
|
41 <tgroup cols="3"> |
|
42 |
|
43 <colspec colname="col1" colwidth="0.80*"/><colspec colname="col2" colwidth="1.03*"/> |
|
44 <colspec colname="col3" colwidth="1.17*"/> |
|
45 <thead> |
|
46 <row> |
|
47 <entry valign="top"><p>User action</p></entry> |
|
48 <entry valign="top"><p>State change</p></entry> |
|
49 <entry valign="top"><p>Feedback</p></entry> |
|
50 </row> |
|
51 </thead> |
|
52 <tbody> |
|
53 <row> |
|
54 |
|
55 <entry nameend="col3" namest="col1"><p><b>In Edit State</b></p></entry> |
|
56 </row> |
|
57 <row> |
|
58 <entry><p>Touch down on item</p></entry> |
|
59 <entry><p>No change</p></entry> |
|
60 <entry><p>Highlight is shown on the item and focus shifts to the item.</p><p>Tactile: |
|
61 Basic list effect and audio feedback is provided with touch down event.</p><note> Only |
|
62 form-specific feedback is provided. No sensitive edit feedback provided on |
|
63 editor item in the form.</note></entry> |
|
64 </row> |
|
65 <row> |
|
66 <entry><p>Touch release on item</p></entry> |
|
67 <entry><p>Item is activated.</p><p>When the user moves a cursor to a text |
|
68 field, the cursor is placed at the end of the text in the field. If the field |
|
69 is empty, the cursor is placed at the beginning of the field.</p><p>Touch |
|
70 release on a radio button list item selects the item and closes the pop-up.</p></entry> |
|
71 <entry><p>Highlight remains on the item.</p><p>In case of a radio button list, |
|
72 highlight stays on the full list, and not on any single selection item.</p><p>Tactile: |
|
73 Basic list effect provided with release event.</p></entry> |
|
74 </row> |
|
75 <row> |
|
76 <entry><p>Touch down and hold on item</p></entry> |
|
77 <entry><p>Inactive</p></entry> |
|
78 <entry><p>Tactile: No effect</p></entry> |
|
79 </row> |
|
80 <row> |
|
81 <entry><p>Touch down and move inside form</p></entry> |
|
82 <entry><p>Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging |
|
83 and flicking</xref> events</p></entry> |
|
84 <entry><p>Highlight remains on the item that is currently active, when the |
|
85 user starts to move.</p><p>Tactile: Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging |
|
86 and flicking</xref> events.</p></entry> |
|
87 </row> |
|
88 <row> |
|
89 <entry><p>Touch down and move outside the form without releasing touch.</p></entry> |
|
90 <entry><p>Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging |
|
91 and flicking</xref> events</p></entry> |
|
92 <entry><p>Tactile: Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging |
|
93 and flicking</xref> events.</p></entry> |
|
94 </row> |
|
95 <row> |
|
96 <entry><p>Touch down and release outside the radio button list</p></entry> |
|
97 <entry><p>Radio button list is closed.</p></entry> |
|
98 <entry><p>Tactile: Pop-up effect is provided with touch down event.</p></entry> |
|
99 </row> |
|
100 <row> |
|
101 <entry nameend="col3" namest="col1"/> |
|
102 </row> |
|
103 <row> |
|
104 <entry nameend="col3" namest="col1"><p><b>In View State</b></p></entry> |
|
105 </row> |
|
106 <row> |
|
107 <entry><p>Touch down on item</p></entry> |
|
108 <entry><p>No effect</p></entry> |
|
109 <entry><p>Highlight is shown.</p><p>Tactile: Basic list effect and audio feedback |
|
110 is provided with the touch down event.</p></entry> |
|
111 </row> |
|
112 <row> |
|
113 <entry><p>Touch release</p></entry> |
|
114 <entry><p>One of the following occurs:<ul> |
|
115 <li><p>Item is activated.</p></li> |
|
116 <li><p>Item get editable.</p></li> |
|
117 <li><p>Item opens context specific <b>Options</b> menu.</p></li> |
|
118 </ul></p></entry> |
|
119 <entry><p>Highlight disappears.</p><p>Tactile: Basic list effect is provided |
|
120 with touch release event.</p><p>If the touch release opens a pop-up, the pop-up |
|
121 open effect is provided with the touch release. If theme effects are ON, then |
|
122 increasing long touch effect with touch release is provided.</p></entry> |
|
123 </row> |
|
124 <row> |
|
125 <entry><p>Touch down and hold</p></entry> |
|
126 <entry><p>Inactive</p></entry> |
|
127 <entry><p>Tactile: No effect</p></entry> |
|
128 </row> |
|
129 <row> |
|
130 <entry><p>Touch down and move inside form</p></entry> |
|
131 <entry><p>Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging |
|
132 and flicking</xref> events</p></entry> |
|
133 <entry><p>Tactile: Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging |
|
134 and flicking</xref> events.</p></entry> |
|
135 </row> |
|
136 <row> |
|
137 <entry><p>Touch down and move outside the form without releasing touch.</p></entry> |
|
138 <entry><p>Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging |
|
139 and flicking</xref> events</p></entry> |
|
140 <entry><p>Tactile: Refer to <xref href="GUID-7C61D3D7-8FCB-46AB-B2E9-CE1AC68F86DE.dita">Dragging |
|
141 and flicking</xref> events.</p></entry> |
|
142 </row> |
|
143 </tbody> |
|
144 </tgroup> |
|
145 </table> |
|
146 <section id="GUID-CB9AC4F2-4C2B-49AA-9FCE-E9EA7209CC50"><title>Using |
|
147 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, 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 |
|
148 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 |
|
149 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 |
|
150 switch from edit mode to view mode and are prompted by the form as to whether |
|
151 they wish to save their modifications.</p><p>For customization, the class <codeph>CAknForm</codeph> provides |
|
152 a single-line or double-line layout and it is possible to use icons on forms. </p><p>In |
|
153 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 |
|
154 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; |
|
155 CleanupStack::PushL(form); |
|
156 form->ConstructL(); |
|
157 CleanupStack::Pop(); |
|
158 form->ExecuteLD(R_AKNEXFORM_TEXT_FIELD_DIALOG); |
|
159 </codeblock></section> |
|
160 </conbody><related-links> |
|
161 <linklist><title>Related APIs</title> |
|
162 <link format="html" href="specs/guides/Dialogs_API_Specification/Dialogs_API_Specification.html" scope="peer"><linktext>Dialogs API</linktext></link> |
|
163 </linklist> |
|
164 </related-links></concept> |