![[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:
w32std.h
Link against: ws32.lib
RWindowBase
Supported from 5.0
Client-side handle to a server-side window.
The server-side windows of handles derived from this class can be displayed on the device's screen, and associated with pointer events.
This class is not for user derivation; however derived classes form part of the standard Window Server client library.
|
Defined in RWindowBase:
Activate(), AddKeyRect(), AllocPointerMoveBuffer(), CancelPointerRepeatEventRequest(), ClaimPointerGrab(), DisablePointerMoveBuffer(), DiscardPointerMoveBuffer(), DisplayMode(), EnableBackup(), EnablePointerMoveBuffer(), FadeBehind(), FreePointerMoveBuffer(), InquireOffset(), IsFaded(), IsNonFading(), MoveToGroup(), PasswordWindow(), PointerFilter(), Position(), RWindowBase(), RemoveAllKeyRects(), RequestPointerRepeatEvent(), RetrievePointerMoveBuffer(), SetCornerType(), SetExtentErr(), SetPointerCapture(), SetPointerGrab(), SetPosition(), SetRequiredDisplayMode(), SetShadowDisabled(), SetShadowHeight(), SetShape(), SetSizeErr(), SetVisible(), Size(), TCaptureDisabled, TCaptureDragDrop, TCaptureEnabled, TCaptureFlagAllGroups, TCaptureFlagDragDrop, TCaptureFlagEnabled, TCaptureFlags
Inherited from MWsClientClass:
WsHandle()
Inherited from RWindowTreeNode:
Child(),
ClearPointerCursor(),
Close(),
Destroy(),
DisableErrorMessages(),
DisableFocusChangeEvents(),
DisableGroupChangeEvents(),
DisableModifierChangedEvents(),
DisableOnEvents(),
EFadeIncludeChildren,
EFadeWindowOnly,
EnableErrorMessages(),
EnableFocusChangeEvents(),
EnableGroupChangeEvents(),
EnableModifierChangedEvents(),
EnableOnEvents(),
FullOrdinalPosition(),
NextSibling(),
OrdinalPosition(),
OrdinalPriority(),
Parent(),
PrevSibling(),
SetCustomPointerCursor(),
SetFaded(),
SetNonFading(),
SetOrdinalPosition(),
SetPointerCursor(),
TFadeControl
protected: RWindowBase();
Protected default constructor; creates an uninitialised, sessionless window handle.
Handles to server-side objects must be created in a session in
order to be operational; this constructor is merely a convenience to allow the
handle to be stored as a data member. See
RWindowTreeNode::RWindowTreeNode() for details of how the complete
setup of a handle field may be deferred until the window server session is
known.
protected: RWindowBase(RWsSession&);
Protected constructor; creates an uninitialised window handle within a session.
|
|
void Activate();
Displays the window and enables it to receive events. Calling this method on a window causes the window to receive a redraw event if it is a non-backed-up window, and should be called after a window has been constructed and initialised.
Windows are not displayed automatically when they are constructed. This allows them to be customised using
SetPosition(), SetOrdinalPosition(),
SetExtent(), etc., before they are displayed.
TInt AddKeyRect(const TRect &aRect, TInt aScanCode, TBool aActivatedByPointerSwitchOn);
Adds an on-screen key rectangle.
This function configures an area of the screen, given by
aRect, to act as an on-screen key. Any subsequent pointer events
within this area will be translated by the window server into key events with a
scan code of aScanCode.
aActivatedByPointerSwitchOn indicates whether or
not to generate a key event as a result of a pointer event that acts to switch
the machine on.
Once this function has been called the window stops receiving pointer events (they are now received as key events). Pointer events outside the specified key rectangles are discarded.
|
|
TInt AllocPointerMoveBuffer(TInt aMaxPoints, TUint aFlags);
Allocates a buffer for storing pointer movements.
The pointer move buffer is used by applications that need to process every single pointer move or drag event: for example, a freehand drawing application.
Normally, multiple drag events which the window server receives from the pointer device driver are translated into a single drag event. The single drag event incorporates all pointer events that occurred while the client was processing the previous pointer event. If the pointer move buffer is used, the window server stores all pointer events in a pointer buffer, and then delivers the entire buffer when it is full.
AllocPointerMoveBuffer() must be called before the
pointer move buffer can be used. It would typically be called during window
construction.
After the pointer move buffer has been allocated, the window
server does not start putting pointer events into it until
EnablePointerMoveBuffer() is called.
Note:
Move events are only available on some hardware.
|
|
void CancelPointerRepeatEventRequest();
Cancels a request for a pointer repeat event.
void ClaimPointerGrab(TBool aSendUpEvent=ETrue);
Claims the pointer grab from another window.
If a pointer grab is already in effect in another window, a window can claim the pointer grab from that window by calling this function. All subsequent events will be delivered to this window, up to and including the next "up" event. This next up event terminates the pointer grab.
This function would typically be used where clicking in a window pops up another window, and where the popped-up window wishes to grab the pointer as though the original click had been in that window.
Note:
If aSendUpEvent is set to ETrue the window losing the grab is immediately sent an up event — signalling the end of its pointer grab.
|
void DisablePointerMoveBuffer();
Instructs the window server to stop adding pointer events to the pointer move buffer.
void DiscardPointerMoveBuffer();
Discards all events in the pointer move buffer.
The window server subsequently continues to put new pointer events into the pointer move buffer as usual (if the buffer is enabled).
TDisplayMode DisplayMode();
Gets the window's current display mode.
|
void EnableBackup();
Withdrawn in 6.0
Backs up the screen contents behind window.
If this function is called, the window server will make a backup of the screen contents that are overlaid by this window, whenever the window is activated or made visible. This is typically used for menus and dialogues, which temporarily overlay area of the screen, because it means that a redraw is not necessary when the window is destroyed or made invisible. A single backup is shared between all windows: therefore, the backup cannot be guaranteed to work, because another window may take the backup. Also, if something is drawn to the backed up window, the backup contents will become out-of-date and will be discarded.
void EnableBackup(TWindowBackupType aBackupType=EWindowBackupAreaBehind);
Supported from 6.0
Withdrawn in 6.1
Backs up the screen contents behind the window.
If this function is called with
aBackupType=EWindowBackupAreaBehind, the window server will make a
backup of the screen contents that are overlaid by this window, whenever the
window is activated or made visible. This is typically used for menus and
dialogues, which temporarily overlay area of the screen, because it means that a
redraw is not necessary when the window is destroyed or made invisible. A
single backup is shared between all windows: therefore, the backup cannot be
guaranteed to work, because another window may take the backup. Also, if
something is drawn to the backed up window, the backup contents will become
out-of-date and will be discarded.
Note:
This function replaces a pre-version 6.0 overload which took no arguments.
The default behaviour is unchanged with respect to previous versions of the Symbian platform. Therefore pre-version 6.0 code should compile with the same behaviour.
|
void EnableBackup(TUint aBackupType=EWindowBackupAreaBehind);
Supported from 6.1
Requests that this window backs up the screen contents behind the window. Enables the caller to specify both types at once if that is what is required.
|
void EnablePointerMoveBuffer();
Enables the pointer move buffer for receiving pointer move events.
This function instructs the window server to begin putting
pointer events into the pointer move buffer.
AllocPointerMoveBuffer() must have previously been called, or a
panic will occur.
As soon as the pointer buffer has at least one point in it, the window server sends an
event of type EEventPointerBufferReady to the client, and the
events can be retrieved from the pointer move buffer using
RetrievePointerMoveBuffer().
Note: pointer move, drag and enter/exit events are not
delivered to a window by default. An application using the pointer move buffer
should use PointerFilter() to request that these events be
delivered.
void FadeBehind(TBool aFade);
Sets whether or not all windows behind the current window, in the same window group, should be faded or unfaded.
This function can be used to fade all windows used by an application when a dialogue is displayed.
Fading works on a count basis. Fading increases the fade count, while unfading decreases it. If the fade count is greater than zero the window will be drawn faded only when it drops back to zero will it stop being faded.
This functionality is used to support nested dialogues. When bringing up a dialogue the rest of the application windows are faded. If an option is selected to launch another dialogue, the original dialogue is faded (fade count 1) and the remaining windows have their fade count increased to 2. When the dialogue is closed the fade count is reduced by one, which displays the original dialogue, but the remaining windows remain faded. They are only displayed when the other dialogue is closed and their fade count is reduced to zero.
Note:
Information is lost when a window is faded, so a redraw is required to restore the window content when it is unfaded (blank and backup windows deal with this themselves). A redraw is also required for the areas that were in shadow when the window was faded, since the shadowing also causes information loss. While a window is faded all drawing to that window will be adjusted appropriately by the window server.
|
void FreePointerMoveBuffer();
Frees the pointer move buffer.
This function should be called on window which calls
AllocPointerMoveBuffer().
TPoint InquireOffset(const RWindowTreeNode& aWindow) const;
Inquires the offset between this and another window.
A positive value indicates a position to the right and down
from aWindow, a negative value indicates a position to the left
and up.
|
|
TBool IsFaded();
Tests whether the current window is faded.
|
TBool IsNonFading();
Tests whether the current window is non-fading.
|
TInt MoveToGroup(TInt aIdentifier);
Supported from 6.0
Moves this window to another window group.
This function allows a window with a window group as its immediate parent to be moved from one window group to another one. The two window groups must be owned by the same client. The new parent window group is specified by it's identifier.
|
|
|
TInt PasswordWindow(TPasswordMode aPasswordMode);
Make this window the password window.
Only one password window can exist concurrently. Another window
may take over as the password window if either (a) the current password window
calls this function with aPasswordMode=EPasswordCancel, or (b) the
current password window is destroyed.
|
|
void PointerFilter(TUint32 aFilterMask, TUint32 aFilter);
Sets the filter which controls which pointer events are sent to the client session.
A pointer filter can be defined for each window separately, and changed dynamically. The default behaviour when a window is created is that move, drag, enter and exit events are filtered out and not delivered to the client.
|
TPoint Position() const;
Gets a window's position relative to its parent.
|
void RemoveAllKeyRects();
Removes all the on-screen keys that have been added to this window.
After this function is called all pointer events are delivered to the window — reversing the effect of AddKeyRect().
void RequestPointerRepeatEvent(TTimeIntervalMicroSeconds32 aTime, const TRect& aRect);
Request a pointer repeat event.
This function instructs the server to send a single pointer
repeat event if the pointer state that caused the last event (e.g.
EButton1Down) has not changed within aTime and the
pointer has not moved outside aRect.
Pointer repeat events are pointer events of type
TPointerEvent::EButtonRepeat.
While the repeat is in operation all move and drag events within the rectangle are filtered out. The repeat is cancelled if the pointer moves outside the rectangle or generates any other pointer event.
A typical use of this function would be for a scrollbar, so that holding down the pointer results in a continuous scroll.
|
TInt RetrievePointerMoveBuffer(TDes8 &aBuf);
Retrieves events from the pointer move buffer.
Use this function to get pointer events from the pointer move
buffer. This function should be called when an event has occurred of type
EEventPointerBufferReady (defined in
TEventCode).
|
|
TInt SetCornerType(TCornerType aCornerType, TInt aCornerFlags=0);
Sets the shape of a window's corners.
|
|
TInt SetExtentErr(const TPoint &point, const TSize &size);
Set a backed-up window's extent, relative to its parent, and returns an error code from the server.
See SetPosition() and SetSizeErr()
for a description of the rules applying to aPoint and
aSize respectively.
Avoid using this function for a window of type
RBlankWindow or RWindow (i.e., not a backed-up
window). Instead, use SetExtent(), which is more efficient as it
does not return a value. However, if the window is a backed-up window, or a
window of unknown type, SetExtentErr() should be used, because
setting the extent of a backed-up window may cause an out-of-memory
error.
This function may be called at any time after the window's
Construct() function: the window's extent will change
dynamically.
|
|
void SetPointerCapture(TInt aFlags);
Sets the pointer capture state.
A window which has called this function can capture events that would otherwise go to other windows — normally pointer events are sent to the window at the co-ordinates where the event occurs. Capturing only works on windows which are behind the capturing window in the z order.
Capture can be enabled or disabled. If capturing is enabled a window will, by default, capture events only from windows in the same window group. A flag can be specified to allow it to capture events across all window groups.
Another flag can be used to specify drag-drop capture. This causes a drag-drop message to be sent to the window within which the pen was lifted. Drag-drop with a pen is a tap-drag-lift sequence.
Capture functionality is useful in situations where only the foreground window should receive events, e.g. in a modal dialogue.
|
void SetPointerGrab(TBool aState);
Allows or disallows pointer grabs in a window.
If the pointer grab is set ETrue, any down event
in this window will cause a pointer grab, terminated by the next corresponding
up event. All pointer events up to and including the next up event will be sent to that window.
Pointer grab can be used for drag-and-drop or other situations when you want the events delivered to the same window even though the pen will be dragged outside that window. This function is typically called during window construction so that pointer grab is enabled for the lifetime of the window.
Pointer grab is disabled by default.
|
void SetPosition(const TPoint& point);
Sets the position of a window relative to its parent.
The co-ordinates given in point specify the
position of the top left-hand corner of the window, relative to the top
left-hand corner of its parent. A positive value indicates a direction to the
right and down. Negative values are valid but will cause part of the window to
be outside its parent's extent, and therefore clipped.
This function may be called at any time after the window's
Construct() function: the window's position will change
dynamically.
A window's
position can also be set via the RWindow::SetExtent() and
RWindowBase::SetExtentErr() functions.
Note:
Upon creation a windows extent is the same as it's parents, i.e. it has the same origin and size.
|
TInt SetRequiredDisplayMode(TDisplayMode aMode);
Sets the window's display mode.
Each window can be given an individual display mode because some windows may require a greater number of different colours than others.
The default display mode of a window is dependent on the individual target device. The default mode may not reflect the full capabilities of the display — on some devices a simpler colour mode may be used as the default in order to save battery power. In these cases, this method may be used to request a different display mode on a per-window basis.
At any given time, the window server uses the highest display
mode of the windows currently visible — and switches the hardware into that mode. Therefore, if an application contains a
window with display mode EGray16, but only EGray4
windows are visible, the screen hardware will use EGray4 until the
EGray16 window becomes visible.
|
|
void SetShadowDisabled(TBool aState);
Enables or disables whether a window casts a shadow.
By default, when a window is created, its shadow is not disabled. (But note that a shadow is only cast by top-level windows.)
|
void SetShadowHeight(TInt aHeight);
Sets a window's shadow height.
This is the height that this window is above the window immediately behind it. The offset of the shadow's bottom right corner from the window's bottom right corner is the product of the window's shadow height and the system shadow vector.
A shadow is only displayed on top-level windows.
|
TInt SetShape(const TRegion &aRegion);
Sets a window's shape arbitrarily, if rectangular windows are not required.
|
|
TInt SetSizeErr(const TSize &size);
Sets the size of a backed-up window.
A window's size is not constrained by the size of its parent. However, its visible region is, and the child window's visible region will always be clipped to the parent's visible region.
Avoid using this function for a window known to be of type
RBlankWindow or RWindow (i.e., not a backed-up
window). Instead, use SetSize(), which is more efficient as it
does not return a value. However, if the window is a backed-up window, or a
window of unknown type, SetSizeErr() should be used, because
setting the size of a backed-up window may cause an out-of-memory error.
This function may be called at any time after the window's
Construct() function: the window's size will change
dynamically.
|
|
void SetVisible(TBool aState);
Sets the window's visibility.
This function can be called after the window has been created to dynamically change its visibility.
Notes:
When a window is invisible, it receives no events from the window server.
A window is invisible before it is activated, irrespective of the state of its visibility flag.
|
TSize Size() const;
Gets the window's current size.
|
|
TCaptureFlags
Capture behaviour flags.
The first three flags actually control state, the remaining flags are
|
Copyright ©2002 Symbian Ltd. 6.1-00174 |
|
![[Top]](../../../stock/arrow_up_2.gif){kind=icon}
![[Top]](../../../stock/arrow_up.gif){kind=icon}