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.
virtual ~ TWindowGroup ()
Interface Category:
API.
Purpose:
Destructor.
Calling Context:
Called to destroy an object.
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:
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:
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:
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:
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:
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:
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:
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:
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.
- 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.
Copyright©1995 Taligent,Inc. All rights reserved.