Symbian
Symbian Developer Library

SYMBIAN OS V9.4

Feedback

[Index] [Previous] [Next]

#include <W32STD.H>

Class RWindowBase

class RWindowBase : public RWindowTreeNode;

Description

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.

Derivation

Members

Defined in RWindowBase:

Inherited from MWsClientClass:

Inherited from RWindowTreeNode:


Member functions


Activate()

IMPORT_C void Activate();

Description

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 RWindowBase::SetPosition(const TPoint &), RWindowTreeNode::SetOrdinalPosition(TInt), SetExtent(), etc., before they are displayed.


SetPosition(const TPoint &)

IMPORT_C void SetPosition(const TPoint &point);

Description

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(const TPoint &,const TSize &) and RWindowBase::SetExtentErr(const TPoint &,const TSize &) 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.

Parameters

const TPoint &point

The position of the window's origin, relative to its parent


SetSizeErr(const TSize &)

IMPORT_C TInt SetSizeErr(const TSize &size);

Description

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, RWindowBase::SetSizeErr(const TSize &) 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.

Parameters

const TSize &size

Window size.

Return value

TInt

KErrNone if successful, otherwise one of the system-wide error codes.

See also:


SetExtentErr(const TPoint &,const TSize &)

IMPORT_C TInt SetExtentErr(const TPoint &point, const TSize &size);

Description

Sets a backed-up window's extent, relative to its parent, and returns an error code from the server.

See RWindowBase::SetPosition(const TPoint &) and RWindowBase::SetSizeErr(const TSize &) 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, RWindowBase::SetExtentErr(const TPoint &,const TSize &) 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.

Parameters

const TPoint &point

The position of the window's origin, relative to its parent.

const TSize &size

Window size.

Return value

TInt

KErrNone if successful, otherwise one of the system-wide error codes.


Size()const

IMPORT_C TSize Size() const;

Description

Gets the window's current size.

This function always causes a flush of the window server buffer.

Return value

TSize

Current size of window.


InquireOffset(const RWindowTreeNode &)const

IMPORT_C TPoint InquireOffset(const RWindowTreeNode &aWindow) const;

Description

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.

Parameters

const RWindowTreeNode &aWindow

Another window tree node.

Return value

TPoint

The offset of this window relative to aWindow.


PointerFilter(TUint32,TUint32)

IMPORT_C void PointerFilter(TUint32 aFilterMask, TUint32 aFilter);

Description

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.

Parameters

TUint32 aFilterMask

Bitwise OR of values from TPointerFilter masking event types which will be updated.

TUint32 aFilter

Bits containing new values for the masked event types. A 1 bit causes the corresponding event to be filtered out, a 0 bit lets through the corresponding event.

See also:


SetPointerGrab(TBool)

IMPORT_C void SetPointerGrab(TBool aState);

Description

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.

Parameters

TBool aState

New state for the pointer grab setting.

See also:


ClaimPointerGrab(TBool)

IMPORT_C void ClaimPointerGrab(TBool aSendUpEvent=ETrue);

Description

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.

Parameters

TBool aSendUpEvent

Whether to deliver an up event to the window that previously had the grab.

See also:


SetPointerCapture(TInt)

IMPORT_C void SetPointerCapture(TInt aFlags);

Description

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.

Parameters

TInt aFlags

Bitwise OR of flag values from TCaptureFlags.

See also:


SetPointerCapturePriority(TInt)

IMPORT_C void SetPointerCapturePriority(TInt aPriority);

Description

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.

Parameters

TInt aPriority

Pointer capture priority


GetPointerCapturePriority()const

IMPORT_C TInt GetPointerCapturePriority() const;

Description

Gets the windows's pointer capture priority

Return value

TInt

Window's pointer capture priority

See also:


SetVisible(TBool)

IMPORT_C void SetVisible(TBool aState);

Description

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.

Parameters

TBool aState

New value for the visibility.


SetShadowHeight(TInt)

IMPORT_C void SetShadowHeight(TInt aHeight);

