Simple controls and compound controls

In addition to being window-owning or non-window-owning, each control is either a simple control or a compound control.

A simple control, such as a label or an image, is one which contains no other controls. A simple control may be window-owning or non-window-owning. The majority of simple controls, in practice, are non-window-owning.

A compound control is one which contains one or more simple or compound controls. Compound controls are also known as container controls and may be window-owning or non-window-owning.

The controls contained by a compound control are its component controls. Components may also be window-owning or non-window-owning. The majority, in practice, are non-window-owning.

The implementation of compound controls changed in version 9.1 of Symbian OS. The previous APIs and the old 'way of working' are still supported but do not support new automated features such as background drawing, font provision, layout managers and accumulated zoom.

The new 'way of working' is currently used by UIQ v3.

S60, MOAP and older versions of UIQ use the old scheme.

Under the old (pre 9.1) scheme the way in which a compound control stored its component controls is not mandated by the framework. Controls derived from CCoeControl are free to store their components as they see fit. They have to implement the virtual function CCoeControl::CountComponentControls() to return the number of components, and also to provide CCoeControl::ComponentControl() to return the CCoeControl* pointing to a particular component. This is very flexible but places a greater burden on application developers and means that it is impossible for tools or agents to make assumptions about the internal structure of controls.

Under the new (9.1 and onwards) scheme CCoeControl provides a storage mechanism and an API for adding, retrieving and removing components. Besides simplifying the API and making life easier for developers this ensures consistency which allows run-time agents, such as layout managers and skins managers, to act across all of the controls in the UI. The CCoeControl::CountComponentControls() and CCoeControl::ComponentControl() functions are now implemented by the base class. By default, CCoeControl also now takes responsibility for deleting its lodgers.

The new scheme provides two methods for identifying component controls - one to be used by the parent, which gives each sibling component a unique ID, and one which allows each control within a view to have a UniqueHandle. The latter is primarily to enable resource driven view construction but is also useful for automated testing.

The control framework (both old and new) provides logic to handle redrawing and the distribution of pointer events to component controls. A compound control must handle distribution of key events to its components. Non-window owning lodger components should not overlap* and must be contained within the extent of the compound control. This does not pose a restriction for most UI elements, such as buttons and labels, as they never need to overlap and never need to be displayed outside their containers.

Component controls may themselves be compound. There is no limit on the number of levels of compounding.

*Overlapping controls may be used in conjunction with MCoeControlHitTest. See How to write controls

Run-time control hierarchy

How to write controls