CCoeControl Class Reference

#include <mw/coecntrl.h>

Link against: cone.lib

class CCoeControl : public CBase, public MObjectProvider

Inherits from

Protected Attributes
CCoeEnv *iCoeEnv
MCoeControlContext *iContext
TPoint iPosition
TSize iSize
Public Member Enumerations
enumTEventDataConfig { EEventDataAllowGroupedPointerEvents }
enumTPrepareType { EPrepareProcess, EPrepareHandle }
enumTZoomType { EAbsoluteZoom, ERelativeZoom }
Public Member Functions
CCoeControl()
CCoeControl(CCoeEnv *)
~CCoeControl()
IMPORT_C TZoomFactorAccumulatedZoom()
virtual IMPORT_C voidActivateL()
IMPORT_C const MCoeControlBackground *Background()
IMPORT_C voidClaimPointerGrab(TBool)
IMPORT_C TIntClaimPointerGrab(TInt, TBool)
IMPORT_C TBoolComponentArrayExists()
virtual IMPORT_C CCoeControl *ComponentControl(TInt)
IMPORT_C TIntConfigureEventData(TInt)
virtual IMPORT_C voidConstructFromResourceL(TResourceReader &)
IMPORT_C MCoeControlContext *ControlContext()
CCoeEnv *ControlEnv()
IMPORT_C voidCopyControlContextFrom(const CCoeControl *)
virtual IMPORT_C TIntCountComponentControls()
IMPORT_C CWindowGc *CustomGc()
IMPORT_C voidDrawBackground(const TRect &)
IMPORT_C voidDrawDeferred()
IMPORT_C voidDrawForeground(const TRect &)
IMPORT_C voidDrawNow()
IMPORT_C voidDrawNow(const TRect &)
IMPORT_C RDrawableWindow *DrawableWindow()
IMPORT_C voidEnableReportControlStateChange(TBool)
TInt EventDataConfiguration()
IMPORT_C const MCoeControlBackground *FindBackground()
IMPORT_C const CCoeFontProvider &FindFontProvider()
IMPORT_C TBoolGetColor(TInt, TRgb &)
virtual IMPORT_C voidGetColorUseListL(CArrayFix< TCoeColorUse > &)
CWindowGc *GetGc()
virtual IMPORT_C voidGetHelpContext(TCoeHelpContext &)
virtual IMPORT_C voidHandlePointerEventL(const TPointerEvent &)
virtual IMPORT_C voidHandleResourceChange(TInt)
virtual IMPORT_C TBoolHasBorder()
IMPORT_C const MCoeControlHitTest *HitTest()
IMPORT_C voidIgnoreEventsUntilNextPointerUp()
IMPORT_C TIntIndex(const CCoeControl *)
virtual IMPORT_C TCoeInputCapabilitiesInputCapabilities()
IMPORT_C TBoolIsBackedUp()
IMPORT_C TBoolIsDimmed()
IMPORT_C TBoolIsFocused()
IMPORT_C TBoolIsNonFocusing()
IMPORT_C TBoolIsVisible()
IMPORT_C MCoeLayoutManager *LayoutManager()
virtual IMPORT_C voidMakeVisible(TBool)
IMPORT_C TIntMaximumWidth()
virtual IMPORT_C TSizeMinimumSize()
voidNotifyFontChange(const CCoeFontProvider *)
IMPORT_C MCoeControlObserver *Observer()
virtual IMPORT_C TKeyResponseOfferKeyEventL(const TKeyEvent &, TEventCode)
IMPORT_C voidOverrideColorL(TInt, TRgb)
IMPORT_C TBoolOwnsWindow()
IMPORT_C CCoeControl *Parent()
IMPORT_C const CCoeControl *Parent()
IMPORT_C TPointPosition()
IMPORT_C TPointPositionRelativeToScreen()
virtual IMPORT_C voidPrepareForFocusGainL()
virtual IMPORT_C voidPrepareForFocusLossL()
voidProcessPointerBufferReadyL()
voidProcessPointerEventL(const TPointerEvent &)
IMPORT_C TRectRect()
voidRecursivelyMergeInputCapabilities(TCoeInputCapabilities &)
IMPORT_C TCoeInputCapabilitiesRecursivelyMergedInputCapabilities()
voidRefetchPixelMappingL()
voidRemoveFromParent()
virtual IMPORT_C TBoolRequestRelayout(const CCoeControl *)
virtual IMPORT_C voidSetAdjacent(TInt)
IMPORT_C voidSetBackground(const MCoeControlBackground *)
IMPORT_C voidSetComponentsToInheritVisibility(TBool)
virtual IMPORT_C voidSetContainerWindowL(const CCoeControl &)
IMPORT_C voidSetContainerWindowL(RWindow &)
IMPORT_C voidSetContainerWindowL(RBackedUpWindow &)
IMPORT_C voidSetControlContext(MCoeControlContext *)
IMPORT_C TIntSetCustomGc(CWindowGc *)
virtual IMPORT_C voidSetDimmed(TBool)
IMPORT_C voidSetExtent(const TPoint &, const TSize &)
IMPORT_C voidSetExtentToWholeScreen()
IMPORT_C voidSetFocus(TBool, TDrawNow)
IMPORT_C voidSetFocusing(TBool)
IMPORT_C voidSetFontProviderL(const CCoeFontProvider &)
TInt SetGc(CWindowGc *)
IMPORT_C voidSetGloballyCapturing(TBool)
IMPORT_C TIntSetHitTest(const MCoeControlHitTest *)
virtual IMPORT_C voidSetLayoutManagerL(MCoeLayoutManager *)
IMPORT_C TIntSetMaximumWidth(TInt)
IMPORT_C voidSetMopParent(MObjectProvider *)
virtual IMPORT_C voidSetNeighbor(CCoeControl *)
IMPORT_C voidSetNonFocusing()
IMPORT_C voidSetObserver(MCoeControlObserver *)
virtual IMPORT_C TIntSetParent(CCoeControl *)
IMPORT_C voidSetPointerCapture(TBool)
IMPORT_C voidSetPosition(const TPoint &)
IMPORT_C voidSetRect(const TRect &)
IMPORT_C voidSetSize(const TSize &)
virtual IMPORT_C voidSetTextBaselineSpacing(TInt)
IMPORT_C TIntSetUniqueHandle(TInt)
IMPORT_C voidSetZoomFactorL(TInt, TZoomType)
IMPORT_C TSizeSize()
IMPORT_C CWindowGc &SystemGc()
virtual IMPORT_C TIntTextBaselineOffset(const TSize &)
IMPORT_C TIntUniqueHandle()
voidWriteInternalStateNowL(RWriteStream &)
IMPORT_C const TCoeZoomWithType *ZoomWithType()
Protected Member Functions
CCoeControl(const CCoeControl &)
IMPORT_C voidActivateGc()
IMPORT_C RBackedUpWindow &BackedUpWindow()
IMPORT_C TBoolCapturesPointer()
IMPORT_C voidCloseWindow()
IMPORT_C CCoeControlArray &Components()
IMPORT_C const CCoeControlArray &Components()
IMPORT_C voidCreateBackedUpWindowL(RWindowTreeNode &)
IMPORT_C voidCreateBackedUpWindowL(RWindowTreeNode &, TDisplayMode)
IMPORT_C voidCreateWindowL()
IMPORT_C voidCreateWindowL(const CCoeControl *)
IMPORT_C voidCreateWindowL(RWindowTreeNode &)
IMPORT_C voidCreateWindowL(RWindowGroup *)
IMPORT_C voidDeactivateGc()
IMPORT_C voidEnableDragEvents()
IMPORT_C voidEnableWindowTransparency()
virtual IMPORT_C voidFocusChanged(TDrawNow)
IMPORT_C CCoeControl *GrabbingComponent()
IMPORT_C CCoeControl *GrabbingComponent(TInt)
IMPORT_C voidHandleComponentControlsResourceChange(TInt)
virtual IMPORT_C voidHandleControlArrayEventL(CCoeControlArray::TEvent, const CCoeControlArray *, CCoeControl *, TInt)
virtual IMPORT_C voidHandlePointerBufferReadyL()
IMPORT_C voidHandleRedrawEvent(const TRect &)
IMPORT_C voidInitComponentArrayL()
IMPORT_C TBoolIsActivated()
IMPORT_C TBoolIsBeingDestroyed()
IMPORT_C TBoolIsBlank()
IMPORT_C TBoolIsReadyToDraw()
IMPORT_C TBoolIsSemiTransparent()
virtual IMPORT_C TTypeUid::PtrMopSupplyObject(TTypeUid)
virtual IMPORT_C voidPositionChanged()
IMPORT_C voidReportEventL(MCoeControlObserver::TCoeEvent)
IMPORT_C voidResetGc()
IMPORT_C const CFont &ScreenFont(const TCoeFont &)
IMPORT_C voidSetAllowStrayPointers()
IMPORT_C voidSetBlank()
IMPORT_C voidSetCanDrawOutsideRect()
IMPORT_C voidSetCornerAndSize(TGulAlignment, const TSize &)
IMPORT_C voidSetSizeWithoutNotification(const TSize &)
virtual IMPORT_C voidSizeChanged()
IMPORT_C CCoeTextDrawerBase &TextDrawer(TInt)
IMPORT_C RWindow &Window()
virtual IMPORT_C voidWriteInternalStateL(RWriteStream &)
CCoeControl &operator=(const CCoeControl &)
Inherited Functions
CBase::CBase()
CBase::Delete(CBase *)
CBase::Extension_(TUint,TAny *&,TAny *)
CBase::operator new(TUint)
CBase::operator new(TUint,TAny *)
CBase::operator new(TUint,TLeave)
CBase::operator new(TUint,TLeave,TUint)
CBase::operator new(TUint,TUint)
CBase::~CBase()
MObjectProvider::FindParent(MObjectProvider *)
MObjectProvider::MObjectProvider()
MObjectProvider::MopGetObject(T *&)
MObjectProvider::MopGetObjectNoChaining(T *&)

