RWindowBase Class Reference

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 constructor; creates an uninitialised window handle within a session.

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.

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.

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.

See also: RemoveAllKeyRects()

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 coming from a single pointer in a pointer buffer, and then delivers the entire buffer when it is full.

If there are multiple pointers available in the system (for example there is a multipointer screen present), for compatibility reasons only events coming from the single emulated pointer will be stored in a pointer buffer. For more information about emulated pointer please refer to the comment of RWindowBase::EnableAdvancedPointers() method.

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.

See also: RWindowBase::EnableAdvancedPointers()

Cancels a request for a pointer repeat event.

If using multiple pointers then this method will issue the cancel to whichever pointer is currently deemed to be the primary pointer. The primary pointer is only known internally. It is advised to use only this method for windows which do not have multiple pointers enabled.

See also: RequestPointerRepeatEvent() CancelPointerRepeatEventRequest(const TUint8 aPointerNumber)

Cancels a request for a pointer repeat event.

Flushes the WServ command buffer.

See also: RequestPointerRepeatEvent(TTimeIntervalMicroSeconds32 aTime,const TRect &aRect, const TUint8 aPointerNumber) To become publishedAll with WSERV NGA APIs To become released with WSERV NGA APIs

Claims any/all pointer grabs from another windows.

For any pointer grabs already in effect in other windows, a window can claim the pointer grabs from those windows by calling this function. All subsequent events will be delivered to this window, up to and including the next "up" event for each pointer. This next up event terminates the pointer grab for that pointer, for that window (other pointers will continue being grabbed until their up event).

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

See also: RWindowBase::SetPointerGrab() RWindowBase::ClaimPointerGrab(const TUint8 aPointerNumber, const TBool aSendUpEvent)

Claims the pointer grab from another window for a specified pointer.

If the pointer grab for a given pointer is already in effect in another window, a window can claim the pointer grab from that window by calling this function. All subsequent events related to this pointer will be delivered to this window, up to and including the next "up" event. This next up event terminates the pointer grab.

Flushes the WServ command buffer.

SwEvent capability is required only for grabbing between windows belonging to different RWsSessions. Grabbing between windows from the same session does not require this capability.

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.

See also: RWindowBase::SetPointerGrab() RWindowBase::ClaimPointerGrab(TBool aSendUpEvent)

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

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

Gets the window's current display mode.

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

After calling this method all pointer events delivered to this window will be instances of TAdvancedPointerEvent class which in addition to TPointerEvent provides pointer number, proximity and pressure information.

If the device is able to handle more than one pointer at the same time (for example a touch screen that is able to determine coordinates of more than one finger touching it at the same time), then this method will enable delivering events from all detected pointers to this window.

This method must be called before the window is activated by calling RWindowBase::Activate(). Otherwise the client is panicked with the code EWservPanicUnableToEnableAdvPointer in a DEBUG mode.

If this method is not called for the window, it is assumed that the window is not able to receive events from multiple pointers, and thus only events from a single emulated pointer are sent to it. Emulated pointer ensures that code written for a single pointer environment works properly in a multiple pointer environment: there is only one global emulated pointer in the whole system and at each point in time its state is equal to state of one of the physical pointers detected by the device. WSERV switches emulated pointer between these physical pointers in a way that maximizes usability.

This method also affects any Animation working in this window. If it has been called, such an Animation will receive pointer events from all pointers. Otherwise it will receive only events from the emulated pointer.

See also: TAdvancedPointerEvent TPointerEvent::AdvancedPointerEvent() MAnimGeneralFunctions::GetRawEvents() RWindowBase::Activate() To become publishedAll with WSERV NGA APIs To become released with WSERV NGA APIs

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.

See also: TWindowBackupType

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.

See also: DisablePointerMoveBuffer()

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.

See also: RWindowTreeNode::SetFaded() RWindowTreeNode::SetNonFading()

Enables orientation independent egl rendering for a full screen instance of an eglWindowSurface created from this window.

When enabled, an instance of an eglWindowSurface created from a full screen window will behave as a full screen surface in the native orientation.

Clients using this feature take over responsibility for rotating the content of egl rendering to match the actual device orientation.

Potential candidates for using this feature are applications using a full screen eglWindowSurface in a non-native orientation, when running on devices where a rotation cost in the compositor may result in a reduced frame rate and possibly an increase in graphics memory usage.

Pointer events for this window are delivered to the client in the current device orientation. The client should express the window extent in the current device orientation, which can be obtained from CWsScreenDevice.

Note: EGraphicsOrientationNormal denotes the native orientation of the device.

See also: Optimizing Non-Native Orientation Windows in Symbian^3

Frees the pointer move buffer.

This function should be called on a window which calls AllocPointerMoveBuffer().

Retrieves a copy of the current configuration for background surface attached to the window.

The client must present a properly initialized TSurfaceConfiguration on entry in particular the size field must be valid before the call. The server will then fill the object with the available data.

If the server supports more fields it will truncate the returned data to the size the client has requested. If the server has fewer fields it will set the returned size field to the lower value.

Note that the returned attribute values will only be guaranteed equivalent to the input values, not exact copies, as the values may be calculated from internal flags rather than reported from a cached exact copy.

See also: SetBackgroundSurface RemoveBackgroundSurface

Gets the windows's pointer capture priority

See also: SetPointerCapturePriority()

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.

Tests whether the current window is faded.

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

Tests whether the current window is non-fading.

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

