|
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-971C9B81-1D6F-59E7-9416-385A0787D642" xml:lang="en"><title>The |
|
13 control stack</title><prolog><metadata><keywords/></metadata></prolog><conbody> |
|
14 <p>The control stack is a mechanism provided by the control framework for |
|
15 handling key press events. The Window Server, which generates events for control |
|
16 framework applications, channels all key press events to the application that |
|
17 currently has keyboard focus (Strictly speaking it channels key press events |
|
18 to the <keyword>window group</keyword> ). It is up to the application itself |
|
19 to channel the event to the correct destination as the Window Server does |
|
20 not associate a key press event with a particular control. </p> |
|
21 <p>In control framework applications using the <keyword>standard app |
|
22 UI</keyword> the control stack contains a list of controls that wish to |
|
23 receive keyboard events. Controls are added to the stack using <codeph>CCoeAppUi::AddToStackL()</codeph> and |
|
24 their ordering on the stack determines their priority in receiving key events: |
|
25 The one with the lowest position on the stack receiving key events first. |
|
26 When a key press event occurs, it is offered to each control on the stack |
|
27 in turn until it is consumed (i.e. used by that control). </p> |
|
28 <p>The ordering of controls on the stack is determined by their priority, |
|
29 a value passed to <codeph>CCoeAppUi::AddToStackL()</codeph>. If several controls |
|
30 on the stack have the same priority, their ordering is determined by the order |
|
31 in which they were added to the stack. </p> |
|
32 <codeblock id="GUID-02BC135C-66C4-5FBD-9085-2F6946A24660" xml:space="preserve">enum |
|
33 { |
|
34 ECoeStackPriorityDefault=0, // Low Priority |
|
35 ECoeStackPriorityMenu=10, |
|
36 ECoeStackPriorityDialog=50, |
|
37 ECoeStackPriorityCba=60, |
|
38 ECoeStackPriorityAlert=200, |
|
39 ECoeStackPriorityFep=250, |
|
40 ECoeStackPriorityEnvironmentFilter=300 // High Priority |
|
41 }; |
|
42 </codeblock> |
|
43 <p>The diagram below shows a hypothetical stack containing 4 controls added |
|
44 in the following order: control A (priority <codeph>ECoeStackPriorityDialog</codeph>), |
|
45 control B (<codeph>ECoeStackPriorityMenu</codeph>), control C (<codeph>ECoeStackPriorityDefault</codeph> — |
|
46 used for application views) and control D (<codeph>ECoeStackPriorityDialog</codeph>). </p> |
|
47 <fig id="GUID-02308139-5BC5-5098-BE15-178434158843"> |
|
48 <title> Example showing the order and priority of controls on the |
|
49 control stack </title> |
|
50 <image href="GUID-7AC4C1C2-D796-508F-93CF-21F061F49A30_d0e47241_href.png" placement="inline"/> |
|
51 </fig> |
|
52 <p>On the stack shown in the diagram key-press events will be offered first |
|
53 to control D, followed by A, B and C in that order. A control on the stack |
|
54 can refuse key press events by setting a flag. This might be done by a dialogs |
|
55 when it is not visible. </p> |
|
56 <p>Applications use the control stack to channel key press events to destinations |
|
57 in decreasing order of priority, such as: </p> |
|
58 <ul> |
|
59 <li id="GUID-EA1211C7-F2F1-5469-8EEB-66D44BC7542D"><p>debug keys </p> </li> |
|
60 <li id="GUID-D4063EC0-102F-563D-9D56-84760F447F7A"><p>any active dialog </p> </li> |
|
61 <li id="GUID-1ABFD001-B3A4-55C1-9D6A-F268457B8619"><p>any menu bar (i.e., |
|
62 its <keyword>hot-keys</keyword>) </p> </li> |
|
63 <li id="GUID-DAD2BC72-CC2A-501A-BD40-E2234D4AE1F2"><p>the application view </p> </li> |
|
64 </ul> |
|
65 </conbody></concept> |