Detailed Description

Control base class from which all other controls are derived.

Member Attribute Documentation

iCoeEnv

CCoeEnv *iCoeEnv[protected]

iContext

MCoeControlContext *iContext[protected]

iPosition

TPoint iPosition[protected]

iSize

TSize iSize[protected]

Member Enumeration Documentation

Enum TEventDataConfig

Contains flags for configuring event data.

EnumeratorValueDescription
EEventDataAllowGroupedPointerEvents0x01Used for enabling grouped pointer events.

Enum TPrepareType

There can be grouped and normal non-grouped events, which both need different kind of processing. These "preparation types" are used in common event handling code to tell what to do with the events once they are prepared for handling.

EnumeratorValueDescription
EPrepareProcessEvents are being prepared for ProcessPointerEventL.
EPrepareHandleEvents are being prepared for HandlePointerEventL.

Enum TZoomType

EnumeratorValueDescription
EAbsoluteZoom
ERelativeZoom

Constructor & Destructor Documentation

CCoeControl ( )

IMPORT_CCCoeControl()

Default C++ constructor.

Initialises the CCoeControl base class.

Note: CCoeControl is normally used as a base class from which concrete control classes are derived. However, it can also be instantiated as a concrete class.

CCoeControl ( CCoeEnv * )

IMPORT_CCCoeControl(CCoeEnv *aCoeEnv)

C++ constructor.

Initialises the CCoeControl base class.

Note: CCoeControl is normally used as a base class from which concrete control classes are derived. However, it can also be instantiated as a concrete class.

Parameters
aCoeEnvThe control environment.

CCoeControl ( const CCoeControl & )

CCoeControl(const CCoeControl &aControl)[protected, inline]

~CCoeControl ( )

IMPORT_C~CCoeControl()

Destructor.

It destroys the window owned by the control, if it is a window-owning control.

In debug builds, this checks if the control still exists on the control stack and raises a CONE 44 panic if it is. An application must remove every control that it has added to the stack.

Member Function Documentation

AccumulatedZoom ( )

IMPORT_C TZoomFactorAccumulatedZoom()const

Return the zoom factor for this control. Takes account of zoom factors in parent controls to calculate accumulated zoom factor.

Return Value
Accumulated zoom factor.

ActivateGc ( )

IMPORT_C voidActivateGc()const [protected]

Activates the standard graphics context.

This is the graphics context owned by the control environment (CCoeEnv).

Applications do not normally need to call this function, as it is called by the control framework whenever it is about to call Draw().

ActivateL ( )

IMPORT_C voidActivateL()[virtual]

Sets the control as ready to be drawn.

The application should call this function on all controls that are not components in a compound control.

The purpose of this function is that controls are not always ready to be drawn as soon as they have been constructed. For example, it may not be possible to set the control's extent during construction, but its extent should always be set before it is drawn. Similarly, if a control is to be made invisible, this should be done before it is activated.

The default implementation sets a flag in the control to indicate it is ready to be drawn. If the control is a compound control, the default implementation also calls ActivateL() for all the control's components. To get the control's components it uses CountComponentControls() and ComponentControl(), which should be implemented by the compound control.

ActivateL() is typically called from the control's ConstructL() function .

Notes:

This function can be overridden. This is useful for doing late initialisation of the control, using information that was not available at the time the control was created. For example, a text editor might override ActivateL() and use it to enquire whether it is focused: if it is, it makes the cursor and any highlighting visible. At the time when the editor is created, it doesn't know whether or not it has keyboard focus.

If overriding ActivateL(), the implementation must include a base call to CCoeControl's ActivateL().

BackedUpWindow ( )

IMPORT_C RBackedUpWindow &BackedUpWindow()const [protected]

Gets the backed-up window owned by the control.

The window must be of type RBackedUpWindow. If you don't know whether the window is of type RWindow or RBackedUpWindow, you should use DrawableWindow().

Deprecated

Return Value
The control's associated window, cast to an RBackedUpWindow.

Background ( )

IMPORT_C const MCoeControlBackground *Background()const

Returns the background drawer object associated with this object, if any. Null is returned if there is no such object. Compare with FindBackground(), which looks up the parent chain to find a background drawer.

Return Value
The background drawer object associated with this object.

CapturesPointer ( )

IMPORT_C TBoolCapturesPointer()const [protected]

Tests whether pointer capture is set for the control.

This returns true if SetPointerCapture() has been called with aCapture=ETrue.

Return Value
ETrue if pointer capture is set. EFalse if it isn't.

ClaimPointerGrab ( TBool )

IMPORT_C voidClaimPointerGrab(TBoolaSendUpEvent = ETrue)

Claims the pointer-grab from another control.

This ensures that all subsequent pointer events are delivered to it and not to the control that originally owned the grab.

The function allows a control to claim the pointer grab only if the pointer is already grabbed by another control.

This method is to be used in systems implementing single-pointer events. Or in systems implementing multiple-pointer events but where this control's window has single-pointer emulation enabled.

See also: RWindowBase::ClaimPointerGrab()

Parameters
aSendUpEventPassed as the argument to RWindowBase::ClaimPointerGrab().

ClaimPointerGrab ( TInt, TBool )

IMPORT_C TIntClaimPointerGrab(TIntaPointerNumber,
TBoolaSendUpEvent
)

Claims pointer grab from another control.

This ensures that all subsequent pointer events of the specified pointer are delivered to it and not to the control that originally owned the grab.

The function allows a control to claim the pointer grab only if the pointer is already grabbed by another control.

This method is intended to be called on a control who's window implements multi-pointer events. If called on a window without multiple pointers enabled, wserv will ignore the pointer number and grab the emulated pointer.

See also: RWindowBase::ClaimPointerGrab() RWindowBase::EnableMMultiplePointers()

Parameters
aPointerNumberThe number of the pointer for which to claim the grab.
aSendUpEventPassed as the argument to RWindowBase::ClaimPointerGrab().
Return Value
KErrNone if successful, KErrNotFound if pointer number out of range (Panics in debug build), or KErrNotSupported if incorrect pointer grab claimed for window in emulation mode.

CloseWindow ( )

IMPORT_C voidCloseWindow()[protected]

Closes the window owned by this control.

It is called from CCoeControl's destructor for window-owning controls.

ComponentArrayExists ( )

IMPORT_C TBoolComponentArrayExists()const

Return Value
ETrue if the component array exists, EFalse otherwise

ComponentControl ( TInt )

IMPORT_C CCoeControl *ComponentControl(TIntaIndex)const [virtual]

Gets an indexed component of a compound control.

There are 2 ways to implement a compound control. One way is to override this function. The other way is to use the CCoeControlArray functionality (see the InitComponentArrayL method).

