Class: TWindowGroup

Declaration: WindowGroup.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

MCollectible

Inherited By:

None.

Purpose:

TWindowGroup is a concrete class that uses several window layers to implement a window layering and activation policy. TWindowGroup organizes windows into three layers: menus, palettes, and content (alerts are part of the content layer). TWindowGroup's activation policy considers the front-most window in the content layer active, and prevents palettes and menus from ever becoming the active window.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Never derive from this class.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Member Function: TWindowGroup::~TWindowGroup

virtual ~ TWindowGroup ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy an object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::OrphanWindow

TWindow * OrphanWindow (TWindow &)

Interface Category:

API.

Purpose:

Removes the specified window from this window group. If the orphaned window is currently active, it is deactivated and some other window is activated based on the activation policy. The client assumes ownership of the window and is responsible for destroying it.

Calling Context:

You can call this function directly.

Parameters:

TWindow & -The window to remove from this window group.

Return Value:

Returns the orphaned window. Returns NIL if the specified window is not in the window group.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::Activate

void Activate ()

Interface Category:

API.

Purpose:

Activates this window group.

Calling Context:

You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::HandleSystemLayerChange

void HandleSystemLayerChange (const TNotification &)

Interface Category:

API.

Purpose:

HandleSystemLayerChange responds to notification that the system layer associated with this window group has changed in z-ordering. Calls SetActive.

Calling Context:

Called by the window group class notifier.

Parameters:

const TNotification & -The notification indicating that the system layer associated with this window group has changed position.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

HandleSystemLayerChange is a protected member function.

Member Function: TWindowGroup::HandlePrimaryWindowClosed

void HandlePrimaryWindowClosed (const TNotification &)

Interface Category:

API.

Purpose:

HandlePrimaryWindowClosed responds to notification that the primary window has closed. This function closes all windows within this window group.

Calling Context:

Called by the window group class notifier.

Parameters:

const TNotification & -The notification indicating that the primary window has closed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

HandlePrimaryWindowClosed is a protected member function.

Member Function: TWindowGroup::CreateDeactivationInterest

virtual TWindowInterest * CreateDeactivationInterest (TWindow * theWindow) const

Interface Category:

API.

Purpose:

Creates an interest object which can be used to register interest in deactivation of the specified window in this window group.

Calling Context:

You can call this function directly.

Parameters:

TWindow * theWindow -The window for which to create a deactivation interest.

Return Value:

Returns the newly created window interest object.

Exceptions:

Throws kWindowNotInGroup if the specified window is not in this window group. Throws kWindowNotInLayer if the specified window is not in the content layer of this window group.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::CreateActivationInterest

virtual TWindowInterest * CreateActivationInterest (TWindow * theWindow) const

Interface Category:

API.

Purpose:

Creates an interest object which can be used to register interest in activation of the specified window in this window group.

Calling Context:

You can call this function directly.

Parameters:

TWindow * theWindow -The window for which to create an activation interest.

Return Value:

Returns the newly created window interest object.

Exceptions:

Throws kWindowNotInGroup if the specified window is not in this window group. Throws kWindowNotInLayer if the specified window is not in the content layer of this window group.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::Deactivate

void Deactivate ()

Interface Category:

API.

Purpose:

Deactivates this window group.

Calling Context:

You can call this function directly, but it is generally called as the result of a layer change notification.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::SetPrimaryWindow

void SetPrimaryWindow (TWindow * window)

Interface Category:

API.

Purpose:

Establishes the specified window as the primary window in this window group. This function registers interest in the kWindowClosed event on the new primary window. TWindowGroup is notified when the primary window is closed (through HandlePrimaryWindowClosed).

Calling Context:

You can call this function directly.

Parameters:

TWindow * window -The window to become the primary window.

Return Value:

None.

Exceptions:

Throws kWindowNotInGroup if the specified window is not in this window group.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::ActivateWindow

