RWindowGroup Class Reference

Creates a sessionless, uninitialised window group 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.

Creates an initialised window group handle within a server session.

Adds a priority key.

Priority key events are typically used for providing "Abort" or "Escape" keys for an application. For priority key events to occur they must first be configured using this function. Functions provided by RWsSession can then be used to get priority key events. Note that unlike other events, the Control Framework does not get priority key events for you.

Priority key events for the key given by aKeyCode are only delivered when the modifier keys specified by aModifierMask are in the states specified by aModifiers. See RWsSession::SetHotKey() for examples of how to use aModifierMask and aModifiers.

More than one priority key can be added for each keycode, each having a different set of modifier requirements.

Note: if you press a priority key while another is waiting to be sent to the client then the first key is lost.

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

Allows a Window Group in the specified process to be be a child of this one

This function will need to be called to allow another window group to become a child window group of this one.

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

Sets or disables auto-foreground behaviour.

If this behaviour is set for a window, it will automatically be given ordinal position zero whenever a pointer event of type EButton1Down occurs in any of its child windows. This will cause it to be brought to the foreground, unless another window group exists with a higher priority.

A window group that is moved to the foreground will automatically get keyboard focus unless it has explicitly had receipt-of-focus disabled or there is a focusable window group of higher priority. See EnableReceiptOfFocus().

Cancels a request for key capture.

Use this function to cancel a request to capture a key previously made with CaptureKey(). If the value passed in aHotKey is not a valid capture key handle, this function will cause a panic.

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

Cancels a capture request for a key up or key down event.

Use this function to cancel a request to capture a key, previously made with CaptureKeyUpAndDowns(). If the value passed in aHotKey is not a valid capture key handle, this function will cause a panic.

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

Cancels a previous long key capture request.

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

Removes the text cursor.

Use this function to remove the current text cursor from this window group. This function does nothing if the cursor is currently in another window group.

Requests key capture.

This function instructs the window server to send key events (of type EEventKey) with the specified key code and modifier state to this window group, regardless of which window group currently has the keyboard focus.

wsGroup->CaptureKey(EKeyDevice2, EModifierAlt|EModifierCtrl, EModifierCtrl); 

Normally, keyboard key presses result in three events being delivered to the client: EEventKeyDown, EEventKey and EEventKeyUp. However, CaptureKey() results in only the EEventKey being delivered to the window group that called it: the EEventKeyUp and EEventKeyDown events are sent to the window group that has focus. If a window group wishes to capture the EEventKeyUp and EEventKeyDown events as well as the EEventKey, it should call CaptureKeyUpAndDowns().

Note that a window group can call this function more than once (to request capture for more than one key), and more than one window group may have requested key capture. If multiple window groups have requested to capture the same key using this function, the key is sent to the window group that most recently requested the key capture.

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

Requests key capture, with a priority.

This function instructs the window server to send key events (of type EEventKey) with the specified key code and modifier state to this window group, regardless of which window group currently has the keyboard focus.

wsGroup->CaptureKey(EKeyDevice2, EModifierAlt|EModifierCtrl, EModifierCtrl, priority); 

Normally, keyboard key presses result in three events being delivered to the client: EEventKeyDown, EEventKey and EEventKeyUp. However, CaptureKey() results in only the EEventKey being delivered to the window group that called it: the EEventKeyUp and EEventKeyDown events are sent to the window group that has focus. If a window group wishes to capture the EEventKeyUp and EEventKeyDown events as well as the EEventKey, it should call CaptureKeyUpAndDowns().

Note that a window group can call this function more than once (to request capture for more than one key), and more than one window group may have requested key capture. If multiple window groups have requested to capture the same key at the same priority, the key is sent to the window group that most recently requested the key capture.

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

Requests the capture of key-up and key-down events on behalf of a window group.

This function requests the window server to send EEventKeyUp and EEventKeyDown key events from the specified key to this window group, regardless of which window group currently has the keyboard focus. This contrasts with CaptureKey(), which causes the window server to send the EEventKey event.

Key events for the key given by aScanCode are captured only when the modifier keys specified by aModifierMask are in the states specified by aModifiers. See RWsSession::SetHotKey() for examples of how to set aModifierMask and aModifiers.

Note: in general, keyboard key presses result in three events being delivered to the client: EEventKeyDown, EEventKey and EEventKeyUp.

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

Requests capture of long key presses.

This function causes the window server to send a long key event (which is generated when the key has been held down for the initial keyboard repeat time), to this window group, regardless of whether it currently has keyboard focus. The key that is output can have a different key code to the key that was captured.

Key events for the key given by aInputKeyCode are captured only when the modifier keys specified by aModifierMask are in the states specified by aModifiers.

A priority can be specified to resolve any conflicts that arise when multiple window groups attempt to capture the same long key event.

Normal key press behaviour (where no long key press capture requests have been made) is as follows. When a key is pressed, a key down event occurs, followed by one or more standard (short) key events, followed by a key up event. All of these key events are sent to the application in the foreground.

Key press behaviour when an application has made a long key press capture request is as follows. When the key is pressed and held down, a long key event is generated in addition to the events described above (although if a long key event occurs, then there will never be more than one standard key event) and this is sent to the application that made the request, even if it is not in the foreground.