See also: RWindowTreeNode::SetNonFading()

This function returns the key color for the window, if used.

Deprecated

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.

Overides the default animation for current window's transition effect by sent animation description. Please refer RWsSession::RegisterEffect() comments for more information on animation 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.

Deprecated

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.

See also: TPointerFilter

Gets a window's position relative to its parent.

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

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

See also: AddKeyRect()

This removes any background surface that has been set to the window.

The surface ID registration associated with the window will be released. This is independent of any outstanding calls to RWsSession::RegisterSurface, which should be completed with a corresponding call to UnregisterSurface.

The aTriggerRedraw parameter triggers a redraw of at least the affected areas of the window at the end of this method.

See also: SetBackgroundSurface GetBackgroundSurface

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) for the pointer 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.

If using multiple pointers then this method will issue the repeat to the emulated single pointer. It is advised to use only this method for windows which do not have multiple pointers enabled.

See also: CancelPointerRepeatEventRequest() RequestPointerRepeatEvent(TTimeIntervalMicroSeconds32 aTime,const TRect &aRect, const TUint8 aPointerNumber)

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.

Flushes the WServ command buffer.

See also: CancelPointerRepeatEventRequest(const TUint8 aPointerNumber) To become publishedAll with WSERV NGA APIs To become released with WSERV NGA APIs

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.

Sets specific effect data or execute commands to the TFX layer. The data or command passed by the client API will be directed to MWsTfxLayer::SendEffectCommand. MWsTfxLayer will accept only window specific commands and data.

This sets the background of the window to be the given surface.

The surface will be stretched or compressed to fill the extent of the window. The background is updated on screen when the window is next redrawn.

When the window is moved, the surface will move with it. If the window is resized, the surface will be similarly scaled. If a 1-1 pixel mapping is required and the window size changes, the function will need to be called again with a different TSurfaceId for a surface with the new size of the window.

This sets a surface to appear in front of the window's background within a given area of that window.

Any rendering performed by CWindowGc operations will appear in front of surface for the window. The TSurfaceConfiguration object contains the Surface ID and allows various surface presentation attributes to be specified. This describes the mapping from surface co-ordinates to screen co-ordinates, allowing for scaling, cropping, and rotation.

For details on the attributes see TSurfaceConfiguration.

If the same surface ID is already set as the window background surface, then only the configuration parameters will be updated.

If the window already has a background surface (that is not same as the new surface) then that surface will be removed and the new background surface will be set. The Surface ID will be registered while attached to this window. This is in addition to any call to RWsSession::RegisterSurface.

See also: RemoveBackgroundSurface GetBackgroundSurface

Sets the shape of a window's corners.

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

See also: TCornerFlags

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.

Sets a region of a window that can receive pointer events.

Once this region is set, pointer events must be within both this region and the window's base area to be received. If an empty pointer acceptance region is set, then no pointer events will be received by this window. Pointer events that fall outside of this region will be processed for any windows underneath. Prior to calling this API the whole base area of the window can receive pointer events.

If a window is moved, the pointer acceptance region will move with it.

If a window is re-sized, the pointer region will NOT change shape/size automatically ( though it will still be clipped by the window's base area ). The new size/shape must be set explicitly from the client/application side using this API.

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

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.

See also: TCaptureFlags

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.

Allows or disallows pointer grabs in a window.

If the pointer grab is set, any down event of a given pointer in this window will cause a pointer grab of this pointer, terminated by the next corresponding up event for this pointer. All pointer events, for the grabbed pointer, up to and including the next up event will be sent to that window.

Please note that the pointer grab works separately for each pointer present in the system (for example, separately for each finger touching the multipointer screen).

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.

See also: ClaimPointerGrab()

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 parents. In other words it has the same origin and size. If the windows parent is a group window, it is initialised to be full screen.

Sets specific window purpose to the TFX layer. The purpose passed by the client API will be directed to MWsTfxLayer::SetPurpose.

See also: MWsTfxLayer

This method has been deprecated. Windows can no longer be associated with a display mode other than the system display mode. This method no longer has any effect and will always return the system display mode.

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

Deprecated

This method has been deprecated. Shadowing is no longer supported. Calling it has no effect. Deprecated

This method has been deprecated. Shadowing of a window is no longer supported. Calling it has no effect. Deprecated

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

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

Deprecated

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.

See also: RWindow::SetSize() RWindow::SetExtent() RWindowBase::SetExtentErr()

This enables clients to specify on a per-window basis whether a background surface for that window is opaque or semi-transparent. By default, a surface associated with a window via RWindowBase::SetBackgroundSurface() is taken to be opaque. This API enables a client to indicate that the surface has alpha and is to be blended into the display output rather than blitted. If this feature is disabled, and the user creates an EGL surface containing an alpha channel, then colorbuffer pixels that do not have an alpha of 1.0 will have an undefined visual appearance when composited on-screen.

The surface transparency setting is persistent, even if the background surface is removed from the window and then replaced later.

Semi-transparent surfaces will be interpreted by the composition system as using pre-multiplied alpha. For this reason, if you intend to render using OpenVG, then you must use the EGL_VG_ALPHA_FORMAT_PRE attribute when calling eglCreateWindowSurface, otherwise on-screen blending results are undefined.

See also: SetBackgroundSurface RemoveBackgroundSurface

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.

Gets the window's current size.

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

Disclaimer - this API is internal and is subject to change