Note: within a compound control, each component control is identified by an index, where the index depends on the order the controls were added: the first is given an index of 0, the next an index of 1, and so on.

Parameters
aIndexThe index of the control.
Return Value
The component control with an index of aIndex.

Components ( )

IMPORT_C CCoeControlArray &Components()[protected]

Returns a component array to store child controls.

This function is useful when the control is a compound control. The CCoeControlArray class provides functions to easily add and remove controls. The array must have been created before this function can be called. The InitComponentArrayL does this.

See also: CCoeControl::InitComponentArrayL()

Return Value
The control array

Components ( )

IMPORT_C const CCoeControlArray &Components()const [protected]

Returns a component array to store child controls.

This function is useful when the control is a compound control. The CCoeControlArray class provides functions to easily add and remove controls. The array must have been created before this function can be called. The InitComponentArrayL does this.

See also: CCoeControl::InitComponentArrayL()

Return Value
The control array

ConfigureEventData ( TInt )

IMPORT_C TIntConfigureEventData(TIntaEventDataConfig)

Configures events, used e.g. for enabling grouped pointer events.

See also: TEventDataConfig for possible values.

Parameters
aEventDataConfigThe configuration flags,
Return Value
KErrNone if configuring was successful, otherwise one of the system wide error codes.

ConstructFromResourceL ( TResourceReader & )

IMPORT_C voidConstructFromResourceL(TResourceReader &aReader)[virtual]

Constructs the control from a resource file.

This function has an empty default implementation. It should be implemented if the control is to be displayed within a dialog. It should initialise the control, reading in resource values from the resource file.

Note: if a control is not displayed in a dialog, it is necessary to set the control's associated window using SetContainerWindowL(). Since this may leave, the control should be constructed using ConstructL().

ControlContext ( )

IMPORT_C MCoeControlContext *ControlContext()const

Gets the control context being used by this control.

The function does not transfer ownership to the caller.

Return Value
The control context.

ControlEnv ( )

CCoeEnv *ControlEnv()const [inline]

Gets the control environment object for this control.

Return Value
The control's control environment object.

CopyControlContextFrom ( const CCoeControl * )

IMPORT_C voidCopyControlContextFrom(const CCoeControl *aControl)

Sets the control's context from another control.

Parameters
aControlThe control whose context is copied.

CountComponentControls ( )

IMPORT_C TIntCountComponentControls()const [virtual]

Gets the number of controls contained in a compound control.

There are 2 ways to implement a compound control. One way is to override this function. The other way is to use the CCoeControlArray functionality (see the InitComponentArrayL method).

Return Value
The number of component controls contained by this control.

CreateBackedUpWindowL ( RWindowTreeNode & )

IMPORT_C voidCreateBackedUpWindowL(RWindowTreeNode &aParent)[protected]

Creates a control's window as a backed-up window.

The new window is the child of aParent and the display mode of the control becomes the same as that of aParent.

Deprecated

Parameters
aParentThe window to be the parent of this control's window. Does not have to be a backed-up window.

CreateBackedUpWindowL ( RWindowTreeNode &, TDisplayMode )

IMPORT_C voidCreateBackedUpWindowL(RWindowTreeNode &aParent,
TDisplayModeaDisplayMode
)[protected]

Creates a control's window as a backed-up window.

The new window is the child of aParent. Furthermore, the window's extent is set to that of the control.

The window will have the same display mode as the system display mode (the provided aDisplayMode is ignored).

Deprecated

Parameters
aParentThe window of the control to be the parent of this control. Does not have to be a backed-up window.
aDisplayModeIgnored. The window will always be created with the system display mode.

CreateWindowL ( )

IMPORT_C voidCreateWindowL()[protected]

Creates a control's window.

The created window is the child of the application's window group.

This function makes the specified control a window-owning control, and would typically be called in the control's ConstructL() function.

Note:

The use of window owning controls is discouraged, as these tax run-time resources. Ideally only the top level control in an appUi would be window owning. There are some exceptions to this rule, e.g. floating controls like menus, dialogs and scroll bars.

CreateWindowL ( const CCoeControl * )

IMPORT_C voidCreateWindowL(const CCoeControl *aParent)[protected]

Creates a control's window, specifying the parent control.

The control's window is created as a child of the parent control's window.

This function makes the specified control a window-owning control, and would typically be called in the control's ConstructL() function.

Note:

The use of window owning controls is discouraged, as these tax run-time resources. Ideally only the top level control in an appUi would be window owning. There are some exceptions to this rule, e.g. floating controls like menus, dialogs and scroll bars.

In general, the overload with no parameters should be used.

Parameters
aParentThe control to be the parent of this control.

CreateWindowL ( RWindowTreeNode & )

IMPORT_C voidCreateWindowL(RWindowTreeNode &aParent)[protected]

Creates a control's window, specifying its parent window and its extent.

This function makes the specified control a window-owning control, and would typically be called in the control's ConstructL() function. It also sets the window's extent to that of the control.

Note:

The use of window owning controls is discouraged, as these tax run-time resources. Ideally only the top level control in an appUi would be window owning. There are some exceptions to this rule, e.g. floating controls like menus, dialogs and scroll bars.

In general, the overload with no parameters should be used.

Parameters
aParentThe window of the control to be the parent of this control.

CreateWindowL ( RWindowGroup * )

IMPORT_C voidCreateWindowL(RWindowGroup *aParent)[protected]

Creates a control's window, specifying its parent window group.

This function makes the specified control a window-owning control, and would typically be called in the control's ConstructL() function.

Note:

The use of window owning controls is discouraged, as these tax run-time resources. Ideally only the top level control in an appUi would be window owning. There are some exceptions to this rule, e.g. floating controls like menus, dialogs and scroll bars.

In general, the overload with no parameters should be used.

Parameters
aParentThe window group of the control to be the parent of this control

CustomGc ( )

IMPORT_C CWindowGc *CustomGc()const

Returns the custom graphics context set for this control (if any). Note that unlike CCoeControl::SystemGc(), this function ignores the parent window's state and returns the context set explicitly for this control instance, or NULL if none has been set.

Return Value
The current graphics context.

DeactivateGc ( )

IMPORT_C voidDeactivateGc()const [protected]

Deactivates the standard graphics context owned by the UI control framework.

Applications do not normally need to call this function, as it is called by the control framework whenever it has called Draw() and drawing is completed.

DrawBackground ( const TRect & )

IMPORT_C voidDrawBackground(const TRect &aRect)const

Draws the control's background using its graphics context. Unlike DrawNow() and DrawDeferred(), this function does not propagate the draw to component controls.

Parameters
aRectThe area to be redrawn. This can be the control's entire rectangle, or a sub-rectangle within it.

DrawDeferred ( )

IMPORT_C voidDrawDeferred()const

Draws the control, with low priority.

This function is called by an application or other code.

It causes the control area to be marked as invalid, which will eventually cause a redraw initiated by the window server. The control framework handles redraw events at a lower priority than user input events, which means that any pending user input events will be processed before the redraw event. DrawDeferred() therefore allows a control to do drawing at a lower priority than drawing performed by DrawNow().

An advantage of using DrawDeferred() is that if you make multiple calls to DrawDeferred() on the same area of a control, the window server will not generate a redraw event to do drawing that has already been superceded. If you make multiple calls to DrawNow(), however, all of them get processed, even if they have already been superceded by the time they are processed.

DrawForeground ( const TRect & )

IMPORT_C voidDrawForeground(const TRect &aRect)const

Draws the control's foreground using the control's graphics context. Unlike DrawNow() and DrawDeferred(), this function does not propagate the draw to component controls.

Parameters
aRectThe area to be redrawn. This can be the control's entire rectangle, or a sub-rectangle within it.

DrawNow ( )

IMPORT_C voidDrawNow()const

Draws the entire control

This function is called by an application or other code. The application should call this function when the control is first created and is ready for drawing, or if a change in application data or the control's internal state means that entire control's appearance is no longer up-to-date.

Partial redrawing of a control is sometimes more appropriate than drawing the entire control, and in this case, use DrawNow(const TRect &aRect) instead.

DrawNow() is implemented by CCoeControl and MAY NOT be overridden. It calls Draw() on the control itself, and also on all its component controls, if it is a compound control. (To do this it uses CountComponentControls() and ComponentControl(), which should be implemented by the derived control class.) If the control is a window-owning control, it also calls Draw() for its child windows (if any).

