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