Description

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.

Parameters

TInt aHeight

Shadow height. The default is 0.


SetShadowDisabled(TBool)

IMPORT_C void SetShadowDisabled(TBool aState);

Description

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.)

Parameters

TBool aState

ETrue if the shadow is to be disabled (not displayed). EFalse if the shadow is to be displayed


Position()const

IMPORT_C TPoint Position() const;

Description

Gets a window's position relative to its parent.

This function always causes a flush of the window server buffer.

Return value

TPoint

Position of this window's origin relative to the origin of its parent.


AbsPosition()const

IMPORT_C TPoint AbsPosition() const;

Description

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.

Return value

TPoint

Position of this window's origin relative to the screen.


SetCornerType(TCornerType,TInt)

IMPORT_C TInt SetCornerType(TCornerType aCornerType, TInt aCornerFlags=0);

Description

Sets the shape of a window's corners.

This function always causes a flush of the window server buffer.

Parameters

TCornerType aCornerType

Corner type to apply.

TInt aCornerFlags

Bitwise OR of flags indicating corners to exclude.

Return value

TInt

KErrNone if successful, otherwise one of the system-wide error codes.

See also:


SetShape(const TRegion &)

IMPORT_C TInt SetShape(const TRegion &aRegion);

Description

Sets a window's shape arbitrarily, if rectangular windows are not required.

This function always causes a flush of the window server buffer.

Parameters

const TRegion &aRegion

Region defining window shape.

Return value

TInt

KErrNone if successful, otherwise one of the system-wide error codes.


SetRequiredDisplayMode(TDisplayMode)

IMPORT_C TInt SetRequiredDisplayMode(TDisplayMode aMode);

Description

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.

Parameters

TDisplayMode aMode

The display mode: can have any TDisplayMode value except ERgb (since this isn't a mode that screen hardware can ever take).

Return value

TInt

The display mode to which the window has been set. This is the closest display mode to aMode supported by the hardware.


DisplayMode()

IMPORT_C TDisplayMode DisplayMode();

Description

Gets the window's current display mode.

This function always causes a flush of the window server buffer.

Return value

TDisplayMode

The window's current display mode.


EnableBackup(TUint)

IMPORT_C void EnableBackup(TUint aBackupType=EWindowBackupAreaBehind);

Description

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(TBool)).

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 RWindowBase::EnableBackup(TUint) 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.

Parameters

TUint aBackupType

The type of backed up window. See the TWindowBackupType enum for possible values.

See also:


RequestPointerRepeatEvent(TTimeIntervalMicroSeconds32,const TRect &)

IMPORT_C void RequestPointerRepeatEvent(TTimeIntervalMicroSeconds32 aTime, const TRect &aRect);

Description

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.

Parameters

TTimeIntervalMicroSeconds32 aTime

Time interval before pointer repeat event should be sent.

const TRect &aRect

Repeat event occurs only if pointer is within this rectangle.

See also:


CancelPointerRepeatEventRequest()

IMPORT_C void CancelPointerRepeatEventRequest();

Description

Cancels a request for a pointer repeat event.

See also:


AllocPointerMoveBuffer(TInt,TUint)

IMPORT_C TInt AllocPointerMoveBuffer(TInt aMaxPoints, TUint aFlags);

Description

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.

RWindowBase::AllocPointerMoveBuffer(TInt,TUint) 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 RWindowBase::EnablePointerMoveBuffer() is called.

Note: move events are not available on all hardware.

This function always causes a flush of the window server buffer.

Parameters

TInt aMaxPoints

Maximum number of pointer events the buffer can hold. This affects the frequency at which the buffer is flushed.

TUint aFlags

Obsolete argument: set to zero always.

Return value

TInt

KErrNone if successful, otherwise one of the system-wide error codes.


FreePointerMoveBuffer()

IMPORT_C void FreePointerMoveBuffer();

Description

Frees the pointer move buffer.

This function should be called on a window which calls RWindowBase::AllocPointerMoveBuffer(TInt,TUint).