DrawNow ( const TRect & )

IMPORT_C voidDrawNow(const TRect &aRect)const

Draws the control, its components and child windows, within the bounds defined by the given rectangle.

Parameters
aRectThe rectangular region of the control to be drawn.

DrawableWindow ( )

IMPORT_C RDrawableWindow *DrawableWindow()const

Gets the control's associated drawable window.

The control must be a window-owning control.

This function should be called if it is not known whether the window is of type RWindow or RBackedUpWindow. RDrawableWindow is an abstract base class from which RWindow and RBackedUpWindow are derived.

See also: Window()

Return Value
The control's associated window.

EnableDragEvents ( )

IMPORT_C voidEnableDragEvents()[protected]

Requests pointer drag events.

This function should be called if a control is required to receive pointer drag and move events. The default behaviour for all controls is that pointer drag and move events are not delivered.

The control framework does not provide a function to disable drag events at a later time, but this can be done via the Window Server API, by calling Window()->PointerFilter().

Note:

By default, pointer move events are not delivered, even after calling EnableDragEvents(), because they are not normally required in a pen-based system. The window server can be configured to deliver pointer move events if required, e.g. for a mouse-based system.

See also: RWindowBase::PointerFilter()

EnableReportControlStateChange ( TBool )

IMPORT_C voidEnableReportControlStateChange(TBoolaState)

Set the status of the report control state change.

See also: SetDimmed(), MakeVisible()

Parameters
aStateSet the state as Enable or Disable to control the report control state change.

EnableWindowTransparency ( )

IMPORT_C voidEnableWindowTransparency()[protected]

By default, all windows are opaque. This means that semi-transparent drawing performed into the window will blend with other content of that window, but not with the content of the window(s) behind. This acts as an important performance optimization, limiting the amount of drawing needed to update the screen.

Call this method to allow semi-transparent drawing into the window to be blended with the content of the windows behind. (Because of the performance implications, be careful not to enable window transparency unless really required.)

This will set the window to use the alpha channel information of the drawing performed into it, and set the initialize window background to fully transparent (before any drawing is made into it).

Note that although the same effect can be achieved by calling the RWindow methods directly, calling this method instead will allow correct drawing of semi-transparent control backgrounds (see MCoeControlBackground).

This method must only be called on (non-BackedUp) window owning controls.

See also: MCoeControlBackground

EventDataConfiguration ( )

TInt EventDataConfiguration()const

Gets the current event configuration.

See also: TEventDataConfig.

Return Value
The current event configuration,

FindBackground ( )

IMPORT_C const MCoeControlBackground *FindBackground()const

Return an MCoeControlBackground object, if there is one - looking up the parent chain as necessary. Compare to Background(), which does not go up the parent chain.

FindFontProvider ( )

IMPORT_C const CCoeFontProvider &FindFontProvider()const

Return the font provider used by this control

Return Value
The font provider used by this control

FocusChanged ( TDrawNow )

IMPORT_C voidFocusChanged(TDrawNowaDrawNow)[protected, virtual]

Responds to a change in focus.

This is called whenever the control gains or loses focus, as a result of a call to SetFocus(). A typical use of FocusChanged() is to change the appearance of the control, for example by drawing a focus rectangle around it.

The default implementation is empty, and should be overridden by the CCoeControl-derived class.

Parameters
aDrawNowContains the value that was passed to it by SetFocus().

GetColor ( TInt, TRgb & )

IMPORT_C TBoolGetColor(TIntaLogicalColor,
TRgb &aColor
)const

Gets the overridden physical colour.

This is the colour which has been mapped to the logical colour specified by a call to OverrideColorL(). If the logical colour specified has not been overridden, the aColor value is not changed.

Parameters
aLogicalColorThe logical colour for which the corresponding physical colour will be retrieved. The set of logical colours for a standard GUI application are defined in TLogicalColor.
aColorOn return, contains the physical colour which has been mapped to aLogicalColour by a call to OverrideColorL().
Return Value
ETrue if aLogicalColour has been overridden, EFalse otherwise.

GetColorUseListL ( CArrayFix< TCoeColorUse > & )

IMPORT_C voidGetColorUseListL(CArrayFix< TCoeColorUse > &aColorUseList)const [virtual]

Gets the list of logical colours used to draw the control.

The list includes an explanation of how each colour is used. The default implementation is empty.

If overriding GetColorUseListL(), the implementation must include a base call to CCoeControl's GetColorUseListL().

Parameters
aColorUseListThe colour list.

GetGc ( )

CWindowGc *GetGc()const [inline]

Deprecated. See DeprecatedCCoeControl::CustomGc().

GetHelpContext ( TCoeHelpContext & )

IMPORT_C voidGetHelpContext(TCoeHelpContext &aContext)const [virtual]

Gets the control's help context.

The default implementation is empty. The function must be implemented in derived classes to associate the control with a particular Help file and topic in a context sensitive application. The implementation should set the public data members of TCoeHelpContext to the required Help file UID and context descriptor, as created using the Context-Sensitive Help Compiler.

Parameters
aContextThe control's help context

GrabbingComponent ( )

IMPORT_C CCoeControl *GrabbingComponent()const [protected]

Returns the component of this control which is grabbing the pointer in systems implementing a single pointer. Or in a multi-pointer system where single-pointer emulation is enabled on this control's window.

Return Value
The component control that is currently grabbing the pointer. If no component of this control is grabbing the pointer, or if this is not a compound control, the function returns NULL.

GrabbingComponent ( TInt )

IMPORT_C CCoeControl *GrabbingComponent(TIntaPointer)const [protected]

Returns the component of this control which is grabbing the specified pointer. This method is to be used on controls who's window has multiple-pointer events enabled.

Return Value
The component control that is currently grabbing the pointer. If no component of this control is grabbing the pointer, or if this is not a compound control, the function returns NULL.

HandleComponentControlsResourceChange ( TInt )

IMPORT_C voidHandleComponentControlsResourceChange(TIntaType)[protected]

Handles a change to the resources in the components of a compound control.

See also: HandleResourceChange()

Parameters
aTypeA message UID value.

HandleControlArrayEventL ( CCoeControlArray::TEvent, const CCoeControlArray *, CCoeControl *, TInt )

IMPORT_C voidHandleControlArrayEventL(CCoeControlArray::TEventaEvent,
const CCoeControlArray *aArray,
CCoeControl *aControl,
TIntaControlId
)[protected, virtual]

Handles events generated by the CCoeControlArray.

This function is useful when the control is a compound control and the CCoeControlArray functionality is used. The CCoeControlArray functions that add and remove controls will use this event handler to notify the control that child controls have been added or removed.

The default implementation of this function forwards the events to the layout manager (if there is one). If the event is EControlAdded it also sets the container window of the new child control unless the child control is a window owning control. If the event is EControlRemoved it also sets the parent of the removed child control to null.

Parameters
aEventThe type of the event
aArrayThe array that generated the event
aControlThe control affected by the event
aControlIdThe id of the control affected by the event

HandlePointerBufferReadyL ( )

IMPORT_C voidHandlePointerBufferReadyL()[protected, virtual]

Handles pointer buffer ready events.

This function is called whenever the control receives an event of type EEventPointerBufferReady, unless one of its component controls has grabbed the pointer, in which case the function is called on that control. An event of type EEventPointerBufferReady will only be received if the pointer move buffer has been set up using window server functions.

The pointer move buffer is typically used when the application requires a continuous stream of pointer drag events, such as in a drawing application.

See also: RWindowBase::AllocPointerMoveBuffer()

HandlePointerEventL ( const TPointerEvent & )

IMPORT_C voidHandlePointerEventL(const TPointerEvent &aPointerEvent)[virtual]

HandleRedrawEvent ( const TRect & )

IMPORT_C voidHandleRedrawEvent(const TRect &aRect)const [protected]

Handles redraw events.

In normal circumstances this function should not be used or overridden by the derived control class.

Parameters
aRectThe rectangle to be redrawn.

HandleResourceChange ( TInt )

IMPORT_C voidHandleResourceChange(TIntaType)[virtual]

Handles a change to the control's resources.

The types of resources handled are those which are shared across the environment, e.g. colours or fonts. For colour scheme changes, DrawDeferred() is called in order to redraw the control.

