The control stack

The control stack is a mechanism provided by the control framework for handling key press events. The Window Server, which generates events for control framework applications, channels all key press events to the application that currently has keyboard focus (Strictly speaking it channels key press events to the window group ). It is up to the application itself to channel the event to the correct destination as the Window Server does not associate a key press event with a particular control.

In control framework applications using the standard app UI the control stack contains a list of controls that wish to receive keyboard events. Controls are added to the stack using CCoeAppUi::AddToStackL() and their ordering on the stack determines their priority in receiving key events: The one with the lowest position on the stack receiving key events first. When a key press event occurs, it is offered to each control on the stack in turn until it is consumed (i.e. used by that control).

The ordering of controls on the stack is determined by their priority, a value passed to CCoeAppUi::AddToStackL(). If several controls on the stack have the same priority, their ordering is determined by the order in which they were added to the stack.

enum
    {
    ECoeStackPriorityDefault=0,  // Low Priority
    ECoeStackPriorityMenu=10,
    ECoeStackPriorityDialog=50,
    ECoeStackPriorityCba=60,
    ECoeStackPriorityAlert=200,
    ECoeStackPriorityFep=250,
    ECoeStackPriorityEnvironmentFilter=300  // High Priority
    };

The diagram below shows a hypothetical stack containing 4 controls added in the following order: control A (priority ECoeStackPriorityDialog), control B (ECoeStackPriorityMenu), control C (ECoeStackPriorityDefault — used for application views) and control D (ECoeStackPriorityDialog).

On the stack shown in the diagram key-press events will be offered first to control D, followed by A, B and C in that order. A control on the stack can refuse key press events by setting a flag: This might be done by a dialogs when it is not visible.

Applications use the control stack to channel key press events to destinations in decreasing order of priority, such as:

• debug keys

• any active dialog

• any menu bar (i.e., its hot-keys)

• the application view