![[Index]](../../../../a_stock/btn_index_wt.gif){kind=small}
![[Spacer]](../../../../a_stock/btn_spacer.gif){kind=small}
![[Previous]](../../../../a_stock/btn_prev_wt.gif){kind=small}
![[Next]](../../../../a_stock/btn_next_wt.gif){kind=small}
|
|
|
|
|
|
||
Location:
W32STD.H
Link against: ws32.lib
class RWindowBase : public RWindowTreeNode;
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 Window Server API.
MWsClientClass - Base class for all classes whose objects are clients of the window server
RWindowTreeNode - A handle to a node in the server-side window tree
RWindowBase - Client-side handle to a server-side window
Defined in RWindowBase:
AbsPosition(), Activate(), AddKeyRect(), AllocPointerMoveBuffer(), CancelPointerRepeatEventRequest(), ClaimPointerGrab(), DisablePointerMoveBuffer(), DiscardPointerMoveBuffer(), DisplayMode(), EnableBackup(), EnablePointerMoveBuffer(), FadeBehind(), FreePointerMoveBuffer(), GetPointerCapturePriority(), InquireOffset(), IsFaded(), IsNonFading(), MoveToGroup(), PasswordWindow(), PointerFilter(), Position(), RemoveAllKeyRects(), RequestPointerRepeatEvent(), RetrievePointerMoveBuffer(), SetCornerType(), SetExtentErr(), SetPointerCapture(), SetPointerCapturePriority(), 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(),
DisableGroupListChangeEvents(),
DisableModifierChangedEvents(),
DisableOnEvents(),
DisableVisibilityChangeEvents(),
EFadeIncludeChildren,
EFadeWindowOnly,
EnableErrorMessages(),
EnableFocusChangeEvents(),
EnableGroupChangeEvents(),
EnableGroupListChangeEvents(),
EnableModifierChangedEvents(),
EnableOnEvents(),
EnableVisibilityChangeEvents(),
FullOrdinalPosition(),
NextSibling(),
OrdinalPosition(),
OrdinalPriority(),
Parent(),
PrevSibling(),
SetCustomPointerCursor(),
SetFaded(),
SetNonFading(),
SetOrdinalPosition(),
SetPointerCursor(),
TFadeControl,
WindowGroupId()
IMPORT_C void Activate();
Displays the window and enables it to receive events.
Calling this method on a window causes it 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.
IMPORT_C void SetPosition(const TPoint &point);
Sets the position of a window relative to its parent.
The co-ordinates given in aPos 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 using the RWindow::SetExtent() and RWindowBase::SetExtentErr() functions.
Note: upon creation, a window's extent is the same as its parent’s. In other words it has the same origin and size. If the window’s parent is a group window, it is initialised to be full screen.
|
IMPORT_C 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 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.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt SetExtentErr(const TPoint &point, const TSize &size);
Sets 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 (in other words, 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 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.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TSize Size() const;
Gets the window's current size.
This function always causes a flush of the window server buffer.
|
IMPORT_C TPoint InquireOffset(const RWindowTreeNode &aWindow) const;
Enquires 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.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C 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.
|
IMPORT_C void SetPointerGrab(TBool aState);
Allows or disallows pointer grabs in a window.
If the pointer grab is set, 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.
|
IMPORT_C 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.
|
IMPORT_C 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.
|
IMPORT_C void SetPointerCapturePriority(TInt aPriority);
Sets the window's pointer capture priority.
To allow window gain a property that allows them to be clicked on even when they are behind a modal window. The priority will be 0 by default. Windows that need to stop modal window in front of them, should set this value to positive. Window can only capture pointer events from another window of same group, if it has at least the same pointer capture priority.
|
IMPORT_C TInt GetPointerCapturePriority() const;
Gets the windows's pointer capture priority
|
IMPORT_C 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.
|
IMPORT_C 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.
|
IMPORT_C 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.)
|
IMPORT_C TPoint Position() const;
Gets a window's position relative to its parent.
This function always causes a flush of the window server buffer.
|
IMPORT_C TPoint AbsPosition() const;
Gets a window's absolute position - ie the windows position relative to the current screen size mode.
This function always causes a flush of the window server buffer.
|
IMPORT_C TInt SetCornerType(TCornerType aCornerType, TInt aCornerFlags=0);
Sets the shape of a window's corners.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TInt SetShape(const TRegion &aRegion);
Sets a window's shape arbitrarily, if rectangular windows are not required.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C 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.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C TDisplayMode DisplayMode();
Gets the window's current display mode.
This function always causes a flush of the window server buffer.
|
IMPORT_C void EnableBackup(TUint aBackupType=EWindowBackupAreaBehind);
Requests that this window backs up all or part of the screen's contents. There are two backup possibilities:- just the area behind this window (the default), or the whole screen. Backing up the whole screen is useful for windows that require the rest of the screen to fade when they are displayed. In this case, the full screen backup is of the unfaded content of the screen.
It is possible to specify both types of backup at the same time. This may be used by fade behind windows that can be dragged across the screen, e.g. a dialog. This is done by calling this function with the parameter EWindowBackupAreaBehind|EWindowBackupFullScreen.
When backing up the whole screen, this function should be called before the window is activated, and before you call fade
behind on it (RWindowBase::FadeBehind()).
Backing up a window is an optimisation feature that is honoured only if there is enough memory to do so, (it requires bitmaps and a region to be created and maintained). If there is not enough memory, all or part of the backup will be lost. In this case, a redraw will be issued at the relevant point just as if the window had not been backed up.
The backup bitmap is made and is claimed by the window not when EnableBackup() is called, but when the window becomes visible (this is normally when the window is activated).
Only one backed up window of the same type can exist at any one time (although the same window can have both types of backup at the same time). If a window requests a backup of type EWindowBackupAreaBehind, any window that has already claimed a backup of this type will lose it. If a window requests a backup of type EWindowBackupFullScreen, this request will fail if another window has already claimed a backup of this type.
|
IMPORT_C void RequestPointerRepeatEvent(TTimeIntervalMicroSeconds32 aTime, const TRect &aRect);
Requests a pointer repeat event.
This function instructs the window 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.
|
IMPORT_C void CancelPointerRepeatEventRequest();
Cancels a request for a pointer repeat event.
IMPORT_C 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 not available on all hardware.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C void FreePointerMoveBuffer();
Frees the pointer move buffer.
This function should be called on a window which calls AllocPointerMoveBuffer().
IMPORT_C 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.
IMPORT_C void DisablePointerMoveBuffer();
Instructs the window server to stop adding pointer events to the pointer move buffer.
IMPORT_C 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).
This function always causes a flush of the window server buffer.
|
|
IMPORT_C 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).
IMPORT_C 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.
Before v7.0, calling this function stopped the window from receiving pointer events (they were received as key events) and pointer events outside the specified key rectangle were discarded. From v7.0, pointer events outside the key rectangles are not discarded and may be handled.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C void RemoveAllKeyRects();
Removes all the on-screen keys that have been added to this window.
After this function has been called, all pointer events are delivered to the window, reversing the effect of AddKeyRect().
IMPORT_C TInt PasswordWindow(TPasswordMode aPasswordMode);
Makes 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.
This function always causes a flush of the window server buffer.
|
|
IMPORT_C 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.
|
IMPORT_C TBool IsFaded();
Tests whether the current window is faded.
This function always causes a flush of the window server buffer.
|
IMPORT_C TBool IsNonFading();
Tests whether the current window is non-fading.
This function always causes a flush of the window server buffer.
|
IMPORT_C TInt MoveToGroup(TInt aIdentifier);
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 its identifier.
This function always causes a flush of the window server buffer.
|
|
|
|
TCaptureFlags
Capture behaviour flags.
|
|
Copyright ©2008 Symbian Software Ltd. |
|
![[Top]](../../../../a_stock/arrow_up_2.gif){kind=icon}
![[Previous]](../../../../a_stock/btn_prev.gif){kind=small}
![[Top]](../../../../a_stock/btn_top.gif)
![[Next]](../../../../a_stock/btn_next.gif){kind=small}