If overriding HandleResourceChange(), the implementation must include a base call to CCoeControl's HandleResourceChange().

See also: HandleComponentControlsResourceChange()

Parameters
aTypeA message UID value.

HasBorder ( )

IMPORT_C TBoolHasBorder()const [virtual]

Tests if the control has a border.

When component controls are arranged in a container, the container control may need to know whether or not the components have borders, as this may affect the way the components are laid out within the container.

The default implementation of this function returns EFalse, but can be overridden to provide the required functionality.

Return Value
ETrue if the control has a border, EFalse if the control does not have a border. The default implementation of this function returns EFalse.

HitTest ( )

IMPORT_C const MCoeControlHitTest *HitTest()const

Gets the object that defines the hit region inside the control's rectangle. The object is set by calling SetHitTest().

Return Value
The hit region tester.

IgnoreEventsUntilNextPointerUp ( )

IMPORT_C voidIgnoreEventsUntilNextPointerUp()

Sets the control to ignore pointer events until the next pointer up.

This means that all events until and including the next pointer up event are discarded and are not processed.

This can be used for example if the user presses the Esc key while selecting text by dragging the pointer device to ensure that further dragging does not result in continued selection.

Index ( const CCoeControl * )

IMPORT_C TIntIndex(const CCoeControl *aControl)const

Gets the index of a control that is a component of this control.

Parameters
aControlThe component control.
Return Value
The index of the component control within the compound control, or KErrNotFound if aControl is not a component of this control.

InitComponentArrayL ( )

IMPORT_C voidInitComponentArrayL()[protected]

Creates a component array to store child controls.

This function is useful when the control is a compound control. It creates an array where the child controls can be stored. The CCoeControl::Components return the created array. The CCoeControlArray class provides functions to easily add and remove controls.

InputCapabilities ( )

IMPORT_C TCoeInputCapabilitiesInputCapabilities()const [virtual]

Gets the control's input capabilities.

Classes that override CCoeControl::OfferKeyEventL() should also override this function, returning a TCoeInputCapabilities object whose attributes correspond to the behaviour of the OfferKeyEventL() function. The default implementation returns TCoeInputCapabilities::ENone.

It is not necessary to call InputCapabilities() on any component controls from inside a class's InputCapabilities() function. This is done automatically by the UI Control Framework.

Return Value
The control's input capabilities.

IsActivated ( )

IMPORT_C TBoolIsActivated()const [protected]

Tests if the control has been activated.

A control is not ready to draw until it is activated.

Return Value
ETrue if the control is activated, EFalse if it is not activated.

IsBackedUp ( )

IMPORT_C TBoolIsBackedUp()const

Tests if the window owned by the control is a backed-up window.

Deprecated

Return Value
ETrue if the window owned by this control is a backed-up window. EFalse if it is not a backed-up window.

IsBeingDestroyed ( )

IMPORT_C TBoolIsBeingDestroyed()const [protected]

Tests if the control is being destroyed.

Return Value
ETrue if the control is being destroyed, otherwise EFalse.

IsBlank ( )

IMPORT_C TBoolIsBlank()const [protected]

Tests if the control is blank.

This simply gets the value of the flag set by SetBlank().

Return Value
ETrue if SetBlank() has been called on the control. EFalse if SetBank() has not been called on the control.

IsDimmed ( )

IMPORT_C TBoolIsDimmed()const

Tests if the control is dimmed.

This function returns the value of a flag within the control which is set and unset using SetDimmed().

Return Value
ETrue if the control is dimmed, EFalse if it is not dimmed.

IsFocused ( )

IMPORT_C TBoolIsFocused()const

Tests if the control has focus.

Focus is set and unset using SetFocus().

Return Value
ETrue if the control has focus, EFalse if it doesn't.

IsNonFocusing ( )

IMPORT_C TBoolIsNonFocusing()const

Tests if the control can receive focus.

See also: SetNonFocusing()

Return Value
ETrue if the control cannot receive focus, EFalse if it can.

IsReadyToDraw ( )

IMPORT_C TBoolIsReadyToDraw()const [protected]

Tests if the control is ready for drawing.

This returns true if the control has been activated and is visible.

Return Value
ETrue if the control is ready for drawing, EFalse if it is not ready for drawing.

IsSemiTransparent ( )

IMPORT_C TBoolIsSemiTransparent()const [protected]

Checks whether semitransparency has been enabled for this control.

See also: EnableWindowTransparency()

IsVisible ( )

IMPORT_C TBoolIsVisible()const

Tests if the control is visible.

Unless MakeVisible() has been called with argument EFalse, the control is visible.

Return Value
ETrue if the control is visible, EFalse if it is invisible.

LayoutManager ( )

IMPORT_C MCoeLayoutManager *LayoutManager()const

Gets the layout manager

Return Value
The current layout manager, or NULL if the control has no layout manager

MakeVisible ( TBool )

IMPORT_C voidMakeVisible(TBoolaVisible)[virtual]

Sets this control as visible or invisible.

This causes the control to disappear or reappear. When a control is created, it is made visible by default.

MakeVisible() can be called before or after the control is activated.

Notes:

This function may be overridden.

The visibility of the control can be queried using IsVisible().

If MakeVisible() is used to make a component visible, and the control captures the pointer (see CapturesPointer()), MakeVisible() throws away any pending pointer events for that control.

Typical uses are for scrollbars, or for dialogs where some user responses are not required in certain circumstances.

Parameters
aVisibleETrue to make the control visible, EFalse to make it invisible.

MaximumWidth ( )

IMPORT_C TIntMaximumWidth()const

Gets the control's maximum width

Return Value
The controls maximum width. (0 if no value set).

MinimumSize ( )

IMPORT_C TSizeMinimumSize()[virtual]

Sets the control's minimum required size.

This function should be overridden by the concrete control class if the control is to be displayed inside a dialog. Standard GUI dialogs set the size and position of their components automatically, and use this function to enquire the minimum size that a control requires.

Other container controls that automatically calculate the layout of their components may also use this function.

Return Value
The minimum size required by the control.

MopSupplyObject ( TTypeUid )

IMPORT_C TTypeUid::PtrMopSupplyObject(TTypeUidaId)[protected, virtual]

Retrieves an object of the same type as that encapsulated in aId.

This function is used to allow controls to ask their owners for access to other objects that they own.

Other than in the case where NULL is returned, the object returned must be of the same object type - that is, the ETypeId member of the object pointed to by the pointer returned by this function must be equal to the iUid member of aId.

Parameters
aIdAn encapsulated object type ID.
Return Value
Encapsulates the pointer to the object provided. Note that the encapsulated pointer may be NULL.

NotifyFontChange ( const CCoeFontProvider * )

voidNotifyFontChange(const CCoeFontProvider *aFontProvider)

Notify controls that the font has changed

Observer ( )

IMPORT_C MCoeControlObserver *Observer()const

Gets the control's observer.

Return Value
The control's observer.

OfferKeyEventL ( const TKeyEvent &, TEventCode )

IMPORT_C TKeyResponseOfferKeyEventL(const TKeyEvent &aKeyEvent,
TEventCodeaType
)[virtual]

Handles key events.

If a control wishes to process key events, it should implement this function. The implementation must ensure that the function returns EKeyWasNotConsumed if it does not do anything in response to a key event, otherwise, other controls or dialogs may be prevented from receiving the key event. If it is able to process the event it should return EKeyWasConsumed.

When a key event occurs, the control framework calls this function for each control on the control stack, until one of them can process the key event (and returns EKeyWasConsumed).

Each keyboard key press results in three separate events: EEventKeyDown, EEventKey, and EEventKeyUp, in that order.

To receive key events, which can be processed by this function, the application should call CCoeAppUi::AddToStackL() to add the control to the stack. This only applies, however, to controls which are not components of a compound control. Compound controls should pass key events to their components as necessary: the components themselves do not go on the stack.

Classes that override CCoeControl::OfferKeyEventL() should also override the InputCapabilities() virtual function, returning a TCoeInputCapabilities object whose attributes correspond to the behaviour of the OfferKeyEventL() function. Note that it is not necessary to call InputCapabilities() on any component controls from inside a class' InputCapabilities() function. This is done automatically by the UI Control Framework.

If overriding OfferKeyEventL(), the implementation must include a base call to CCoeControl's OfferKeyEventL().

