![[Index]](../../../../_stock/btn_index_wt.gif){kind=small}
![[Spacer]](../../../../_stock/btn_spacer.gif){kind=small}
![[Previous]](../../../../_stock/btn_prev_wt.gif){kind=small}
![[Next]](../../../../_stock/btn_next_wt.gif){kind=small}
|
|
|
|
|
|
Location:
COECNTRL.H
Link against: cone.lib
class CCoeControl : public CBase, public MObjectProvider;
Control base class from which all other controls are derived.
MObjectProvider - An interface that allows an object to be part of a network of object providersCBase - Base class for all classes to be instantiated on the heapCCoeControl - Control base class from which all other controls are derivedDefined in CCoeControl:
AccumulatedZoom(), ActivateGc(), ActivateL(), BackedUpWindow(), Background(), CCoeControl(), CCoeControl(), CapturesPointer(), ClaimPointerGrab(), CloseWindow(), ComponentArrayExists(), ComponentControl(), Components(), Components(), ConstructFromResourceL(), ControlContext(), ControlEnv(), CopyControlContextFrom(), CountComponentControls(), CreateBackedUpWindowL(), CreateBackedUpWindowL(), CreateWindowL(), CreateWindowL(), CreateWindowL(), CreateWindowL(), DeactivateGc(), Draw(), DrawBackground(), DrawDeferred(), DrawForeground(), DrawNow(), DrawNow(), DrawableWindow(), EAbsoluteZoom, ERelativeZoom, EnableDragEvents(), FindBackground(), FindFontProvider(), FocusChanged(), GetColor(), GetColorUseListL(), GetGc(), GetHelpContext(), GetTextDrawer(), GrabbingComponent(), HandleComponentControlsResourceChange(), HandleControlArrayEventL(), HandlePointerBufferReadyL(), HandlePointerEventL(), HandleRedrawEvent(), HandleResourceChange(), HasBorder(), HitTest(), IgnoreEventsUntilNextPointerUp(), Index(), InitComponentArrayL(), InputCapabilities(), IsActivated(), IsBackedUp(), IsBeingDestroyed(), IsBlank(), IsDimmed(), IsFocused(), IsNonFocusing(), IsReadyToDraw(), IsVisible(), LayoutManager(), MakeVisible(), MaximumWidth(), MinimumSize(), MopNext(), MopSupplyObject(), Observer(), OfferKeyEventL(), OverrideColorL(), OwnsWindow(), Parent(), Parent(), Position(), PositionChanged(), PositionRelativeToScreen(), PrepareForFocusGainL(), PrepareForFocusLossL(), Rect(), RecursivelyMergedInputCapabilities(), ReportEventL(), RequestRelayout(), Reserved_2(), ResetGc(), ScreenFont(), SetAdjacent(), SetAllowStrayPointers(), SetBackground(), SetBlank(), SetCanDrawOutsideRect(), SetComponentsToInheritVisibility(), SetContainerWindowL(), SetContainerWindowL(), SetContainerWindowL(), SetControlContext(), SetCornerAndSize(), SetDimmed(), SetExtent(), SetExtentToWholeScreen(), SetFocus(), SetFocusing(), SetFontProviderL(), SetGc(), SetGloballyCapturing(), SetHitTest(), SetLayoutManagerL(), SetMaximumWidth(), SetMopParent(), SetNeighbor(), SetNonFocusing(), SetObserver(), SetParent(), SetPointerCapture(), SetPosition(), SetRect(), SetSize(), SetSizeWithoutNotification(), SetTextBaselineSpacing(), SetUniqueHandle(), SetZoomFactorL(), Size(), SizeChanged(), SystemGc(), TZoomType, TextBaselineOffset(), TextDrawer(), UniqueHandle(), Window(), WriteInternalStateL(), ZoomWithType(), iCoeEnv, iContext, iPosition, iSize, ~CCoeControl()
Inherited from CBase:
Delete(),
Extension_(),
operator new()
Inherited from MObjectProvider:
MObjectProvider_Reserved1(),
MObjectProvider_Reserved2(),
MopGetObject(),
MopGetObjectNoChaining()
IMPORT_C CCoeControl();
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.
IMPORT_C CCoeControl(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.
|
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.
|
IMPORT_C TBool ComponentArrayExists() const;
|
virtual IMPORT_C 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).
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().
|
|
virtual IMPORT_C 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 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.
|
virtual IMPORT_C void SetDimmed(TBool aDimmed);
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().
|
virtual IMPORT_C void SetContainerWindowL(const CCoeControl &aContainer);
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().
|
virtual IMPORT_C void ConstructFromResourceL(TResourceReader &aReader);
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().
|
virtual IMPORT_C void ActivateL();
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().
virtual IMPORT_C void PrepareForFocusLossL();
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.
virtual IMPORT_C void PrepareForFocusGainL();
Prepares the control for gaining focus.
Implementations may by taking any action required, such as updating control information. The default implementation is empty.
virtual IMPORT_C void SetAdjacent(TInt aAdjacent);
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.
|
virtual IMPORT_C void SetNeighbor(CCoeControl *aNeighbor);
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.
|
virtual IMPORT_C TBool HasBorder() const;
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.
|
virtual IMPORT_C 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 enquire the minimum size that a control requires.
Other container controls that automatically calculate the layout of their components may also use this function.
|
virtual IMPORT_C void HandleResourceChange(TInt aType);
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().
|
virtual IMPORT_C void GetColorUseListL(CArrayFix< TCoeColorUse > &aColorUseList) const;
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().
|
virtual IMPORT_C void GetHelpContext(TCoeHelpContext &aContext) const;
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.
|
virtual IMPORT_C TCoeInputCapabilities InputCapabilities() const;
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.
|
inline CCoeEnv *ControlEnv() const;
Gets the control environment object for this control.
|
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.
|
IMPORT_C TBool OwnsWindow() const;
Tests if the control is window-owning.
|
IMPORT_C TBool IsBackedUp() const;
Tests if the window owned by the control is a backed-up window.
|
IMPORT_C void SetContainerWindowL(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().
|
IMPORT_C void SetContainerWindowL(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().
|
virtual IMPORT_C TInt SetParent(CCoeControl *aParent);
Sets aParent as the parent of this control.
|
|
IMPORT_C TRect Rect() 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.
|
IMPORT_C void SetRect(const TRect &aRect);
Sets the control's extent, specifying a rectangle.
Note: calling this function results in a call to SizeChanged().
|
IMPORT_C void SetExtent(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().
|
IMPORT_C void SetExtentToWholeScreen();
Sets the control's extent to the whole screen.
Note: calling this function results in a call to SizeChanged().
IMPORT_C TSize Size() const;
Gets the control's size.
|
IMPORT_C void SetSize(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().
|
IMPORT_C TPoint Position() const;
Gets the control's position.
|
IMPORT_C TPoint PositionRelativeToScreen() const;
Gets the control's position relative to screen origin.
The screen origin is its top-left corner.
|
IMPORT_C void SetPosition(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.
|
IMPORT_C TInt MaximumWidth() const;
Gets the control's maximum width
|
IMPORT_C TInt SetMaximumWidth(TInt aMaxWidth);
Sets the controls maximum width.
|
|
IMPORT_C MCoeLayoutManager *LayoutManager() const;
Gets the layout manager
|
virtual IMPORT_C void SetLayoutManagerL(MCoeLayoutManager *aLayout);
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.
|
![[Top]](../../../../_stock/arrow_up_2.gif){kind=icon}
MCoeLayoutManager::Attachvirtual IMPORT_C TBool RequestRelayout(const CCoeControl *aChildControl);
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.
|
|
IMPORT_C TBool IsVisible() const;
Tests if the control is visible.
Unless MakeVisible() has been called with argument EFalse, the control is visible.
|
IMPORT_C void SetComponentsToInheritVisibility(TBool aInherit=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.
|
IMPORT_C TBool IsDimmed() 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().
|
IMPORT_C void SetObserver(MCoeControlObserver *aObserver);
Sets the control's observer.
|
IMPORT_C MCoeControlObserver *Observer() const;
Gets the control's observer.
|
IMPORT_C TBool IsFocused() const;
Tests if the control has focus.
Focus is set and unset using SetFocus().
|
IMPORT_C void SetFocus(TBool aFocus, TDrawNow aDrawNow=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.
|
IMPORT_C 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.
IMPORT_C void SetFocusing(TBool aFocusing);
Sets the control as able to receive keyboard focus.
|
IMPORT_C TBool IsNonFocusing() const;
Tests if the control can receive focus.
|
IMPORT_C void DrawNow() 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).
IMPORT_C void DrawNow(const TRect &aRect) const;
Draws the control, its components and child windows, within the bounds defined by the given rectangle.
|
IMPORT_C void DrawDeferred() 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.
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()).
|
IMPORT_C TInt SetGc(CWindowGc *aGraphicsContext) const;
Sets the control's graphics context. This value overrides the existing 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().
|
|
IMPORT_C CWindowGc *GetGc() const;
Returns the 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.
|
IMPORT_C void SetControlContext(MCoeControlContext *aContext);
Set the control context for this control.
|
IMPORT_C void CopyControlContextFrom(const CCoeControl *aControl);
Sets the control's context from another control.
|
IMPORT_C MCoeControlContext *ControlContext() const;
Gets the control context being used by this control.
The function does not transfer ownership to the caller.
|
IMPORT_C void SetPointerCapture(TBool aCapture=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.
|
IMPORT_C 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.
|
IMPORT_C void IgnoreEventsUntilNextPointerUp();
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.
IMPORT_C 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.
|
IMPORT_C TInt SetHitTest(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.
|
|
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().
|
IMPORT_C 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.
|
IMPORT_C TBool GetColor(TInt aLogicalColor, 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.
|
|