![[Index]](../../../stock/btn_index.gif){kind=small}
![[Glossary]](../../../stock/btn_glossary.gif){kind=small}
![[Previous]](../../../stock/btn_prev.gif){kind=small}
![[Next]](../../../stock/btn_next.gif){kind=small}
| |
|
| |
Location:
coecntrl.h
Link against: cone.lib
CCoeControl
Supported from 5.0
Control base class from which all other controls are derived.
Note:
In ER5u only, this class derived additionally from
MCoeInputObserver.
|
Defined in CCoeControl:
ActivateGc(), ActivateL(), BackedUpWindow(), CCoeControl(), CapturesPointer(), ClaimPointerGrab(), CloseWindow(), ComponentControl(), ConstructFromResourceL(), ControlContext(), ControlEnv(), CopyControlContextFrom(), CountComponentControls(), CreateBackedUpWindowL(), CreateWindowL(), DeactivateGc(), Draw(), DrawDeferred(), DrawNow(), DrawableWindow(), EnableDragEvents(), FocusChanged(), GetColor(), GetColorUseListL(), GetHelpContext(), GrabbingComponent(), HandleComponentControlsResourceChange(), HandlePointerBufferReadyL(), HandlePointerEventL(), HandleRedrawEvent(), HandleResourceChange(), HasBorder(), IgnoreEventsUntilNextPointerUp(), Index(), InputCapabilities(), IsActivated(), IsBackedUp(), IsBeingDestroyed(), IsBlank(), IsDimmed(), IsFocused(), IsNonFocusing(), IsReadyToDraw(), IsVisible(), MakeVisible(), MinimumSize(), Observer(), OfferKeyEventL(), OverrideColorL(), OwnsWindow(), Position(), PositionChanged(), PositionRelativeToScreen(), PrepareForFocusGainL(), PrepareForFocusLossL(), Rect(), RecursivelyMergedInputCapabilities(), ReportEventL(), ResetGc(), SetAdjacent(), SetAllowStrayPointers(), SetBlank(), SetCanDrawOutsideRect(), SetComponentsToInheritVisibility(), SetContainerWindow(), SetContainerWindowL(), SetControlContext(), SetCornerAndSize(), SetCornerAndSizeL(), SetDimmed(), SetExtent(), SetExtentL(), SetExtentToWholeScreen(), SetExtentToWholeScreenL(), SetFocus(), SetFocusing(), SetGloballyCapturing(), SetNeighbor(), SetNonFocusing(), SetObserver(), SetPointerCapture(), SetPosition(), SetRect(), SetRectL(), SetSize(), SetSizeL(), SetSizeWithoutNotification(), SetSizeWithoutNotificationL(), Size(), SizeChanged(), SizeChangedL(), SystemGc(), Window(), ~CCoeControl()
Inherited from CBase:
operator new()
CCoeControl();
Default C++ constructor.
This function performs initialisation of the
CCoeControl base class.
Note:
The CCoeControl class is normally used as a
base class from which concrete control classes are derived. However, it can
also be instantiated as a concrete class: CEikMsgWin provides an
example of this.
virtual void ConstructFromResourceL(TResourceReader& aReader);
Constructs controls 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 using
aReader.
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().
|
TBool IsBeingDestroyed() const;
Supported from 6.0
Tests if the control is being destroyed.
|
~CCoeControl();
Destructor.
It destroys the window owned by the control, if it is a window-owning control.
From version 6.1, the destructor in debug builds checks if the control exists in the control stack and gives a CONE 44 panic if it is still there. An application must remove every control that it adds to the stack.
|
A compound control is one which contains one or more simple or compound controls. Compound controls are also known as container controls, and may be window-owning or non-window-owning.
virtual TInt CountComponentControls() const;
Gets the number of controls contained in a compound control.
This function should be implemented by all compound controls.
Note:
In 6.1 this was changed from protected to public.
|
protected: virtual CCoeControl* ComponentControl(TInt aIndex) const;
Gets the specified component of a compound control.
This function should be implemented by all compound controls.
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.
|
|
void SetContainerWindow(RWindow& aWindow);
Withdrawn in 5.1
Sets a component control's container window — if the container is a window-owning control.
This function sets the control's associated window to be the same as the container's associated window.
The function can only be called on non-window-owning controls.
Note:
The container's window can be accessed using
Window(), DrawableWindow(), or
BackedUpWindow().
This function is replaced by a leaving version after ER5:
SetContainerWindowL().
|
|
void SetContainerWindowL(RWindow& aWindow);
Supported from 5.1
Sets a component control's container window — if the container is a window-owning control.
This function sets the control's associated window to be the same as the container's associated window. The function can only be called on non-window-owning controls.
Note:
The container's window can be accessed using
Window(), DrawableWindow(), or
BackedUpWindow().
This function replaces SetContainerWindow()
used in ER5.
|
|
void SetContainerWindow(RBackedUpWindow& aWindow);
Withdrawn in 5.1
Sets a component control's container window — if the container is a backed up window owning control.
This function sets the control's associated window to be the same as the container's associated window.
The function can only be called on non-window-owning controls.
Note:
The container's window can be accessed using
Window(), DrawableWindow(), or
BackedUpWindow().
This function is replaced by a leaving version after ER5:
SetContainerWindowL().
|
|
SetContainerWindowL(RBackedUpWindow& aWindow);
Sets a component control's container window — if the container is a backed up window owning control.
Sets a component control's container as a. This function sets the control's associated window to be the same as the container's associated window.
The function can only be called on non-window-owning controls.
Note:
The container's window can be accessed using
Window(), DrawableWindow(), or
BackedUpWindow().
This function replaces SetContainerWindow()
used in ER5.
|
|
virtual void SetContainerWindowL(const CCoeControl& aContainer);
Sets a component control's container — leaving.
It does this by setting the control's associated window to be the same as the container's associated window.
This function can only be called on non-window-owning controls.
Note:
If the container is a window-owning control, you can
alternatively use SetContainerWindow().
|
|
TInt Index(const CCoeControl* aControl) const;
Gets the index of a control that is a component of this control.
|
|
virtual void SetAdjacent(TInt aAdjacent);
Sets control's appearance when 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: for example it is implemented and used by the standard GUI.
|
virtual void SetNeighbor(CCoeControl* aNeighbor);
Sets associated control.
This can be used to establish co-ordinated groups of controls (e.g. 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: for example it is implemented and used by the standard GUI.
|
virtual TBool HasBorder() const;
Tests if a control has a border.
When component controls are arranged in a container, the container control may need to know whether or not the component have borders, as this may affect the way the components are laid out within the container.
The default implementation of this function always returns
EFalse, but can be overridden to provide the required
functionality. The GUI implements and uses this function in several of its
concrete controls.
|
|
protected: void CreateWindowL();
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.
protected: void CreateWindowL(const CCoeControl* aParent);
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 first overload should be used.
|
protected: void CreateWindowL(RWindowTreeNode& aParent);
Creates a control's window — specifying its parent 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 first overload should be used.
|
protected: void CreateWindowL(RWindowGroup* aParent);
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 first overload should be used.
|
TBool OwnsWindow() const;
Tests if the control is window-owning.
|
protected: RWindow& Window() const;
Get 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().
|
RDrawableWindow* DrawableWindow() const;
Get 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.
|
protected: void CreateBackedUpWindowL(RWindowTreeNode& aParent);
Create 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.
|
protected: void CreateBackedUpWindowL(RWindowTreeNode& aParent,TDisplayMode aDisplayMode);
Create a control's window as a backed-up window, specifying the display mode.
The new window is the child of aParent and the
display mode of the control is set to aDisplayMode.
|
TBool IsBackedUp() const;
Tests if the window owned by the control is a backed-up window.
|
protected: RBackedUpWindow& BackedUpWindow() const;
Gets the backed-up window owned by 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().
|
protected: void SetBlank();
Sets a flag to indicate the control is blank.
Once set, this flag cannot be unset for the lifetime of the control.
protected: TBool IsBlank() const;
Tests if the control is a blank.
This simply gets the value of the flag set by
SetBlank().
|
protected: void CloseWindow();
Closes window owned by this control.
It is called from CCoeControl's destructor for
window-owning controls.
|
A control's origin is its top-left corner. The position of a control is specified relative to the origin of its associated window.
void SetExtentL(const TPoint& aPosition,const TSize& aSize);
Withdrawn in 5.1
Sets the control's extent — specifying size and position.
Note:
Calling this function results in a call to
SizeChangedL().
This function is replaced by a non-leaving variant after
ER5: SetExtent().
|
void SetExtent(const TPoint& aPosition,const TSize& aSize);
Supported from 5.1
Sets the control's extent — specifying size and position.
Note:
Calling this function results in a call to
SizeChanged().
This function replaces the ER5 function:
SetExtentL().
|
void SetRectL(const TRect& aRect);
Withdrawn in 5.1
Sets the control's extent — specifying a
TRect.
Note:
Calling this function results in a call to
SizeChangedL().
This function is replaced by a non-leaving variant after
ER5: SetRect().
|
void SetRect(const TRect& aRect);
Supported from 5.1
Sets the control's extent — specifying a
TRect.
Note:
Calling this function results in a call to
SizeChanged().
This function replaces the ER5 function:
SetRectL().
|
void SetSizeL(const TSize& aSize);
Withdrawn in 5.1
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
SizeChangedL().
This function is replaced by a non-leaving variant after
ER5: SetSize().
|
void SetSize(const TSize& aSize);
Supported from 5.1
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().
This function replaces the ER5 function:
SetSizeL().
|
protected: void SetSizeWithoutNotificationL(const TSize& aSize);
Withdrawn in 5.1
Sets a control's size without calling
SizeChangedL().
If the size, but not the position, of a control is set, then
its position will default to TPoint(0,0).
Note:
This function is replaced by a non-leaving variant after
ER5: SetSizeWithoutNotification().
|
protected: void SetSizeWithoutNotification(const TSize& aSize);
Supported from 5.1
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).
Note:
This function replaces the ER5 function:
SetSizeWithoutNotificationL().
|
TSize Size() const;
Gets the control's size.
|
void SetPosition(const TPoint& aPosition);
Sets the control's position.
|
TPoint Position() const;
Gets the control's position.
|
TPoint PositionRelativeToScreen() const;
Gets the control's position relative to screen origin.
The screen origin is its top-left corner.
|
void SetExtentToWholeScreenL();
Withdrawn in 5.1
Sets the control's extent to the whole screen.
Note:
Calling this function results in a call to
SizeChangedL().
This function is replaced by a non-leaving variant after
ER5: SetExtentToWholeScreen().
void SetExtentToWholeScreen();
Supported from 5.1
Sets the control's extent to the whole screen.
Note:
Calling this function results in a call to
SizeChanged().
This function replaces the ER5 function:
SetExtentToWholeScreenL().
protected: void SetCornerAndSizeL(TCoeAlignment aCorner,const TSize& aSize);
Withdrawn in 5.1
Sets the control's position by setting its screen 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
SizeChangedL().
This function is replaced by a non-leaving variant after
ER5: SetCornerAndSize().
|
protected: void SetCornerAndSize(TCoeAlignment aCorner,const TSize& aSize);
Supported from 5.1
Sets the control's position by setting its screen 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().
This function replaces the ER5 function:
SetCornerAndSizeL().
|
virtual TSize MinimumSize();
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 inquire the minimum size that a control requires.
Other container controls that automatically calculate the layout of their components may also use this function.
|
protected: virtual void SizeChangedL();
Withdrawn in 5.1
Responds to size changes to sets the size and position of the contents of this control.
For a simple control this might include text or graphics. For a
compound control this sets the size and position of the component. It has an
empty default implementation and should be implemented by the
CCoeControl-derived class.
The function is called whenever SetExtentL(),
SetSizeL(), SetRectL(),
SetCornerAndSizeL(), or SetExtentToWholeScreenL() are
called on the control. Note that the window server does not generate
size-changed events: SizeChangedL() 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.
Note:
This function is replaced by a non-leaving variant after
ER5: SizeChanged().
protected: virtual void SizeChanged();
Supported from 5.1
Responds to size changes to sets the size and position of the contents of this control.
For a simple control this might include text or graphics. For a
compound control this sets the size and position of the component. It has an
empty default implementation and should be implemented by the
CCoeControl-derived class.
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.
Note:
This function replaces the ER5 function:
SizeChangedL().
protected: virtual void PositionChanged();
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 by whenever the application calls
SetPosition() on the control.
|
virtual void ActivateL();
Sets 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 draw 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, CEikEdwin overrides
ActivateL() and uses it to inquire if the edit window is focused:
if it is, it highlights the text and makes the cursor visible. At the time when
the edit window is created, it doesn't know whether or not it has keyboard
focus.
protected: TBool IsActivated() const;
Tests if the control has been activated.
A control is not ready to draw until it is activated.
|
protected: TBool IsReadyToDraw() const;
Tests if the control is ready for drawing.
This returns true if the control has been activated and is visible.
|
|
private: virtual void Draw(const TRect& aRect) const;
Draw a control — called by window server.
All controls, except blank controls, should implement this function. The default implementation draws a blank control.
This function is used for window server-initiated redrawing of
controls, and for some application-initiated drawing. It should be implemented
by each control, but is only called from within CCoeControl's
member functions, and not from the derived class. For this reason it is a
private member function of CCoeControl.
The rectangle aRect indicates the region of the
control that needs to be redrawn. The implementation of Draw()must
always draw to every pixel within this rectangle.
Notes:
For non-window-owning controls, care must be taken not to draw outside the control, as drawing will not be clipped to the control. Drawing is clipped to window-owning-controls, but not to non-window-owning controls.
Drawing outside aRect may cause
flicker.
Drawing should be done using a graphics context
(CWindowGc), which can be obtained using
SystemGc().
|
void DrawNow() const;
Draws a control — 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 DrawNow() should
not be used.
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).
void DrawDeferred() const;
Draws the control with low priority — called by application
This function 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 superseded. If you make multiple calls to
DrawNow(), however, all of them get processed, even if they have
already been superseded by the time they are processed.
protected: void SetCanDrawOutsideRect();
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.
TBool GetColor(TInt aLogicalColor,TRgb& aColor) const;
Gets the over-ridden 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.
|
|
void OverrideColorL(TInt aLogicalColor,TRgb aColor);
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.
|
|
virtual void GetColorUseListL(CArrayFix<TCoeColorUse>& aColorUseList) const;
Supported from 5.1
Gets the list of logical colours used to draw the control.
The list includes an explanation of how each colour is used. By default, this function has an empty implementation.
|
|
protected: CWindowGc& SystemGc() const;
Gets the standard graphics context for use when drawing controls.
All graphics functions are carried out through a graphics context.
Note:
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 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()).
|
protected: void ActivateGc() const;
Activates the standard graphics context.
This is the graphics context owned by the control environment
(CCoeEnv).
Applications should not normally need to call this function, as
it is called within the control framework whenever it is about to call
Draw().
protected: void ResetGc() const;
Resets the standard graphics context.
The function resets the graphics context owned by the control environment to its default settings.
protected: void DeactivateGc() const;
Deactivates the standard graphics context owned by the UI control framework.
Applications should not normally need to call this function, as
it is called within control framework whenever it has called
Draw() and drawing is completed.
|
Control contexts allow a group of controls to share a common set of graphics context settings, and hence a common appearance.
void SetControlContext(MCoeControlContext* aContext);
Set the control context for this control.
|
void CopyControlContextFrom(const CCoeControl* aControl);
Sets the control's context from another control.
|
|
virtual void MakeVisible(TBool aVisible);
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 of after the
control is activated.
Note:
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.
|
TBool IsVisible() const;
Tests if the control is visible.
Unless MakeVisible() has been called with argument
EFalse, the control is visible.
|
void SetComponentsToInheritVisibility(TBool aInherit=ETrue);
Sets components to inherit visibility setting from their container control.
If set, when MakeVisible() is called on the
compound control, the value for visibility is propagated to all its
components.
|
|
virtual void SetDimmed(TBool aDimmed);
Sets control 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 action performed by 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 inquired using IsDimmed().)
|
TBool IsDimmed() const;
Tests if control is dimmed.
This function returns the value of a flag within the control
which is set and unset using SetDimmed().
|
|
void SetFocus(TBool aFocus,TDrawNow aDrawNow=ENoDrawNow);
Sets that the control has keyboard focus.
The function 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 inquired 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.
|
virtual void PrepareForFocusLossL();
Prepare for focus loss.
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, two actions result in a control losing
focus: one is when the user presses the OK button or the Enter key, to close
the dialog and enter the information, and the second is when the user presses
the up or down arrow keys to change the keyboard focus within the dialog. All
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.
virtual void PrepareForFocusGainL();
Supported from 6.0
Prepares the control for gaining focus.
Implementations may by taking any action required, such as updating control information. By default, the implementation is empty.
protected: virtual void FocusChanged(TDrawNow aDrawNow);
Responds to focus changed.
This function is called whenever a 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 to
indicate whether or not it has focus, for example by drawing a focus rectangle
around it.
The default implementation is empty, and should be overridden
by the CCoeControl-derived class.
|
TBool IsFocused() const;
Tests if the control has focus.
Focus is set and unset using SetFocus().
|
void SetNonFocusing();
Deprecated. Use SetFocusing().
Sets the control as unable to receive keyboard focus. The function would typically be called during construction of the control.
void SetFocusing(TBool aFocusing);
Sets the control as able to receive keyboard focus.
The function would typically be called after construction of the control.
|
TBool IsNonFocusing() const;
Tests if the control can receive focus.
|
|
The functions grouped below handle key and pointer events and sending events to another control.
virtual TKeyResponse OfferKeyEventL(const TKeyEvent& aKeyEvent,TEventCode aType);
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).
|
|
![[Top]](../../../stock/arrow_up_2.gif){kind=icon}
EEventKeyDown, EEventKey, and
EEventKeyUp, in that order. 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.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.protected: virtual void HandlePointerEventL(const TPointerEvent& aPointerEvent);
Handles pointer events.
This function gets called whenever a pointer event occurs in the control, i.e. with the pointer within the control's extent, or when the control has grabbed the pointer. The control should implement this function to handle pointer events.
Note:
Events of type EButton1Down are processed
before HandlePointerEventL() is called, in order to transfer
keyboard focus to the control in which the EButton1Down event
occurred.
|
protected: void SetAllowStrayPointers();
Set 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 is it the pointer up
event that is used to activate a menu option. This is in contrast to other
components such as command buttons, where a pointer down event and up event in
succession are required to activate the button.
protected: void EnableDragEvents();
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 events and pointer 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.
protected: virtual void HandlePointerBufferReadyL();
Handle events in pointer buffer.
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.
protected: void HandleRedrawEvent(const TRect& aRect) const;
Handles redraw event.
In normal circumstances this function should not be used or overridden by the derived control class.
|
TCoeInputCapabilities InputCapabilities() const;
Supported from 5.1
Gets the control's input capabilities.
|
CCoeControl::OfferKeyEventL() should also override the
InputCapabilities() virtual function, returning a
TCoeInputCapabilities object whose attributes correspond to the
behaviour of the OfferKeyEventL() function.InputCapabilities() on any component controls
from inside a class' InputCapabilities() function — this is done
automatically by the UI Control Framework.TCoeInputCapabilities RecursivelyMergedInputCapabilities() const;
Supported from 6.0
Gets the input capabilities of the control and all its components.
|
|
virtual void HandleResourceChange(TInt aType);
Supported from 5.1
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.
|
void HandleComponentControlsResourceChange(TInt aType);
Supported from 5.1
Handles a change to the resources in the components of a compound control.
|
|
This is implemented within control framework and does not have to be implemented by the derived control class.
In the UI control framework, when a pointer event of type
EButton1Down occurs in a control, the control grabs the pointer
until the next event of type EButton1Up. This means, all pointer
events are delivered to this control between (and inclusive of) the
EButton1Down and EButton1Up events, regardless of
which control the event occurs in. (If the control is invisible or dimmed,
however, it does not grab the pointer.)
void ClaimPointerGrab(TBool aSendUpEvent=ETrue);
Claims 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.
|
protected: CCoeControl* GrabbingComponent() const;
Gets the component control which is grabbing the pointer.
|
|
void SetPointerCapture(TBool aCapture=ETrue);
Set pointer capture.
Once set, pointer capture lasts until
SetPointerCapture() is called on the control with
aCapture=EFalse.
This function is typically used with dialogs, to throw away any pointer events that don't occur within the dialog, or with menus, to dismiss the menu if the user clicks outside it.
|
void SetGloballyCapturing(TBool aGlobal);
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.
|
protected: TBool CapturesPointer() const;
Tests if pointer capture is set for the control.
This returns true if SetPointerCapture() has been
called with aCapture=ETrue.
|
void IgnoreEventsUntilNextPointerUp();
Sets control to ignore pointer events until next pointer up.
This means that all events until and including the next pointer up event get thrown away and are not processed.
|
MCoeControlObserver defines a protocol for passing
events between controls: events are sent using
CCoeControl::ReportEventL(), and handled by the observer control
using MCoeControlObserver::HandleControlEventL().
MCoeControlObserver also defines a set of event types that can be
passed between controls: these are not the same as the user input events that
are generated by the window server.
A control can send events to another control by making that
control its observer. To do this, the observer control must be derived from
MCoeControlObserver, and must be set as the control's observer by
calling SetObserver().
void SetObserver(MCoeControlObserver* aObserver);
Sets the control's observer.
|
MCoeControlObserver* Observer() const;
Gets the control's observer.
|
protected: void ReportEventL(MCoeControlObserver::TCoeEvent aEvent);
Sends an event to the control's observer.
|
|
CCoeEnv* ControlEnv() const;
Gets the control environment object for this control.
|
virtual void GetHelpContext(TCoeHelpContext& aContext) const;
Supported from 5.1
Gets the control's help context. Returns a NULL context by default.
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.
|
MCoeControlContext* ControlContext() const;
Supported from 6.0
Gets the control context being used by this control.
The function does not transfer ownership to the caller.
|
Copyright ©2002 Symbian Ltd. 6.1-00174 |
|
![[Top]](../../../stock/arrow_up.gif){kind=icon}