Parameters
aKeyEventThe key event.
aTypeThe type of key event: EEventKey, EEventKeyUp or EEventKeyDown.
Return Value
Indicates whether or not the key event was used by this control.

OverrideColorL ( TInt, TRgb )

IMPORT_C voidOverrideColorL(TIntaLogicalColor,
TRgbaColor
)

Overrides the control's colour setting, as specified in the application's colour scheme.

This function does not change the application's colour scheme. It changes the colour mapping used in this control only.

See also: GetColor()

Parameters
aLogicalColorThe logical colour. Indicates which part of a control the physical colour maps to. The set of logical colours for a standard application are defined in TLogicalColor.
aColorThe new physical colour to which the logical colour should be mapped.

OwnsWindow ( )

IMPORT_C TBoolOwnsWindow()const

Tests if the control is window-owning.

Return Value
ETrue if the control is window-owning. EFalse if the control is non-window-owning.

Parent ( )

IMPORT_C CCoeControl *Parent()

Parent ( )

IMPORT_C const CCoeControl *Parent()const

Position ( )

IMPORT_C TPointPosition()const

Gets the control's position.

Return Value
The position of the control, relative to its associated window.

PositionChanged ( )

IMPORT_C voidPositionChanged()[protected, virtual]

Responds to changes in the position of a control.

It has an empty default implementation which may be overridden by the CCoeControl-derived class.

This function is called whenever the application calls SetPosition() on the control.

PositionRelativeToScreen ( )

IMPORT_C TPointPositionRelativeToScreen()const

Gets the control's position relative to screen origin.

The screen origin is its top-left corner.

Return Value
The position of the control, measured in pixels, relative to the screen origin.

PrepareForFocusGainL ( )

IMPORT_C voidPrepareForFocusGainL()[virtual]

Prepares the control for gaining focus.

Implementations may by taking any action required, such as updating control information. The default implementation is empty.

PrepareForFocusLossL ( )

IMPORT_C voidPrepareForFocusLossL()[virtual]

Prepares the control for loss of focus.

A control which is displayed within a dialog should implement this function if it wishes to validate data entered into the control.

This function is called by the dialog framework immediately before it removes keyboard focus from a control within a dialog. It is intended to be used for validating the state of the control: for example, if the control allows the user to enter a date, PrepareForFocusLossL() would normally check to make sure the user did not enter an invalid date such as February 31st. If an invalid state is detected, PrepareForFocusLossL() should leave and issue a message to the user if appropriate. If it does leave, the framework does not perform the action that would have resulted in the control losing focus, and focus remains with the control to allow valid data to be entered.

In standard GUI dialogs, various actions can result in a control losing focus, for instance if the user presses the OK button or the Enter key to close the dialog and enter the information, or if the user navigates away from the focussed control. These actions result in PrepareForFocusLossL() being called on the control that currently has keyboard focus.

The default implementation of this function is empty, and it is not called from within the UI control framework. The function exists only to provide an interface to the control, for the GUI and any other UI library.

ProcessPointerBufferReadyL ( )

voidProcessPointerBufferReadyL()

ProcessPointerEventL ( const TPointerEvent & )

voidProcessPointerEventL(const TPointerEvent &aPointerEvent)

Rect ( )

IMPORT_C TRectRect()const

Gets the control's extent.

The position of the top-left of the rectangle is (0,0) if the control owns its window. Otherwise, its position is relative to its window.

Return Value
The control's extent.

RecursivelyMergeInputCapabilities ( TCoeInputCapabilities & )

voidRecursivelyMergeInputCapabilities(TCoeInputCapabilities &aInputCapabilities)const

Gets the input capabilities of the control and all its components.

Since
6.0
Return Value
"TCoeInputCapabilities" The input capabilities of the control.

RecursivelyMergedInputCapabilities ( )

IMPORT_C TCoeInputCapabilitiesRecursivelyMergedInputCapabilities()const

Gets the input capabilities of the control and all its components.

Return Value
The input capabilities of the control.

RefetchPixelMappingL ( )

voidRefetchPixelMappingL()

Force all CCoeFontProviders to update their logical-to-pixel mapping from CCoeControlStaticSettings

RemoveFromParent ( )

voidRemoveFromParent()

ReportEventL ( MCoeControlObserver::TCoeEvent )

IMPORT_C voidReportEventL(MCoeControlObserver::TCoeEventaEvent)[protected]

Sends an event to the control's observer (if the control has one).

Parameters
aEventThe event type.

RequestRelayout ( const CCoeControl * )

IMPORT_C TBoolRequestRelayout(const CCoeControl *aChildControl)[virtual]

Requests a relayout

The default implementation is to call the parents RequestRelayout().

Should normally be overridden by top-level controls, such as scrollable containers. Classes that override this function must ensure that they don't cause infinite loops, since a relayout might cause calls to RequestRelayout() itself, This might be solved like this:
TBool CAnyControl::RequestRelayout(const CCoeControl* aChildControl)
	{
	if(iRelayoutInProgress) return EFalse;
	iRelayoutInProgress = ETrue;
	//perform the relayout
	iRelayoutInProgress = EFalse;
	return ETrue;
	}

When the request is addressed the requesting control knows that its SizeChanged() will be called.

Parameters
aChildControlThe child control that requests the relayout, might be NULL
Return Value
ETrue if the request is addressed, otherwise EFalse

ResetGc ( )

IMPORT_C voidResetGc()const [protected]

Resets the standard graphics context.

The function resets the graphics context owned by the control environment to its default settings.

ScreenFont ( const TCoeFont & )

IMPORT_C const CFont &ScreenFont(const TCoeFont &aFont)const [protected]

Returns the closest matching font from the control's current font provider to the requested logical font, taking into account the control's zoom factor.

This function should be used in preference to legacy functions like CEikonEnv::LegendFont(), CCoeEnv::NormalFont() or CCoeEnv::CreateScreenFontL().

Example 1: Instead of the control using a CFont class member, or calling NormalFont(), LegendFont() etc, it is recommended the control (e.g. in its Draw() method) call the new ScreenFont() method to temporarily access a CFont object owned by the font provider. This is a lot more efficient than repeatedly e.g. calling GetNearestFontInPixels(), and allows the CFont object used for text drawing to vary depending on the current zoom factor. Thus the CFont reference must not be kept as class member data, as it may be changed by the font provider at any time.

CSomeControl::Draw(const TRect& aRect)
	{
	XCoeTextDrawer textDrawer(TextDrawer());
	textDrawer.SetAlignment(EHCenterVCenter);
	textDrawer.DrawText(gc, iText, aRect, ScreenFont(TCoeFont::LegendFont());
	}

Example 2: Although efficiently implemented, try not to call ScreenFont() or CCoeFontProvider::Font() repeatedly unnecessarily. Instead, create and use a local const CFont& on the stack, as shown below.

Note that the ScreenFont() call above is provided as short-hand for the code on the first two lines below. Also note that font providers and zoom factors apply hieratically to the control tree (i.e. setting the zoom factor or font provider on a container control affects the child controls too).

CSomeControl::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, aRect, font);
    textDrawer.DrawText(gc, iText2, aRect, font);
    }

See also: CCoeFontProvider TCoeFont

Parameters
aFontLogical font to use.

SetAdjacent ( TInt )

IMPORT_C voidSetAdjacent(TIntaAdjacent)[virtual]

Sets the control's appearance when it is next to other controls.

Its intended use is to remove the double border that may occur if two controls, both with borders, are adjacent within a container control.

This function has an empty default implementation, and is not used within the UI control framework. However, it may be implemented and used by derived control classes.

Parameters
aAdjacentTypically a value defined in TGulAdjacent.

SetAllowStrayPointers ( )

IMPORT_C voidSetAllowStrayPointers()[protected]

Sets whether or not to allow stray pointer events.

This function sets a flag that affects the way the control framework handles pointer events. By default, the flag is not set, and the control will ignore any pointer drag events and up events where the matching pointer down event occurred in a different control. This would happen if a user pressed the pointer down in a control, but then dragged the pointer into a different control before releasing it.

SetAllowStrayPointers() is typically used for menus, where stray pointer events are required because it is the pointer up event that is used to activate a menu option even when the pointer down event occured in a different menu pane. This is not the case in some other components such as command buttons, where a pointer down event and up event in succession are required to activate the button.

SetBackground ( const MCoeControlBackground * )

