How +to write controls

Cone itself does not provide any concrete controls. Uikon and the UI variant +libraries provide a large number of 'stock' controls for application writers. +Application writers often need to supplement the standard set of controls +with application specific controls of their own. These may be completely new +controls or, more often, compound controls which contain a number of standard +controls.

This section describes how to create controls and how to integrate them +in to the control framework. It is divided into the following sections:

Creating +a control

Window +owning or not?

Creating +a compound control

Size, +position and layout

Drawing +and refreshing

Drawing +backgrounds

Drawing +text

Drawing +graphics

Handling +events

Implementing +the Object Provider (MOP) interface

Creating a +control

A control is a class which derives from CCoeControl. +It should have a public constructor and, if any leaving function calls or +memory allocations are required during construction, a ConstructL() function. +The majority of re-useable and configurable controls have a ConstructFromResourceL() function +which allows a specific instance of a control to be configured using an application's +resource file. Obviously any memory allocated must be freed in the destructor. +Before a control is drawn to the screen it must be activated. The ActivateL() +function may be overriden to perform last-minute configuration (but +must call the function in the base class).

+Class CMyControl : public CCoeControl + { + public: + CMyControl() ; + void ConstructL(...) ; + // from CCoeControl + void ConsructFromResourceL( TResourceReader& aReader ) ; + private: + ~CMyControl() ; + + // additional functions to handle events + // additional functions to draw the control + // additional functions to determine the size, layout and position the control + }

Window owning +or not?

The decision over whether to make a control window owning +or not is usually straightforward. Each view requires a window, so the top-level +control must be window-owning and a child of the AppUi. Below this a window +owning control is normally only necessary where a sense of layering is required: +for instance a pop-up window or a scrolling window. Dialogs and menus are +window owning controls but these are normally implemented in the Uikon and +UI variant libraries and do not require custom derivation from CCoeControl. +Unnecessary window-owning controls should be avoided as they require more +infrastructure, place greater demand on the Window Server and reduce performance.

If +a control must be window owning its window must either be created in the ConstructL() function +or by the caller. The former is preferred. There are several overloads of +the CreateWindowL() and CreateBackedUpWindowL() functions. +Those which do not take a parent parameter create a top-level window which +is a child of the root window.

If a control is not window owning its SetContainerWindowL() function +must be called when it is instantiated.

If it can, the Framework will +automatically set up the parent pointer when the window, or associated window +relationship is established. If it cannot do this, because CreateWindowL() or SetContainerWindowL() did +not provide a CCoeControl, the parent pointer (and MopParent) +may be set expicitly using SetParent() and SetMopParent().

Creating a +compound control

Most applications UIs are built from compound +controls. Many custom controls are built up from stock controls and are therefore +also compound controls. When a compound control is constructed it constructs +its components in its ConstructL() function. When it receives +commands itself, such as ActivateL() and DrawNow() it +passes them on to each of its components. In most cases the Framework does +much of the donkey work as long as the compound control has been constructed +correctly.

There are now two methods of creating and managing lodger +controls. The first method described is the one that should be used.

+void MyControl::ConstructL( ... ) + { + // initialise the component array. This must be called once (subsequent calls have no effect) + InitComponentArrayL() ; + + // construct each component control and add it to the component array. + CComponent* myComponent = new (ELeave) CComponent ; + Components().AppendLC( myComponent ) ; // or InsertLC or InsertAfterLC(). Places item on cleanup stack. + myComponent->ConstructL() ; + myComponent->SetThisAndThatL() ; + CleanupStack::Pop( myComponent ) ; + }

The return value of the insert and append methods is +a CCoeControlArray::TCursor object which works as an iterator. +It will remain valid when other items are inserted or deleted, or even if +the whole array is re-ordered.

The insert and append methods leave +the component on the Cleanup Stack using a dedicated Cleanup Item that protects +the parent's array as well as the component itself.

The insert and +append methods allow each component to be given an ID. The ID must be unique +only within the parent so typically a compound control will have an enum listing +each of its children's IDs. CCoeControlArray , accessed +using CCoeControl::Components(), has a ControlById() method +to retrieve components using their IDs.

Components in the array are, +by default, owned by the parent and will be deleted automatically when the +parent is deleted. The default may be overridden using CCoeControlArray::SetControlsOwnedExternally(). +The setting applies to all of the components.

Controls may be removed +from the array using one of the Remove() methods. These do +not delete.

+class CCoeControlArray + ... + public: + IMPORT_C TInt Remove(const CCoeControl* aControl); + IMPORT_C CCoeControl* Remove(TCursor aRemoveAt); + IMPORT_C CCoeControl* RemoveById(TInt aControlId); + ... +

Using the component array as described is now the approved +method of constructing and managing compound controls. In older versions of +Symbian OS a specific method of handling components was not provided and developers +were obliged to design their own. Bypassing the component array is still possible. +It is necessary to allocate and store the components (typically as member +data) and to implement the CountComponentControls() and ComponentControl() functions +to return the number of components and a specified component to the framework. +The new method offers significant advantages when controls are added and removed +dynamically or are dependant on run-time data. The new method is also integrated +with new layout managers.

Size, position +and layout

There are several factors which contribute to a control's +size and position. The control itself will require a certain size in order +to display itself (and its data) correctly. The control's container will be +responsible for positioning the control but is also likely to be responsible +for positioning other controls - each of which will have its own requirements. +Additionally there are the requirements of the UI's look and feel that must +be complied with.

Each control is responsible for implementing its +own Size() function.

Until Symbian OS version 9.1 +it was normal to write layout code for simple and compound controls in the SizeChanged() function. +This is called by the framework, as one might expect, when a control's size +(its 'extent') is changed. From 9.1, however, Symbian OS supports the use +of the layout manager interface (MCoeLayoutManager) and +the SizeChanged() function is now implemented in the base +class. (Note that if a control's position is changed, with no size change, +using CCoeControl::SetPosition() its PositionChanged() function +is called and that default implementation of PositionChanged() is +empty).

+class MCoeLayoutManager + ... + protected: + IMPORT_C MCoeLayoutManager(); + + public: + virtual TBool CanAttach() const = 0; + virtual void AttachL(CCoeControl& aCompoundControl) = 0; + virtual void Detach(CCoeControl& aCompoundControl) = 0; + virtual TSize CalcMinimumSize(const CCoeControl& aCompoundControl) const = 0; + virtual void PerformLayout() = 0; + virtual TInt CalcTextBaselineOffset(const CCoeControl& aCompoundControl, const TSize& aSize) const = 0; + virtual void SetTextBaselineSpacing(TInt aBaselineSpacing) = 0; + virtual TInt TextBaselineSpacing() const = 0; + virtual void HandleAddedControlL(const CCoeControl& aCompoundControl, const CCoeControl& aAddedControl) = 0; + virtual void HandleRemovedControl(const CCoeControl& aCompoundControl, const CCoeControl& aRemovedControl) = 0; + virtual TInt HandleControlReplaced(const CCoeControl& aOldControl, const CCoeControl& aNewControl) = 0; + ... +

A layout manager may be attached to a compound control.

+class CCoeControl + ... + protected: + IMPORT_C MCoeLayoutManager* LayoutManager() const; + IMPORT_C virtual void SetLayoutManagerL(MCoeLayoutManager* aLayoutManager); + + public: + IMPORT_C virtual TBool RequestRelayout(const CCoeControl* aChildCtrl); + ...

The default implementations of MinimumSize() and SizeChanged() now +use the layout manager.

+EXPORT_C TSize CCoeControl::MinimumSize() + { + const MCoeLayoutManager* layoutManager = LayoutManager(); + if (layoutManager) + return layoutManager->CalcMinimumSize(*this); + else + return iSize; + } + +EXPORT_C void CCoeControl::SizeChanged() + { + MCoeLayoutManager* layout = LayoutManager(); + if (layout) + layout->PerformLayout(); +

The layout manager is responsible for the size and position +of the component controls. In practice it's likely that the UI variant libraries +will provide concrete layout managers. Application developers should use these +as the basis for control-specific layout managers.

Drawing and +refreshing

A fundamental requirement of most controls is that they +are able to render themselves onto the screen. For most controls the drawing +process involves outputting text, painting backgrounds (either plain or from +a bitmap), drawing shapes (graphics objects) and drawing component controls.

Screen +drawing may be initiated by the application itself, following something within +the application changing, or by the Window Server, due to something else in +the system updating the screen while the application is visible. In both cases +the control's Draw() function will be called automatically +by the framework. For compound controls all of the components' Draw() functions +will also be called - unless the component lies completely outside the area +that requires redrawing.

As a control writer you will probably have +to implement a Draw() function.

Here is the signature +for Draw():

private: + void Draw( const TRect& aRect ) const ;

Note that it +is private, takes a const TRect& as a parameter, must +not leave and is const.

It should only be called +by the framework. Application initiated redraws should be through calls to DrawNow(), DrawDeferred() or +custom functions for drawing smaller elements.

The aRect parameter +is the part of the control that requires drawing (refreshing).

The +function is const and non-leaving because it is intended +to support the decoupling of drawing actions from application state.

Drawing backgrounds

A +control's background is typically determined by the current colour scheme +or skin. It may be a plain colour or a bitmap. It's also possible that a control +is to appear non-rectangular or transparent in which case some of the background +will be the control underneath. Prior to Symbian OS 9.1 controls were required +to clear and update their whole area and creating these effects was rather +complex. From 9.1 controls are drawn 'backmost first'.

Background +drawing should be done by a dedicated background drawer - i.e. an object which +implements the MCoeControlBackground interface. A background +can be attached to a CCoeControl using SetBackground() and +is used for that control and all of its children. When a control is drawn +the framework looks for the nearest background up the run-time hierarchy and +calls MCoeControlBackground::Draw().

UI variant libraries +typically provide backgrounds. They are not owned by the controls to which +they are attached.

Drawing text

Text +must be drawn with the correct color, font, size and direction. As with backgrounds, +these are determined at runtime according to UI customizations. This is achieved +by means of a Text Drawer. Note the use of the XCoeTextDrawer class. +This is a smart pointer (note the use of the -> operator +to access CCoeTextDrawerBase functions) which ensures that +only one text drawer is allocated on the heap at a time.

+XCoeTextDrawer textDrawer( TextDrawer() ); +textDrawer->SetAlignment(iAlignment); +textDrawer->SetMargins(iMargin); +textDrawer->SetLineGapInPixels(iGapBetweenLines); +textDrawer.SetClipRect(aRect); // have to use . [dot] operator for SetClipRect() as not CCoeTextDrawerBase function. + +textDrawer.DrawText(gc, *iTextToDraw, Rect(), *Font()); +

Text drawers are typically provided by the UI variant library +or skin manager. Controls within the run-time hierarchy can set the text drawer +for their children by overriding GetTextDrawer().

Note +that the text drawer expects text to be passed as a TBidiText rather +than a descriptor. Controls should store all display text in TBidiText objects. +Application writers should consider the implications of right-to-left layouts +for languages such as Hebrew and Arabic.

A control's GetTextDrawer() function +might look something like this. It checks on the current state of the control +(IsDimmed()) and passes the call on to a skin manager.

+EXPORT_C void CMyButtonControl::GetTextDrawer(CCoeTextDrawerBase*& aTextDrawer, const CCoeControl* aDrawingControl, TInt /*aKey*/) const + { + const TInt textDrawerIndex = (IsDimmed() ? EButtonTextDimmed : EButtonText); + + SkinManager::GetTextDrawer(aTextDrawer, KSkinUidButton, textDrawerIndex, aDrawingControl); + } +

If the control is drawing text on its own graphics (and does +not care about the text drawer of its parents) it can just create an XCoeTextDrawer object +on the stack in its Draw() method and initiate it from the +skin that it is currently using to draw its graphics, using the CSkinPatch::TextDrawer() method, +like this:

+const CSkinPatch& skin = SkinManager::SkinPatch(KSomeSkinUid, KSomeSkinIndex, this); + +skin.DrawBitmap(gc, Rect(), aRect); +XCoeTextDrawer textDrawer( skin.TextDrawer(KSomeSkinUid, ESomeSkinTextDimmed, this) ); + +const CFont& font = ScreenFont(TCoeFont::NormalFont); +textDrawer.DrawText(gc, iText, rect, font); +

The example above also illustrates how to retrieve the correct +font. CFont objects must not be stored in control member +data as they must change when the control's zoom state changes. Instead, a TCoeFont that +represents a font's size (logical or absolute in pixels) and style (plain, +bold, italic, subscript, or superscript) should be used.

+class TCoeFont + ... + public: + IMPORT_C TCoeFont(TLogicalSize aSize, TInt aStyle, TInt aFlags = ENoFlags); + IMPORT_C TCoeFont(TInt aHeightInPixels, TInt aStyle, TInt aFlags = ENoFlags); + IMPORT_C TCoeFont(const TCoeFont& aFont); + IMPORT_C TCoeFont(); + ...

By creating a TCoeFont object +describing the properties of the desired font, a CFont object +reference (needed to actually draw the text) can be fetched from the CCoeFontProvider. +A font provider can be attached to any CCoeControl and +will keep information about the typeface used by that control and all controls +below. A default font provider is attached to the CCoeEnv.

+class CCoeControl + ... + public: + IMPORT_C const CCoeFontProvider& FindFontProvider() const; + IMPORT_C void SetFontProviderL(const CCoeFontProvider& aFontProvider); + ... +

To get hold of the CFont object +a Draw() method can be implemented like this:

+void CMyControl::Draw(const TRect& aRect) + { + const CCoeFontProvider& fontProvider = FindFontProvider(); + const CFont& font = fontProvider.Font(TCoeFont::LegendFont(), AccumulatedZoom()); + + XCoeTextDrawer textDrawer( TextDrawer() ); + textDrawer->SetAlignment(EHCenterVCenter); + textDrawer.DrawText(gc, iText, rect, font); + } +

For convenience there’s a CCoeControl::ScreenFont() method +that locates the font provider and calls it with the control’s accumulated +zoom:

+class CCoeControl + ... + protected: + IMPORT_C const CFont& ScreenFont(const TCoeFont& aFont) const; + ... +

Drawing graphics

Controls +draw graphics objects - lines, rectangles, shapes and bitmaps to a graphics +context. The graphics context is provided by the Window Server and +represents a group of settings appropriate for the physical device that is +ultimately being drawn to. In most cases the device is a screen and a graphics +context should be obtained using CCoeControl::SystemGc(). CCoeControl::SystemGc() gets +the current graphics context from the run-time hierarchy. Controls in the +hierarchy may override graphics context settings which will then be passed +on to their children. Controls should not get their graphics context directly +from CCoeEnv as to do so would bypass the hierarchy.

+void CMyControl::Draw( const TRect& aRect ) + { + CWindowGc& gc = SystemGc() ; // get gc from run time hierarchy + TRect rect = TRect( Size() ) ; + if ( IsBlanked() ) + { + // blank out the entire control + gc.SetPenStyle( CGraphicsContext::ENullPen ) ; + gc.SetBrushStyle( CGraphicsContext::ESolidBrush ) ; + TRgb blankColor = BlankingColor() ; + gc.SetBrushColor( blankColor ) ; + gc.DrawRect( rect ) ; + } + else + { + // draw masked bitmap in the centre of the control + // The parent will draw the background + TInt id = BitMapId() ; + + TInt x = Size().iWidth - iBitmap[id]->SizeInPixels().iWidth ; + TInt y = Size().iHeight - iBitmap[id]->SizeInPixels().iHeight ; + + TPoint pos = Rect().iTl ; + pos.iX = pos.iX + ( x / 2 ) ; + pos.iY = pos.iY + ( y / 2 ) ; + + gc.BitBltMasked( pos, iBitmap[id], rect, iMaskBitmap, ETrue ) ; + } + }

Before a graphics context can be used it must be activated. +After use it must be deactivated. Activation and deactivation are done automatically +by the framework in DrawNow(), DrawDeferred() and HandleRedrawEvent() but +must be done explicitly for any other application initiated drawing by calling ActivateGc() and DeactivateGc().

Controls may implement partial drawing to speed up performance. The Draw() function +may be split into sub functions: DrawThis(), DrawThat(), DrawTheOther(). +Each of these requires a corresponding DrawThisNow() and/or DrawThisDeferred() function.

+CMyControl::Draw() + { + DrawThis() ; + DrawThat() ; + DrawTheOther() ; + } +CMyControl::DrawThisNow() + { + ActivateGc() ; + DrawThis() ; + DeactivateGc() ; + }

Handling events

The +Control Framework supports user interaction in two ways: key-press events +and pointer events. Both types of event arrive through the Window Server though +they each arrive in a slightly different way. Both are closely related to +the concept of 'focus' and the location of the cursor.

Handling +key events

Key events are delivered to the AppUi. The Window +Server channels them through the root window of its current window group which +maps to the AppUi foreground application. The AppUi offers each key event +to each of the controls on its control stack in priority order until one of +the controls 'consumes' it.

To receive key events a control must implement CCoeControl::OfferKeyEventL(). +If it handles the event it must return EKeyWasConsumed: If +it doesn't it must return EKeyWasNotConsumed so that the +next control on the stack receives it.

+TKeyResponse CMyControl::OfferKeyEventL( const TKeyEvent& aKeyEvent, TEventCode aType) + { + TKeyResponse returnValue = EKeyWasConsumed ; + switch( aKeyEvent.iCode ) + { + case EKeyEnter : + // do stuff + break ; + case EKeyEscape : + // do stuff : + break ; + + ... + + default : + // did not recognise key event + returnValue = EKeyWasNotConsumed ; + break ; + } + return returnValue ; + }

The handling of key events will depend on the design +and purpose of the control itself. Compound controls might need to keep track +of an input focus, or cursor, and to pass key events amongst +its lodgers. Input into one lodger might have an effect on another - pressing +a navigation key might cause one control to lose the highlight and another +to gain it, pressing a number key might cause a text editor to grow which +might, in turn, require all of the components below it to shuffle downwards +and a scroll bar to become visible (which might also require some controls +to be laid out differently).

Handling pointer events

Pointer +events are slightly different as the position of the pointer, rather than +of the focus, is significant. The Window Server passes a pointer event to +the top-most visible window at the point of contact. The Framework uses the +functions ProcessPointerEventL() and HandlePointerEventL() to +work down the hierarchy. The Framework also uses the MCoeControlObserver and +focussing mechanisms to inform the observer of the controls that will be losing +and gaining the focus.

Using the Control Observer Interface

The +Control Framework facilitates this type of relationship between a container +and its lodgers with the MCoeControlObserver interface. Typically +the container implements the interface and becomes the observer for each lodger +that can receive user input (focus). There is only one function in MCoeControlObserver:

virtual void HandleControlEventL( CCoeControl *aControl, TCoeEvent aEventType ) = 0 ;

and it is called when an observed control calls

void CCoeControl::ReportEvent( MCoeControlObserver::TCoeEvent aEvent ) ;

A control can have only one observer (or none) so ReportEvent() does +not need to specify an observer. An observer may observe any number of controls +so HandleControlEventL() takes the observed control as a +parameter. The other piece of information passed to the observer is a TCoeEvent.

enum TCoeEvent + { + EEventRequestExit, + EEventRequestCancel, + EEventRequestFocus, + EEventPrepareFocusTransition, + EEventStateChanged, + EEventInteractionRefused + };

CCoeControl also provides IsFocused(), SetFocused() and IsNonFocussing(). Note that Framework does not attempt to ensure exclusivity of focus, nor +does it give any visible indication of focus. It is up to the application +developer to ensure that only one control has the focus at a time, that the +focus is correctly transferred between controls, that only appropriate controls +receive the focus and that the focus is visible at all times.

void CContainer::HandleControlEventL(CCoeControl* aControl, TCoeEvent aEventType) + { + switch (aEventType) + { + case EEventRequestFocus: + { + if( !(aControl->IsFocussed()) ) + { + aControl->SetFocus( ETrue ) ; + // remove focus from other controls + for ( Tint ii = 0 ; ii < CountComponentControls() ; ii++ ) + { + CCoeControl* ctl = ComponentControl( ii ) ; + if( ( ctl != aControl ) && !( ctl->IsNonFocussing() ) ) + { + aControl->SetFocus( EFalse ) ; + } + } + } + } + break; + ... + } + }

Control developers may implement HandlePointerEventL(), +which is a virtual function, to perform pointer event functionality. The implementation +must, however, call the base class function.

Controls may modify their +pointer area, possibly if they appear non-rectangular or overlap. To do so +requires the addition of a hit test which describes a hit-test region. A hit-test +region may cover all or part of one or more controls. A hit for a control +is registered in the area covered by both the control and its associated hit +test.

The diagram below represents three controls, each of which is +rectangular but which appears on the screen as a non-rectangular bitmap. Only +a hit on a bitmap area should register. This could be achieved by defining +a single hit-test region in the shape (and position) of the three blue areas +and associating it with each of the controls. The class that implements the +hit-test region must implement the MCoeControlHitTest interface.

+ Hit-test region example + + +class MCoeControlHitTest + ... + public: + virtual TBool HitRegionContains( const TPoint& aPoint, const CCoeControl& aControl ) const = 0; +

A hit test is associated with a control using CCoeControl::SetHitText(). +The base class implementation of HandlePointerEventL() performs +the following test:

+ ... + const MCoeControlHitTest* hitTest = ctrl->HitTest() ; + if( hitTest ) + { + if( hitTest->HitRegionContains( aPointerEvent.iPosition, *ctrl ) && + ctrl->Rect().Contains( aPointerEvent.iPosition ) )

Note +that this is performed by a container when deciding which lodger to pass the +event onto. This snippet also illustrates how a control can find where (iPosition) +the pointer event actually occurred.

Pointer support includes dragging +& grabbing. See TPointerEvent.

Implementing +the Object Provider (MOP) interface

The Object +Provider mechanism exists to allow a control to call a function on +another control in the hierarchy for which it does not have a reference. It +simply calls MopGetObject() specifying the interface containing +the function. It may also call MopGetObjectNoChaining() to +inquire of a specific object whether it supports the requested interface.

Only +controls which wish to supply an interface require customisation. In order +to be identifiable an interface must have an associated UID. The following +code samples show how CEikAlignedControl implements and +supplies MEikAlignedControl:

+class MEikAlignedControl + ... + public: + DECLARE_TYPE_ID( 0x10A3D51B ) // Symbian allocated UID identifies this interface + ... + +class CEikAlignedControl : public CCoeControl, public MEikAlignedControl + { + ... + private: //from CCoeControl + IMPORT_C TTypeUid::Ptr MopSupplyObject( TTypeUid aId ) ; + ... + +EXPORT_C TTypeUid::Ptr CEikAlignedControl::MopSupplyObject( TTypeUid aId ) + { + if( aId.iUid == MEikAlignedControl::ETypeId ) + return aId.MakePtr( static_cast<MEikAlignedControl*>( this ) ) ; + + return CCoeControl::MopSupplyObject( aId ) ; // must call base class! + } +

To get an interface from the object provider framework the +caller must use a pointer to the interface.

+ ... + MEikAlignedControl* alignedControl = NULL ; + MyControl->MopGetObject( alignedControl ) ; + if ( alignedControl ) + { + ... // etc.

To get an interface from a specific object +the caller may use the no-chaining function call.

+ ... + MEikAlignedControl* alignedControl = NULL ; + aControl->MopGetObjectNoChaining( alignedControl ) ; + if ( alignedControl ) + { + ... // etc.