If that application also wants to capture the up and down key events then it needs to call CaptureKeyUpAndDowns(). If it wants to capture the standard key event, then it needs to call CaptureKey(). Depending on flags (enumerated in TLongCaptureFlags) specified when making the long key capture request, the standard key event can either be generated when the key is pressed, as it would be if no long key capture request had been made, or it can be generated when the key is released. In the latter case, the standard key event is only generated if the key was not held down long enough to generate a long key event.

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

See also: TLongCaptureFlags

Requests capture of long key presses.

This function causes the window server to send a long key event (which is generated when the key has been held down for the specified time), to this window group, regardless of whether it currently has keyboard focus.

For more information on this function, see the other CaptureLongKey() overload.

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

See also: TLongCaptureFlags

Clears all children of the current window group.

The window group chain is broken directly after the current window group. In the general case (consider clearing the child group of a window group in the middle of a long chain), this results in two distinct chains. In the special cases where either the parent window group or the child window group ends up as the only member of a resultant chain, it is removed from that chain.

See also: SetChildGroup()

Completes construction of a window group.

Construction must be complete before any other window group methods can be called.

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

See also: RWindow::Construct()

Completes construction of a window group on a screen.

Construction must be complete before any other window group methods can be called.

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

See also: RWindow::Construct()

Completes construction of a window group on a screen.

Construction must be complete before any other window group methods can be called.

The purpose of this Construct function for RWindowGroup is that it allows chains of window groups to be created on a specific screen. When one of the window groups in a chain is moved with SetOrdinalPosition then all window groups in that chain will be moved to be consecutative, with the parent being at the back in the Z-order. The purpose of this feature is to allow embedding of applications.

Note: The term parent should not be confused with the paremeter used in the function RWindow::Construct. There it means that this window is a child of that window in the tree. Here is just means that the two window groups involved will have an extra association. Note: This window group will be given the same ordinal priority as it's parent window group.

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

See also: RWindow::Construct()

Completes the construction of a window group, setting its initial focus state.

Construction must be complete before any other window group methods can be called.

aInitialFocusState can be specified in order to prevent a window group from automatically taking the keyboard focus when it is created. If specified, it sets the initial focus state of the window group. If a window group has a focus state of ETrue (the default), it can receive keyboard focus; if EFalse, it is prevented from receiving keyboard focus until this setting is changed. If a window group is constructed without specifying an initial focus state, keyboard focus will be enabled by default and the window group will receive keyboard focus automatically when it is created. To prevent this, set aInitialFocusState to EFalse.

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

See also: EnableReceiptOfFocus() RWindow::Construct()

Completes construction of a window group.

Construction must be complete before any other window group methods can be called.

The purpose of this Construct function for RWindowGroup is that it allows chains of window groups to be created. When one of the window groups in a chain is moved with SetOrdinalPosition then all window groups in that chain will be moved to be consecutative, with the parent being at the back in the Z-order. The purpose of this feature is to allow embedding of applications.

Note: The term parent should not be confused with the paremeter used in the function RWindow::Construct. There it means that this window is a child of that window in the tree. Here is just means that the two window groups involved will have an extra association. Note: This window group will be given the same ordinal priority as it's parent window group.

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

See also: RWindow::Construct()

Completes construction of a window group.

Construction must be complete before any other window group methods can be called.

This Construct function of RWindowGroup allows both the creation of the group window in a chain and for and for it not to recieve focus.

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

See also: RWindow::Construct()

Makes this window group the default owning window group.

The default owning window group is the group that is brought to the foreground when the window group which has keyboard focus (the foreground application) dies, if no other window has been set up as the owning group.

This window group will take over as the default owning window group even if another window group has previously called this function. However, if this window group is subsequently destroyed, the default owning window group will revert to being the previous window group.

See also: SetOwningWindowGroup()

Disables key clicks.

If a window group calls this function with aState=ETrue, key clicks (i.e. the sound generated when keys are pressed) will be disabled whenever this window group has the keyboard focus. Key clicks for this window group can be re-enabled by calling this function with aState=EFalse.

Note that this function doesn't do anything in v6.0 and v6.1.

Disables screen change event sending.

This function prevents window groups from getting screen change events, which are sent, for example, when the cover on a phone that supports screen flipping is opened or closed.

Note that not getting screen change events is the default behaviour.

See EnableScreenChangeEvents().

Enables or disables receipt of keyboard focus.

The front most focusable window has keyboard focus. This function sets whether or not the window can receive keyboard focus.

Enables screen change event sending.

This function ensures that window groups are sent screen change events, which are sent, for example, when the cover on a phone that supports screen flipping is opened or closed.

Note that not getting screen change events is the default behaviour.

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

See also: DisableScreenChangeEvents()

Gets the identifier of the window group.

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

Gets the window group's name, as set by SetName().

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

Removes a priority key.

Use this function to remove a priority key that was added using AddPriorityKey(). If the specified priority key does not exist, this function does nothing.

Note: all 3 parameters must match exactly for a successful removal.

Sets a window group chain onto the current window group.

Appends all the window groups chained to the child window group onto the chain containing the current window group.

See also: ClearChildGroup()