IMPORT_C voidSetBackground(const MCoeControlBackground *aBackground)

Sets a pointer to a MCoeControlBackground object that is responsible for drawing the control's background

See also: CCoeControl::EnableWindowTransparency()

Parameters
aBackgroundPointer to an object that implements MCoeControlBackground

SetBlank ( )

IMPORT_C voidSetBlank()[protected]

Sets a flag to indicate that the control is blank.

Once set, this flag cannot be unset for the lifetime of the control.

See also: IsBlank()

SetCanDrawOutsideRect ( )

IMPORT_C voidSetCanDrawOutsideRect()[protected]

Allows the control to draw outside its own extent.

When a compound control is drawn, all its component controls are also drawn. However, unless this flag is set, they are not drawn if the rectangle they inhabit on the screen doesn't intersect with the rectangle to be drawn.

Setting this flag has the effect of allowing a component control to draw outside its own extent. It should be used with caution! By default, this flag is not set.

SetComponentsToInheritVisibility ( TBool )

IMPORT_C voidSetComponentsToInheritVisibility(TBoolaInherit = ETrue)

Sets the control's components to inherit the visibility setting of their container control.

If set, when MakeVisible() is called on the compound control, the visibility setting is propagated to all its components.

Parameters
aInheritIf ETrue, the control's components inherit its visibility setting; if EFalse they do not.

SetContainerWindowL ( const CCoeControl & )

IMPORT_C voidSetContainerWindowL(const CCoeControl &aContainer)[virtual]

Sets the control's containing window by copying it from aContainer.

It also copies the control context from aContainer if one has not previously been set.

This function can only be called on non-window-owning (or 'lodger') controls.

If overriding SetContainerWindowL(), the implementation must include a base call to CCoeControl's SetContainerWindowL().

Parameters
aContainerThe compound control that is the container for this control.

SetContainerWindowL ( RWindow & )

IMPORT_C voidSetContainerWindowL(RWindow &aWindow)

Sets the control's containing window, without transferring ownership of the window to this control.

This function can only be called on non-window-owning ('lodger') controls.

Note: the container's window can be accessed using Window(), DrawableWindow(), or BackedUpWindow().

Parameters
aWindowThe window owned by the container control.

SetContainerWindowL ( RBackedUpWindow & )

IMPORT_C voidSetContainerWindowL(RBackedUpWindow &aWindow)

Sets the control's containing window without transferring ownership of the window to this control.

The function can only be called on non-window-owning ('lodger') controls.

Note: the container's window can be accessed using Window(), DrawableWindow(), or BackedUpWindow().

Deprecated

Parameters
aWindowThe backed up window owned by the container control.

SetControlContext ( MCoeControlContext * )

IMPORT_C voidSetControlContext(MCoeControlContext *aContext)

Set the control context for this control.

Parameters
aContextThe context for this control.

SetCornerAndSize ( TGulAlignment, const TSize & )

IMPORT_C voidSetCornerAndSize(TGulAlignmentaCorner,
const TSize &aSize
)[protected]

Sets the control's alignment and size.

The control's position is calculated, relative to the screen, according to the requested alignment.

Note: calling this function results in a call to SizeChanged().

Parameters
aCornerThe alignment of the control.
aSizeThe control's size.

SetCustomGc ( CWindowGc * )

IMPORT_C TIntSetCustomGc(CWindowGc *aGraphicsContext)

Sets the control's custom graphics context. This value overrides the system context for this control and any children.

If aGraphicsContext is null, the control's graphics context is reset to the one it inherited from its parent, or to the default system graphics context (iCoeEnv->SystemGc()) if none of its parents have set their own graphics context.

This value is retrieved by CCoeControl::SystemGc().

SetDimmed ( TBool )

IMPORT_C voidSetDimmed(TBoolaDimmed)[virtual]

Sets the control to be dimmed.

This function sets a flag within the control which indicates whether or not the control is dimmed (greyed out). This is typically used to show that the control is temporarily unavailable.

SetDimmed() does not initiate a redraw of the control. The application should call DrawNow() or DrawDeferred() if a redraw is required after calling SetDimmed(). The control's Draw() function should draw the control appropriately according to whether it is dimmed or not. (This can be enquired using IsDimmed().)

If overriding SetDimmed(), the implementation must include a base call to CCoeControl's SetDimmed().

Parameters
aDimmedETrue to dim the control, EFalse to set the control as not dimmed.

SetExtent ( const TPoint &, const TSize & )

IMPORT_C voidSetExtent(const TPoint &aPosition,
const TSize &aSize
)

Sets the control's extent, specifying a size and a position.

Note: calling this function results in a call to SizeChanged().

Parameters
aPositionThe position of the control, relative to its associated window.
aSizeThe size of the control, in pixels.

SetExtentToWholeScreen ( )

IMPORT_C voidSetExtentToWholeScreen()

Sets the control's extent to the whole screen.

Note: calling this function results in a call to SizeChanged().

SetFocus ( TBool, TDrawNow )

IMPORT_C voidSetFocus(TBoolaFocus,
TDrawNowaDrawNow = ENoDrawNow
)

Sets this control to have the keyboard focus.

It sets the value of a focus flag within the control to the value given by aFocus. This flag indicates whether or not the control has keyboard focus, and its value can be enquired using IsFocused(). It then calls FocusChanged(), passing it the value given by aDrawNow, unless the control is invisible or not activated, in which case it passes ENoDrawNow.

Note that setting focus does not initiate a redraw. The control's implementation of FocusChanged() should do this if required. The control's Draw() function, or that of its container, should normally change the appearance of the control to indicate whether or not it currently has focus.

Parameters
aFocusETrue sets the control as having keyboard focus, EFalse sets it as not having keyboard focus.
aDrawNowFlag to pass to FocusChanged().

SetFocusing ( TBool )

IMPORT_C voidSetFocusing(TBoolaFocusing)

Sets the control as able to receive keyboard focus.

Parameters
aFocusingETrue if the control can have focus, EFalse if it can't.

SetFontProviderL ( const CCoeFontProvider & )

IMPORT_C voidSetFontProviderL(const CCoeFontProvider &aFontProvider)

Set the font provider. This is an external object that takes the responsibililty for finding an appropriate font away from the control.

Parameters
aFontProviderThe provider to use.

SetGc ( CWindowGc * )

TInt SetGc(CWindowGc *aGraphicsContext)const [inline]

Deprecated. See DeprecatedCCoeControl::SetCustomGc().

SetGloballyCapturing ( TBool )

IMPORT_C voidSetGloballyCapturing(TBoolaGlobal)

Sets the global pointer capture flag.

This flag indicates whether or not pointer capture should be global.

The flag is used by SetPointerCapture() to determine what value to pass to RWindowBase::SetPointerCapture(). The default for the global capture flag, when a control is created, is EFalse.

Parameters
aGlobalValue for global capture flag.

SetHitTest ( const MCoeControlHitTest * )

IMPORT_C TIntSetHitTest(const MCoeControlHitTest *aHitTestControl)

Installs a hit tester for this control. The tester defines the hit region, which is the area within the control that accepts pointer events. If no hit region is set, pointer events are accepted in the control's entire rectangle.

Parameters
aHitTestControlObject which defines the hit region.
Return Value
KErrNone if successful, or another system error code.

SetLayoutManagerL ( MCoeLayoutManager * )

IMPORT_C voidSetLayoutManagerL(MCoeLayoutManager *aLayout)[virtual]

Sets the layout manager

If the control already has a layout manager, its MCoeLayoutManager::Detatch() is called. MCoeLayoutManager::Attach() is called on aLayout

The control doesn't take ownership of the Layout manager.

See also: MCoeLayoutManager::Attach

Parameters
aLayoutThe new layout manager, NULL if you just want to remove the current layout manager.

SetMaximumWidth ( TInt )

IMPORT_C TIntSetMaximumWidth(TIntaMaxWidth)

Sets the controls maximum width.

Parameters
aMaxWidthThe control's maximum width.
Return Value
Error Code. (KErrNone if max width was set successfully)

SetMopParent ( MObjectProvider * )

IMPORT_C voidSetMopParent(MObjectProvider *aParent)

Sets the context - that is, the enclosing parent control - for this control. If setting aParent as MopParent of this control creates a cyclic relationship, this method will do nothing.

Parameters
aParentThe parent object which is the context for the control.

SetNeighbor ( CCoeControl * )

