Chapter 1

� A dialog, containing a title bar, a help icon, a captioned control array, a button
(Schedule), a page selector, and a button group.
� A captioned control array with five captioned controls, including a numeric editor with
up and down arrows.
� A page selector with three tabs and left and right scroll arrows.
� A button group with two buttons (Cancel and Done).
That's 21 controls altogether, all lodging in a single window.
For another example, see the Write file dialog in Chapter 11, which had two captioned
controls and two buttons, for a total of 12 controls.
It should be obvious that the dialog isn't the only container here. The captioned control array,
and some controls themselves, are also important containers with their own responsibilities,
as we'll see. What we think of as 'the controls' in the dialog (the five controls in the captioned
control array we were talking about above) are more complicated than they appear, and
account for only about a quarter of the controls actually on this dialog page.
12.2.5 Key Distribution and Focus
Here's a simplified account of how a dialog processes OfferKeyEventL() (for the full
truth, check out CEikDialog::OfferKeyEventL() in the SDK).
In UIQ, the primary method of text input is the FEP. UIQ provides two FEPs: a handwriting
recognition method and an on-screen virtual keyboard; others may be written by third
parties. Both FEPs receive pointer events and translate them into key events, which are
passed to the application. Whether the key event is generated by a FEP or by a real
keyboard shouldn't make any difference to your app. If you are creating a new control that
can receive text input, you need to override CCoeControl's virtual
InputCapabilities() method. This tells the FEP whether it can accept text input, and if
so, which types of input are supported. The default implementation in CCoecontrol returns
TCoeInputCapabilities::Enlone.
At any one time, precisely one of the controls in the captioned control array has focus. That
means the line is either highlighted, or displays a cursor, and is the recipient of 'most' key
events. When the dialog is offered a key event, it handles some special cases itself (for
instance, it offers Confirm to the dialog buttons), but otherwise it offers the key to the
currently focused general-purpose control.
Note
A general-purpose control is one that can be used both in dialogs and app
views. Incidentally to make a control intended for dialogs usable in app views
isn't always difficult, and it's a good thing to aim for. But to make a control
intended for app views usable in a dialog is rarely necessary, and you
shouldn't try to do so without good reason.
There are plenty of special cases (such as support for the page selector), but this description
is enough to illustrate the role of focus, and also to begin to show why keys are offered, and
why they are not always consumed.
It's important to give a clear visual indication of focus and all the components work together
to achieve this:
� The dialog is the topmost window: it has focus merely by being there.
� The buttons and the title bar can never receive focus so they don't need to change
their drawing code in response to whether they're focused or not.