|
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-7B275129-5EF7-4B27-B603-3BDE2C650A93" xml:lang="en"><title>Queries</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
13 <p>A query is a state where the software waits for user input. Queries are |
|
14 used in situations with more than one ways to proceed, when the application |
|
15 needs data from the user, or when it is necessary to make sure the user knows |
|
16 what is happening. A query must be exited before the application can proceed.</p> |
|
17 <p>Queries are displayed in pop-up windows. The following query types can |
|
18 be used:</p> |
|
19 <table id="GUID-90850312-4A91-46D7-AC86-DC6F1B7E4BA9"> |
|
20 <tgroup cols="2"><colspec colname="col1" colwidth="0.39*"/><colspec colname="col2" colwidth="1.61*"/> |
|
21 <thead> |
|
22 <row> |
|
23 <entry valign="top"><p>Query types</p></entry> |
|
24 <entry valign="top"><p>Description</p></entry> |
|
25 </row> |
|
26 </thead> |
|
27 <tbody> |
|
28 <row> |
|
29 <entry><p>Confirmation query</p></entry> |
|
30 <entry><p>A question or notice with one or two possible responses. </p></entry> |
|
31 </row> |
|
32 <row> |
|
33 <entry><p>List query</p></entry> |
|
34 <entry><p>A question with a selection of more than two possible (pre-defined) |
|
35 responses in a list. </p></entry> |
|
36 </row> |
|
37 <row> |
|
38 <entry><p>Grid query</p></entry> |
|
39 <entry><p>A question with a selection of more than two possible (pre-defined) |
|
40 responses in a grid.</p></entry> |
|
41 </row> |
|
42 <row> |
|
43 <entry><p>Multi-selection list query</p></entry> |
|
44 <entry><p>Presents a list of items; the user can select any number of them. </p></entry> |
|
45 </row> |
|
46 <row> |
|
47 <entry><p>Data query</p></entry> |
|
48 <entry><p>Used for numeric or textual input.</p></entry> |
|
49 </row> |
|
50 <row> |
|
51 <entry><p>Message query</p></entry> |
|
52 <entry><p>Used for various purposes in queries that are longer than one screen.</p></entry> |
|
53 </row> |
|
54 </tbody> |
|
55 </tgroup> |
|
56 </table> |
|
57 <section id="GUID-53619735-6F0F-401F-AE62-154EDF75A0C3"><title>Using |
|
58 queries in C++ applications</title><p>The APIs to use for queries are the |
|
59 Queries API, <xref format="html" href="specs/guides/Dialogs_API_Specification/Dialogs_API_Specification.html" scope="peer">Dialogs API</xref>, and the <xref format="html" href="specs/guides/Popups_API_Specification/Popups_API_Specification.html" scope="peer">Popups API</xref>. For implementation information, see <xref format="html" href="specs/guides/Dialogs_API_Specification/Dialogs_API_Specification.html#Dialogs_API_Specification.topic3" scope="peer">Using the Dialogs API</xref>.</p><p>Query dialogs are dialogs |
|
60 that can be used to require user input or user selection. All query dialogs |
|
61 derive from <xref href="GUID-DD9C643C-223D-3B70-AEBA-5BF5C5E181ED.dita"><apiname>CAknQueryDialog</apiname></xref>, which inherits <xref href="GUID-FBE5021B-FA5C-3306-B836-601E4BCB11E4.dita"><apiname>CAknDialog</apiname></xref>. |
|
62 There are two types of queries: local and global queries. Local query dialogs |
|
63 are local to a certain application. That means they are only displayed within |
|
64 this application. Global query dialogs are system-wide queries, and are shown |
|
65 topmost even when another application moves to the foreground. Query dialogs |
|
66 require resource definitions when they are used in your code. </p><note><p>To |
|
67 have a header pane, the <codeph>AVKON_HEADING</codeph> component should be |
|
68 specified as the first dialog line in the resource description.</p></note><p>At |
|
69 runtime, the dialog's header pane (<xref href="GUID-5FEC2E62-57DB-328C-8E13-4990F9308BF6.dita"><apiname>CAknPopupHeadingPane</apiname></xref>) |
|
70 can be obtained by calling the method <xref href="GUID-DD9C643C-223D-3B70-AEBA-5BF5C5E181ED.dita#GUID-DD9C643C-223D-3B70-AEBA-5BF5C5E181ED/GUID-B7AC6A1B-1C68-38AC-8B5F-D6199AA272D4"><apiname>CAknQueryDialog::QueryHeading()</apiname></xref>.</p><p>The |
|
71 following parts are available for modification from the class <codeph>CAknQueryDialog</codeph>:</p><ul> |
|
72 <li><p>Data query </p><ul> |
|
73 <li><p>Header text </p></li> |
|
74 <li><p>Header image/animation </p></li> |
|
75 <li><p>Prompt text </p></li> |
|
76 <li><p>Edit indicator (can be removed) </p></li> |
|
77 </ul></li> |
|
78 <li><p>Confirmation query </p><ul> |
|
79 <li><p>Prompt text </p></li> |
|
80 <li><p>Image/animation </p></li> |
|
81 </ul></li> |
|
82 <li><p>List query </p><ul> |
|
83 <li><p>Header text </p></li> |
|
84 <li><p>Header image/animation </p></li> |
|
85 <li><p>List type (Single, SingleHeading, SingleGraphic, SingleGraphicHeading) </p></li> |
|
86 </ul></li> |
|
87 </ul><p>The following example illustrates the resource definition for the |
|
88 Secret Editor Query, which contains a Secret Editor, resides inside the dialog. |
|
89 The values for flags, type, id, and control are specific to the query dialog. |
|
90 These values are enumerated in the file <codeph>avkon.hrh</codeph>, which |
|
91 is in the <codeph>./epoc32/include</codeph> folder.</p><codeblock xml:space="preserve">RESOURCE DIALOG r_aknexquery_code_query |
|
92 { |
|
93 flags = EGeneralQueryFlags |
|
94 buttons = R_AVKON_SOFTKEYS_OK_CANCEL; |
|
95 items = |
|
96 { |
|
97 DLG_LINE |
|
98 { |
|
99 type = EAknCtQuery; |
|
100 id = EGeneralQuery; |
|
101 control = EGeneralQueryFlags |
|
102 { |
|
103 layout = ECodeLayout; |
|
104 label = label_text; |
|
105 control = SECRETED |
|
106 { |
|
107 num_letters = 8; |
|
108 }; |
|
109 }; |
|
110 } |
|
111 }; |
|
112 } |
|
113 </codeblock><p>The query in the above example includes a secret editor. For |
|
114 information on implementing secret editors, see the <xref format="html" href="specs/guides/Editors_API_Specification/Editors_API_Specification.html" scope="peer">Editors API</xref>. </p><p><b>See also</b>:</p></section> |
|
115 </conbody></concept> |