IMPORT_C voidSetNeighbor(CCoeControl *aNeighbor)[virtual]

Sets an associated control.

This can be used to establish co-ordinated groups of controls for instance in dialogs without specific application co-operation.

This function has an empty default implementation, and is not used within the UI control framework. However, it may be implemented and used by derived control classes.

Parameters
aNeighborA control to be used by this function.

SetNonFocusing ( )

IMPORT_C voidSetNonFocusing()

Deprecated. Use SetFocusing().

Sets the control as unable to receive keyboard focus. The function would typically be called during construction of the control.

SetObserver ( MCoeControlObserver * )

IMPORT_C voidSetObserver(MCoeControlObserver *aObserver)

Sets the control's observer.

Parameters
aObserverThe observer.

SetParent ( CCoeControl * )

IMPORT_C TIntSetParent(CCoeControl *aParent)[virtual]

Sets aParent as the parent of this control. If setting aParent as parent of this control will create a cyclic relationship, this method does nothing.

Parameters
aParentThe control to set as this control's parent.
Return Value
KErrNone if successful, otherwise another of the system error codes.

SetPointerCapture ( TBool )

IMPORT_C voidSetPointerCapture(TBoolaCapture = ETrue)

Sets pointer capture.

Once set, pointer capture lasts until SetPointerCapture() is called on the control with aCapture=EFalse.

This function is typically used by dialogs, to discard any pointer events that occur outside of the dialog.

See also: RWindowBase::SetPointerCapture()

Parameters
aCaptureIf ETrue, passes the following value as the argument to RWindowBase::SetPointerCapture(): RWindowBase::TCaptureFlagAllGroups|RWindowBase::TCaptureFlagEnabled, if the control's global capture flag is set to ETrue (see SetGloballyCapturing()) or RWindowBase::TCaptureFlagEnabled if the control's global capture flag is set to EFalse. If EFalse, passes EFalse as the argument to RWindowBase::SetPointerCapture().

SetPosition ( const TPoint & )

IMPORT_C voidSetPosition(const TPoint &aPosition)

Sets the control's position.

If the control owns its containing window, it achieves this by setting the position of the window. Otherwise, the position of the control is set relative to its containing window. The positions of the control's components are adjusted accordingly and PositionChanged() is called.

Parameters
aPositionThe position of the the top-left of the control, relative to its associated window.

SetRect ( const TRect & )

IMPORT_C voidSetRect(const TRect &aRect)

Sets the control's extent, specifying a rectangle.

Note: calling this function results in a call to SizeChanged().

Parameters
aRectThe rectangle that defines the control's extent. The rectangle's origin is relative to the origin of its associated window.

SetSize ( const TSize & )

IMPORT_C voidSetSize(const TSize &aSize)

Sets the control's size.

If the size, but not the position, of a control is set, then its position will default to TPoint(0,0).

Note: calling this function results in a call to SizeChanged().

Parameters
aSizeThe control's size, in pixels.

SetSizeWithoutNotification ( const TSize & )

IMPORT_C voidSetSizeWithoutNotification(const TSize &aSize)[protected]

Sets a control's size without calling SizeChanged().

If the size, but not the position, of a control is set, then its position will default to TPoint(0,0).

See also: SetSize()

Parameters
aSizeThe control's size, in pixels.

SetTextBaselineSpacing ( TInt )

IMPORT_C voidSetTextBaselineSpacing(TIntaSpacing)[virtual]

Sets the spacing between text baselines.

The default implementation calls SetTextBaselineSpacing of the layout manager if one is installed. It does nothing if there is no layout manager.

Derived classes that don't want to use the layout manager and still want to do something when the this function is called should re-implement it.

Parameters
aSpacingThe baseline spacing i.e. the space in pixels between the text baselines.

SetUniqueHandle ( TInt )

IMPORT_C TIntSetUniqueHandle(TIntaUniqueHandle)

Sets a Unique Handle (identifier). That the number is unique is the perogative of the caller!

See also: UniqueHandle()

Return Value
Standard error code

SetZoomFactorL ( TInt, TZoomType )

IMPORT_C voidSetZoomFactorL(TIntaZoomFactor,
TZoomTypeaZoomType = ERelativeZoom
)

Set the zoom factor for this control.

Parameters
aZoomFactorAmount of zoom (multiplied by 1000)
aZoomTypeAbsolute or relative (EAbsoluteZoom or ERelativeZoom)

Size ( )

IMPORT_C TSizeSize()const

Gets the control's size.

Return Value
The control's size, in pixels.

SizeChanged ( )

IMPORT_C voidSizeChanged()[protected, virtual]

Responds to changes to the size and position of the contents of this control.

For a simple control this might include text or graphics. For a compound control it sets the size and position of the components.

The function is called whenever SetExtent(), SetSize(), SetRect(), SetCornerAndSize(), or SetExtentToWholeScreen() are called on the control. Note that the window server does not generate size-changed events: SizeChanged() gets called only as a result of calling the functions listed above. Therefore, if a resize of one control affects the size of other controls, it is up to the application to ensure that it handles the re-sizing of all affected controls.

SystemGc ( )

IMPORT_C CWindowGc &SystemGc()const

Gets the graphics context that is used when drawing the control.

This function walks the CCoeControl hierarchy upwards from child to parent until a context is found. If no control in the hierarchy has defined its own graphics context, the default system graphics context (iCoeEnv->SystemGc()) is returned.

All drawing is carried out through a graphics context. A graphics context must be activated before it can be drawn to, and deactivated when it is no longer needed. When drawing is done using Draw(), DrawNow() or DrawDeferred(), the application does not have to do this, as it is done within the control framework. However, for application-initiated drawing which is not done using DrawNow() or DrawDeferred(), the application should activate and deactivate the graphics context using ActivateGc() and DeactivateGc() (or CWindowGc::Activate() and CWindowGc::Deactivate()).

Return Value
The system graphics context.

TextBaselineOffset ( const TSize & )

IMPORT_C TIntTextBaselineOffset(const TSize &aSize)const [virtual]

Gets the offset to the first text baseline relative to the top of the control.

The default implementation calls CalcTextBaselineOffset of the layout manager if one is installed. It returns 0 if no layout manager is installed.

Derived classes that don't want to use the layout manager and still want to return a baseline offset should re-implement this function.

Return Value
The offset of the baseline from the top of the control.

TextDrawer ( TInt )

IMPORT_C CCoeTextDrawerBase &TextDrawer(TIntaKey =  KErrNotFound )const [protected]

Gets the text drawer to be used for the control. This method returns a reference simply because the return value must never be NULL. The ownership transfer rules of the returned CCoeTextDrawerBase object obey specific rules. If the CCoeTextDrawerBase::IsReusable() flag is set then the caller must call Reset when the object is not needed anymore else it should simply delete the object. The XCoeTextDrawer class is a wrapper around the CCoeTextDrawerBase that will implement this logic automatically. The method will start with the default text drawer. It then allows the childs background control to change the text drawer if the child itself is window owning. Otherwise only the parent control can change the text drawer.

Parameters
aKeyThis parameter can be used by clients that need some custom behaviour. The framework doesn't use this parameter.
Return Value
reference to a CCoeTextDrawerBase object

UniqueHandle ( )

IMPORT_C TIntUniqueHandle()const

Returns a Unique Handle (identifier) previously allocated to the control.

See also: SetUniqueHandle

Return Value
Previously allocated value.

Window ( )

IMPORT_C RWindow &Window()const [protected]

Gets the control's associated window.

The control must be window owning, and the window must be of type RWindow. If you don't know whether the window is of type RWindow or RBackedUpWindow, you should use DrawableWindow().

Return Value
The control's associated window, cast to an RWindow.

WriteInternalStateL ( RWriteStream & )

IMPORT_C voidWriteInternalStateL(RWriteStream &aWriteStream)const [protected, virtual]

WriteInternalStateNowL ( RWriteStream & )

voidWriteInternalStateNowL(RWriteStream &aWriteStream)const

ZoomWithType ( )

IMPORT_C const TCoeZoomWithType *ZoomWithType()const

Return the zoom factor but without taking into account the zoom factor of the parent. Use of AccumulatedZoom() is recommended as it takes into account the zoom factor of the parent.

operator= ( const CCoeControl & )

CCoeControl &operator=(const CCoeControl &aControl)[protected, inline]