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.

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

Cancels a request for a pointer repeat event.

RequestPointerRepeatEvent()

Dummy implementation in order to preserve compatibility with WSERV NGA.

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.

SetPointerGrab()

Dummy implementation in order to preserve compatibility with WSERV NGA.

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.

Dummy implementation in order to preserve compatibility with WSERV NGA.

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.

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.

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.

RWindowTreeNode::SetFaded() RWindowTreeNode::SetNonFading()

Dummy implementation in order to preserve compatibility with WSERV NGA.

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.

Gets the windows's pointer capture priority

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.

RWindowTreeNode::SetNonFading()

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

In chroma key composition mode, this will be an opaque color; in alpha composition mode, it will be transparent black, i.e. TRgb(0, 0, 0, 0). If the window does not have a surface or overlay background, the return value is transparent black.

The value of a chroma key color depends on the background type. Windows with surface backgrounds return the system defined key color, whereas windows with overlay backgrounds return the color passed in.

If the return value is opaque, the client should take care to avoid using the color when rendering further content in the window, since it may cause that content to become invisible.

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.

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.

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.

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

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.

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.

CancelPointerRepeatEventRequest()

Dummy implementation in order to preserve compatibility with WSERV NGA.

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.

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.

The key color to use in chroma key composition mode is defined by the system, for all TSurfaceId background windows to use. In alpha composition mode, transparent black is used. The composition mode is determined by the screen display mode: if the mode supports an alpha channel, alpha composition is used; otherwise chroma key composition is used.

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.

The composition mode is determined by the screen display mode: if the mode supports an alpha channel, alpha composition is used; otherwise chroma key composition is used. In chroma key composition mode, the key color used is defined by the system, for all TSurfaceId background windows to use. In alpha composition mode, transparent black is used.

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

Sets the shape of a window's corners.

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

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

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

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

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.

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

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.

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

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

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.

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

Not supported in non-NGA

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.

Dummy implementation in order to preserve compatibility with WSERV NGA.

Capture behaviour flags.

SetPointerCapture() EEventDragDrop