EnablePointerMoveBuffer()

IMPORT_C void EnablePointerMoveBuffer();

Description

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. RWindowBase::AllocPointerMoveBuffer(TInt,TUint) 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 RWindowBase::RetrievePointerMoveBuffer(TDes8 &).

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 RWindowBase::PointerFilter(TUint32,TUint32) to request that these events be delivered.

See also:


DisablePointerMoveBuffer()

IMPORT_C void DisablePointerMoveBuffer();

Description

Instructs the window server to stop adding pointer events to the pointer move buffer.


RetrievePointerMoveBuffer(TDes8 &)

IMPORT_C TInt RetrievePointerMoveBuffer(TDes8 &aBuf);

Description

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.

Parameters

TDes8 &aBuf

Buffer to store events retrieved from pointer move buffer

Return value

TInt

KErrNone if successful, otherwise one of the system-wide error codes.


DiscardPointerMoveBuffer()

IMPORT_C void DiscardPointerMoveBuffer();

Description

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).


AddKeyRect(const TRect &,TInt,TBool)

IMPORT_C TInt AddKeyRect(const TRect &aRect, TInt aScanCode, TBool aActivatedByPointerSwitchOn);

Description

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.

Parameters

const TRect &aRect

Rectangle to act as an on-screen key, relative to the window origin

TInt aScanCode

Scan code of key events generated by this on-screen key

TBool aActivatedByPointerSwitchOn

If ETrue, a switch-on pointer event will produce a key event. If EFalse, a switch-on pointer event will not produce a key event.

Return value

TInt

KErrNone if successful, otherwise one of the system-wide error codes.

See also:


RemoveAllKeyRects()

IMPORT_C void RemoveAllKeyRects();

Description

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 RWindowBase::AddKeyRect(const TRect &,TInt,TBool).

See also:


PasswordWindow(TPasswordMode)

Interface status: deprecated

IMPORT_C TInt PasswordWindow(TPasswordMode aPasswordMode);

Description

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.

Parameters

TPasswordMode aPasswordMode

The type of password handling required.

Return value

TInt

KErrNone if successful, KErrInUse if this function is called when another password window already exists, otherwise another of the system-wide error codes.


FadeBehind(TBool)

IMPORT_C void FadeBehind(TBool aFade);

Description

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.

Parameters

TBool aFade

ETrue to increase the fade count of all windows behind the current window (within the current window group), EFalse to reduce the fade count.

See also:


IsFaded()

IMPORT_C TBool IsFaded();

Description

Tests whether the current window is faded.

This function always causes a flush of the window server buffer.

Return value

TBool

ETrue if the current window is faded, otherwise EFalse.


IsNonFading()

IMPORT_C TBool IsNonFading();

Description

Tests whether the current window is non-fading.

This function always causes a flush of the window server buffer.

Return value

TBool

ETrue if the current window is non-fading, otherwise EFalse.

See also:


MoveToGroup(TInt)

IMPORT_C TInt MoveToGroup(TInt aIdentifier);

Description

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.

Parameters

TInt aIdentifier

The identifier of the target window group. This is the value returned by RWindowGroup::Identifier()const.

Return value

TInt

KErrNone if successful, otherwise another of the system-wide error codes. An error is returned if an attempt is made to move the window between window groups in different clients.

[Top]


Member enumerations


Enum TCaptureFlags

TCaptureFlags

Description

Capture behaviour flags.

See also:

TCaptureFlagEnabled

If set, capture is enabled, disabled otherwise.

TCaptureFlagDragDrop

If set, drag-drop events are sent to the window in which the pointer was lifted. Drag-drop is a tap-drag-lift sequence.

TCaptureFlagAllGroups

Capture events from windows belonging to any group, not just the group of the window on which the flag was set

TCaptureDisabled

Equivalent to disabling all the above flags.

TCaptureEnabled

Equivalent to TCaptureFlagEnabled.

TCaptureDragDrop

Equivalent to the OR of the first three flags.