void ActivateWindow (TWindow &)

Interface Category:

API.

Purpose:

Activates the specified window after deactivating the currently active window (there can be only one active window at a time). The window must already be a member of this window group or an exception is thrown. Opens the window if it is not already open.

Calling Context:

You can call this function directly.

Parameters:

TWindow & -The window to activate.

Return Value:

None.

Exceptions:

Throws kWindowNotInGroup if the window is not a member of this group. Throws kWindowNotInLayer if the window is not a member of the content layer.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::AdoptMenuWindow

void AdoptMenuWindow (TWindow * window)

Interface Category:

API.

Purpose:

Adds the specified window to the menu layer of this window group.

Calling Context:

You can call this function directly.

Parameters:

TWindow * window -The window to add to the menu layer of this window group.

Return Value:

None.

Exceptions:

Throws kWindowAlreadyInLayer if the specified window is already in the menu layer of this window group.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::AdoptPaletteWindow

void AdoptPaletteWindow (TWindow * window)

Interface Category:

API.

Purpose:

Adds the specified window to the palette layer of this window group.

Calling Context:

You can call this function directly.

Parameters:

TWindow * window -The window to add to the palette layer of this window group.

Return Value:

None.

Exceptions:

Throws kWindowAlreadyInLayer if the specified window is already in the palette layer of this window group.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::AdoptAlertWindow

void AdoptAlertWindow (TWindow * window)

Interface Category:

API.

Purpose:

Adds the specified alert window to the content layer of this window group.

Calling Context:

You can call this function directly.

Parameters:

TWindow * window -The alert window to add to the content layer of this window group.

Return Value:

None.

Exceptions:

Throws kWindowAlreadyInLayer if the specified alert window is already in the content layer of this window group.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::AdoptContentWindow

void AdoptContentWindow (TWindow * window)

Interface Category:

API.

Purpose:

Adds the specified window to the content layer of this window group.

Calling Context:

You can call this function directly.

Parameters:

TWindow * window -The window to add to the content layer of this window group.

Return Value:

None.

Exceptions:

Throws kWindowAlreadyInLayer if the specified window is already in the content layer of this window group.

Concurrency:

Multithread safe.

Other Considerations:

None. Warning: if a content window's HandleAfterConnectionToViewRoot function makes any calls that have the effect of calling any of the TViewRoot member functions BringToFront, SendToBack, or MoveBehind, the window group containing the window will not get proper notification of the ordering change. This is because the window group can't connect for notification until after the view root adoption is completed. Implementors of such HandleAfterConnectionToViewRoot functions should see the documentation for the TRequest class, and TView's GetRequestProcessor member function, regarding how to post a request to have the TViewRoot function call done later, after the window group is set up.

Member Function: TWindowGroup::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & -The stream the object streams itself in from.

Return Value:

Returns a reference to the stream the object streams itself in from.

Exceptions:

Throws a TAssertionFailureException.

Concurrency:

Multithread safe.

Other Considerations:

WindowGroups do not currently support streaming. Attempting to use this operator will result in an assertion failure.

Member Function: TWindowGroup::operator>>=

virtual TStream & operator >>=(TStream &) const

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & -The stream the object streams itself out to.

Return Value:

Returns a reference to the stream the object streams itself out to.

Exceptions:

Throws a TAssertionFailureException.

Concurrency:

Multithread safe.

Other Considerations:

WindowGroups do not currently support streaming. Attempting to use this operator will result in an assertion failure.

Member Function: TWindowGroup::HandleContentStateChange

virtual void HandleContentStateChange (const TNotification & notification)

Interface Category:

API.

Purpose:

Responds to notification that the last content window in the group has been hidden or closed, or that a window has been shown.

Calling Context:

Called by the constructor and the window group class notifier.

Parameters:

const TNotification & notification -The notification.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function is protected.

Member Function: TWindowGroup::GetNotifier

virtual MNotifier * GetNotifier () const

Interface Category:

API.

Purpose:

Returns the window class notifier.

Calling Context:

You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

A pointer to the class notifier.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function is protected.

Member Function: TWindowGroup::CreateContentWindowShownInterest

virtual TWindowGroupInterest * CreateContentWindowShownInterest () const

Interface Category:

API.

Purpose:

Creates a window group interest object which can be used to register interest in when any content window is shown.

Calling Context:

You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the newly created window group interest object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::CreateLastContentHiddenInterest

virtual TWindowGroupInterest * CreateLastContentHiddenInterest () const

Interface Category:

API.

Purpose:

Creates a window group interest object which can be used to register interest in when there are no content windows remaining to set active.

Calling Context:

You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the newly created window group interest object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::IsActive

bool IsActive () const

Interface Category:

API.

Purpose:

Determines whether or not this window group is currently active.

Calling Context:

You can call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if this window group is active, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::IsActiveWindow

bool IsActiveWindow (const TWindow &) const

Interface Category:

API.

Purpose:

Determines if the specified window is the active window in this window group.

Calling Context:

You can call this function directly.

Parameters:

const TWindow & -The window to check for activation.

Return Value:

Returns true if the specified window is the active window in this window group, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::IsMenuWindow

bool IsMenuWindow (const TWindow &) const

Interface Category:

API.

Purpose:

Determines whether the specified window is within the menu layer of this window group.

Calling Context:

You can call this function directly.

Parameters:

const TWindow & -The window to test for membership in the menu layer.

Return Value:

Returns true if the specified window is in the menu layer of this window group, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::IsPaletteWindow

bool IsPaletteWindow (const TWindow &) const

Interface Category:

API.

Purpose:

Determines whether the specified window is within the palette layer of this window group.

Calling Context:

You can call this function directly.

Parameters:

const TWindow & -The window to test for membership in the palette layer.

Return Value:

Returns true if the specified window is in the palette layer of this window group, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::IsAlertWindow

bool IsAlertWindow (const TWindow &) const

Interface Category:

API.

Purpose:

Determines whether the specified window is an alert window. IsContentWindow and IsAlertWindow distinguish between alert and content windows, so each window will only return true from one of these functions.

Calling Context:

You can call this function directly.

Parameters:

const TWindow & -The window to test as an alert window.

Return Value:

Returns true if the specified window is an alert window, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::IsContentWindow

bool IsContentWindow (const TWindow &) const

Interface Category:

API.

Purpose:

Determines whether the specified window is within the content layer of this window group. IsContentWindow and IsAlertWindow distinguish between alert and content windows, so each window will only return true from one of these functions.

Calling Context:

You can call this function directly.

Parameters:

const TWindow & -The window to test for membership in the content layer.

Return Value:

Returns true if the specified window is in the content layer of this window group, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::IsMember

bool IsMember (const TWindow &) const

Interface Category:

API.

Purpose:

Determines if the specified window is currently in this window group.

Calling Context:

You can call this function directly.

Parameters:

const TWindow & -The window to check for in this window group.

Return Value:

Returns true if the specified window is in this window group, false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TWindowGroup::TWindowGroup

TWindowGroup (TRequestProcessor * processor, TSystemLayer * systemLayer =NIL)
TWindowGroup ()

Interface Category:

API.

Purpose:

The TWindowGroup constructor requires a pointer to a Request Queue and an optional System Layer. The new TWindowGroup does not assume ownership of the request queue but does own the system layer. If no system layer is passed in, a new one is created.
Default constructor. This constructor is protected.

Calling Context:

You can call this function directly.
Called by the stream-in operators.

Parameters:

TRequestProcessor * processor -The request queue for the newly created window group.
TSystemLayer * systemLayer =NIL -The screen layer on which to place the new window group.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Click the icon to mail questions or corrections about this material to Taligent personnel.