Taxonomy Categories:
Member Functions:
Interface Category:
API.
Inherits From:
TActivationManagerView, MControl
Inherited By:
TMenuWindow
TPrimitiveFrameView
Purpose:
TWindow derives from TActivationManagerView and MControl and is the abstract base class from which all windows descend. In addition to the functionality provided by TView, TWindows can be open or closed, shown or hidden, enabled or disabled, and highlighted or unhighlighted. TWindows have position and size; the position is defined in terms of the parent view's coordinate system, and the size is defined in the window's own coordinate system. No assumption is made regarding the shape or size of the window.
Although a window typically exists on the desktop, this is not a strict requirement, and windows, being a derived class of TView, can exist inside another view.
Note that TWindow has no concept of activation beyond that provided by TActivationManagerView, nor does it assume anything about its location within the view hierarchy--in effect, it's just a specialized view. It is the responsibility of other objects to enforce a specific activation policy.
By default, the TWindow class is not a MMouseEventHandler. Use TStandardWindow for a standard rectangular window providing mouse input handling.
Clients can register interest in various state changes occurring within this window--for example, when the window opens. To register interest in a window event on a particular window: (1) Create a TWindowInterest object (using TWindow's CreateInterest function) and specify the event type of interest, (2) Use the interest object to register interest with the view class notifier. When a window event occurs within this window, the window uses the view class notifier, which, in turn, notifies any objects that have registered an interest in that event on this window. The TTokens whose names begin with kWindow are used to create TWindowInterest objects, and to notify objects when the window event occurs.
Instantiation:
Abstract base class; do not allocate.
Deriving Classes:
Classes deriving from TWindow should not override Open, Close, Enable, Disable, Show, Hide, and Hilite to provide specialized window behavior when those actions take place in a window. Instead, they should override the corresponding functions whose names begin with Handle. The non- Handle functions call the Handle functions, giving derived classes an opportunity to provide specialized behavior. By default the Handle functions do nothing.
Classes deriving from TWindow should override DrawContents (inherited from TView) to provide specialized look.
Classes deriving from TWindow must include TWindow in any DynamicCast macros they provide. Failure to do so may result in hard to track down bugs in their activation behavior, since the activation framework relies on dynamic casting for views to be activated.
Concurrency:
In general, this class is not multithread safe. However, four member functions are multithread safe: IsOpen, IsShown, IsEnabled, and IsHilited.
Resource Use:
No special requirements.
virtual ~ TWindow ()
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:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::Open
void Open ()
Interface Category:
API.
Purpose:
Opens the window.
Open is part of TWindow's open and close protocol. Developers should override the HandleOpen and HandleClose functions to implement specific open or close behavior.
Calling Context:
You can call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::Close
void Close ()
Interface Category:
API.
Purpose:
Closes the window and disables it if the window is currently enabled.
Close is part of TWindow's open and close protocol. Developers should override the HandleOpen and HandleClose functions to implement specific open or close behavior.
Calling Context:
You can call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::Show
void Show ()
Interface Category:
API.
Purpose:
Used to make a window visible. Clients should use this function instead of TView::SetVisibility to change the window's visibility.
Show is part of TWindow's show and hide protocol. Developers should override the HandleShow and HandleHide functions to implement specific show or hide behavior.
Calling Context:
You can call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws a kWindowNotOpen exception if the window is not open.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::Hide
void Hide ()
Interface Category:
API.
Purpose:
Used to make a window invisible. Clients should use this function instead of TView::SetVisibility to change the window's visibility.
Hide is part of TWindow's show and hide protocol. Developers should override the HandleShow and HandleHide functions to implement specific show or hide behavior.
Calling Context:
You can call this function directly.
Parameters:
Return Value:
None.
Exceptions:
Throws a kWindowNotOpen exception if the window is not open.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::Enable
void Enable ()
Interface Category:
API.
Purpose:
Enables the window.
Enable is part of TWindow's enable and disable protocol. Developers should override the HandleEnable function to implement specific enable behavior.
Calling Context:
This function is typically called directly by an activation policy object rather than by developer code.
Parameters:
Return Value:
None.
Exceptions:
Throws a kWindowNotOpen exception if the window is not open.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::Disable
void Disable ()
Interface Category:
API.
Purpose:
Disables a window. Disable unhighlights the window if currently highlighted.
Disable is part of TWindow's enable and disable protocol. Developers should override the HandleDisable function to implement specific enable behavior.
Calling Context:
This function is typically called directly by an activation policy object rather than by developer code.
Parameters:
Return Value:
None.
Exceptions:
Throws a kWindowNotOpen exception if the window is not open.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::CreateInterest
virtual TWindowInterest * CreateInterest (const TToken & theChange) const
Interface Category:
API.
Purpose:
Creates a notification interest on this window. The TWindow class sends out notification whenever the window is opened, closed, shown, hidden, enabled, disabled, highlighted or unhighlighted. The caller is responsible for destroying the TWindowInterest object created by this function.
Calling Context:
You can call this function directly.
Parameters:
- const TToken & theChange -The window event in which the caller is interested.
Return Value:
Returns the newly create TWindowInterest object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::MoveWindowTo
virtual void MoveWindowTo (const TGPoint &)
Interface Category:
API.
Purpose:
Moves the window within its parent view to the specified location. The upper left corner is placed at the specified point. Clients should use this function instead of TView::TranslateTo.
Calling Context:
You can call this function directly.
Parameters:
- const TGPoint & -The new location for the upper left corner of the window. This point is specified in the parent view's coordinate system.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::MoveWindowBy
virtual void MoveWindowBy (const TGPoint &)
Interface Category:
API.
Purpose:
Moves the window within its parent view, relative to its current location, by the specified delta values. Clients should use this function instead of TView::TranslateBy.
Calling Context:
You can call this function directly.
Parameters:
- const TGPoint & -The delta X and delta Y values by which to move the window. These values are specified in the parent view's coordinate system.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::SetWindowSize
virtual void SetWindowSize (const TGPoint &)
Interface Category:
API.
Purpose:
Sets the window size. Although windows can be any shape, it is assumed that a given window class has a discrete shape as part of its invariant. The point passed into TWindow::SetWindowSize describes the width and height of the window's bounding box. The default implementation of TWindow::SetWindowSize simply calls TView::SetAllocatedArea passing in a TGRect with a width and height equal to the point passed in. The window size is always pinned within the minimum and maximum resize limits which are established using the SetResizeLimits member functions.
Calling Context:
You can call this function directly.
Parameters:
- const TGPoint & -The new width and height for the window's bounding box. The X coordinate of the point is the width, and the Y coordinate of the point is the height.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::GetWindowSize
virtual TGPoint GetWindowSize () const
Interface Category:
API.
Purpose:
Gets the window size. Although windows can be any shape, it is assumed that a given window class has a discrete shape as part of its invariant. The point returned by TWindow::GetWindowSize describes the width and height of the window's bounding box.
Calling Context:
You can call this function directly.
Parameters:
Return Value:
Returns a TGPoint whose X coordinate is the width and whose Y coordinate is the height of the window's bounding box.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::SetResizeLimits
- virtual void SetResizeLimits (const TGPoint & minSize, const TGPoint & maxSize)
- virtual void SetResizeLimits (const TGRect &)
Interface Category:
API.
Purpose:
Sets the minimum and maximum resize limits for the window. The bounding box that describes the window's size will not be allowed to become smaller than the minimum resize limit, nor larger than the maximum resize limit. These functions are overloaded to take either two TGPoints, or a TGRect where the top left point specifies the minimum resize limit and the bottom right point specifies the maximum resize limit.
Calling Context:
- You can call this function directly.
- You can call this function directly.
Parameters:
- const TGPoint & minSize -The minimum allowable size for the window's bounding box. The X coordinate of this point represents the smallest width and the Y coordinate of this point represents the smallest height.
- const TGPoint & maxSize -The maximum allowable size for the window's bounding box. The X coordinate of this point represents the largest width and the Y coordinate of this point represents the largest height.
- const TGRect & -The minimum and maximum allowable sizes for the window's bounding box. The top left point specifies the minimum resize limit and the bottom right point specifies the maximum resize limit.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::GetResizeLimits
- void GetResizeLimits (TGPoint & minSize, TGPoint & maxSize) const
- TGRect GetResizeLimits () const
Interface Category:
API.
Purpose:
Gets the minimum and maximum resize limits for the window. These functions are overloaded to take either two TGPoints, or pass back a TGRect where the top left point specifies the minimum resize limit and the bottom right point specifies the maximum resize limit.
Calling Context:
- You can call this function directly.
- You can call this function directly.
Parameters:
- TGPoint & minSize -The minimum allowable size for the window's bounding box as returned by this function. The X coordinate of this point represents the smallest width and the Y coordinate of this point represents the smallest height.
- TGPoint & maxSize -The maximum allowable size for the window's bounding box as returned by this function. The X coordinate of this point represents the largest width and the Y coordinate of this point represents the largest height.
- Takes no parameters.
Return Value:
- Returns a TGRect that is the minimum and maximum allowable sizes for the window's bounding box as returned by this function. The top left point specifies the minimum resize limit and the bottom right point specifies the maximum resize limit.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::operator=
TWindow & operator =(const TWindow &)
Interface Category:
API.
Purpose:
Assignment operator.
Calling Context:
Call this function by using the operator in an assignment statement.
Parameters:
- const TWindow & -The window to be copied.
Return Value:
A non-const reference to the left-hand side object.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::operator>>=
virtual TStream & operator >>=(TStream & towhere) const
Interface Category:
API.
Purpose:
Stream-out operator.
Calling Context:
Called to stream out data.
Parameters:
- TStream & towhere -The stream to which the object streams itself out.
Return Value:
Returns a reference to the stream the object streams itself out to.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::operator<<=
virtual TStream & operator <<= (TStream & fromwhere)
Interface Category:
API.
Purpose:
Stream-in operator.
Calling Context:
Called to stream in data.
Parameters:
- TStream & fromwhere -The stream from which the object streams itself in.
Return Value:
Returns a reference to the stream the object streams itself in from.
Exceptions:
Throws a TInvalidVersionError if the version of the object on the stream is unknown to the version of the shared library installed.
Concurrency:
In general, this class is not.
Other Considerations:
None.
TWindow ()
Interface Category:
API.
Purpose:
Default constructor.
Calling Context:
Called by the stream-in operators.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
TWindow is an abstract base class--all the constructors are protected. Do not instantiate this class.
Member Function: TWindow::HandleShow
virtual void HandleShow ()
Interface Category:
API.
Purpose:
HandleShow is part of TWindow's show and hide protocol. Developers should override the HandleShow function to implement specific show behavior. The default does nothing.
Calling Context:
Called from the Show function.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
This function is protected.
Member Function: TWindow::HandleHide
virtual void HandleHide ()
Interface Category:
API.
Purpose:
HandleHide is part of TWindow's show and hide protocol. Developers should override the HandleHide function to implement specific hide behavior. The default does nothing.
Calling Context:
Called from the Hide function.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
This function is protected.
Member Function: TWindow::HandleOpen
virtual void HandleOpen ()
Interface Category:
API.
Purpose:
HandleOpen is part of TWindow's open and close protocol. Developers should override the HandleOpen function to implement specific open behavior. The default does nothing.
Calling Context:
Called from the Open function.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
This function is protected.
Member Function: TWindow::HandleClose
virtual void HandleClose ()
Interface Category:
API.
Purpose:
HandleClose is part of TWindow's open and close protocol. Developers should override the HandleClose function to implement specific close behavior. The default does nothing.
Calling Context:
Called from the Close function.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
This function is protected.
Member Function: TWindow::HandleEnable
virtual void HandleEnable ()
Interface Category:
API.
Purpose:
HandleEnable is part of TWindow's enable and disable protocol. Developers should override the HandleEnable function to implement specific enable behavior. The default does nothing.
Calling Context:
Called from the Enable function. Enable is typically called by an activation policy object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
This function is protected.
Member Function: TWindow::HandleDisable
virtual void HandleDisable ()
Interface Category:
API.
Purpose:
HandleDisable is part of TWindow's enable and disable protocol. Developers should override the HandleDisable function to implement specific disable behavior. The default does nothing.
Calling Context:
Called from the Disable function. Disable is typically called by an activation policy object.
Parameters:
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
This function is protected.
Member Function: TWindow::HandleHilite
virtual void HandleHilite (bool hilite)
Interface Category:
API.
Purpose:
HandleHilite is part of TWindow's highlight protocol. Developers should override the HandleHilite function to implement specific highlight behavior. The default does nothing.
Calling Context:
Called from the Hilite function. Hilite is typically called by an activation policy object.
Parameters:
- bool hilite -Indicates whether to highlight or unhighlight the window.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
This function is protected.
Member Function: TWindow::SetWindowSizeAndLocation
virtual void SetWindowSizeAndLocation (const TGPoint & desiredSize, const TGPoint & location)
Interface Category:
API.
Purpose:
This is semantically equivalent to calling SetWindowSize followed by MoveWindowTo, but is more efficient and avoids flicker.
Calling Context:
You can call this function directly.
Parameters:
- const TGPoint & desired size -The new width and height for the window's bounding box. The X coordinate of the point is the width, and the Y coordinate of the point is the height.
- const TGPoint & location -The new location for the upper left corner of the window. This point is specified in the parent view's coordinate system.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::GetWindowLocation
virtual TGPoint GetWindowLocation () const
Interface Category:
API.
Purpose:
Returns the location of the window within its parent view.
Calling Context:
You can call this function directly.
Parameters:
Return Value:
The location of the upper left corner of the window, specified in this parent view's coordinate system.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::IsHilited
bool IsHilited () const
Interface Category:
API.
Purpose:
Determines if a window is highlighted or not.
Hilite is part of TWindow's highlight protocol. Developers should override the HandleHilite function to implement specific highlight behavior.
Calling Context:
This function is typically called directly by an activation policy object or while drawing in a drived class, rather than by developer code.
Parameters:
Return Value:
Returns true if the window is highlighted, false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
Member Function: TWindow::Hilite
void Hilite (bool hilite =true)
Interface Category:
API.
Purpose:
Highlights or unhighlights the window according to the specified input parameter. Enables the window if hilite is true, and the window is not already enabled.
Hilite is part of TWindow's highlight protocol. Developers should override the HandleHilite function to implement specific highlight behavior.
Calling Context:
This function is typically called directly by an activation policy object rather than by developer code.
Parameters:
- bool hilite =true -Highlight the window (if true), or unhighlight the window (if false).
Return Value:
None.
Exceptions:
Throws a kWindowNotOpen exception if the window is not open.
Concurrency:
In general, this class is not.
Other Considerations:
None.
Member Function: TWindow::IsEnabled
bool IsEnabled () const
Interface Category:
API.
Purpose:
Determines if a window is enabled or not.
IsEnabled is part of TWindow's enable and disable protocol. Developers should override the HandleEnable or HandleDisable functions to implement specific enable or disable behavior.
Calling Context:
This function is typically called directly by an activation policy object rather than by developer code.
Parameters:
Return Value:
Returns true if the window is enabled, false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
Overrides inherited MControl function.
Member Function: TWindow::SetEnabled
virtual void SetEnabled (bool enabled)
Interface Category:
API.
Purpose:
This is an MControl override to enable or disable the window. It calls Enable if enabled is true, or Disable if enabled is false.
Calling Context:
This function is typically called directly by an activation policy object rather than by developer code.
Parameters:
- bool enabled -The flag indicating whether to enable or disable this window--true enables the window; false disables it.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
Overrides inherited MControl function.
Member Function: TWindow::GetVisibility
virtual bool GetVisibility () const
Interface Category:
API.
Purpose:
Calls IsShown to determine whether or not this window is visible.
Calling Context:
Clients or derived classes can call this function directly.
Parameters:
Return Value:
Returns true if this window is visible, false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
Overrides inherited TView and MControl functions.
Member Function: TWindow::SetVisibility
virtual void SetVisibility (bool visible)
Interface Category:
API.
Purpose:
Sets this window to be visible or invisible. Calls Open and Show if visible is true. Calls Hide if visible is false.
Calling Context:
Clients or derived classes can call this function directly.
Parameters:
- bool visible -The flag indicating whether this window should become visible or invisible--true makes the window visible; false makes it invisible.
Return Value:
None.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
In general, this class is not.
Other Considerations:
Overrides inherited TView and MControl functions.
Member Function: TWindow::IsShown
bool IsShown () const
Interface Category:
API.
Purpose:
Determines if a window is visible or not.
IsShown is part of TWindow's show and hide protocol. Developers should override the HandleShow and HandleHide functions to implement specific show or hide behavior.
Calling Context:
You can call this function directly.
Parameters:
Return Value:
Returns true if the window is visible, false otherwise.
Exceptions:
Throws no exceptions, passes all exceptions through.
Concurrency:
Multithread safe.
Other Considerations:
None.
Member Function: TWindow::IsOpen
bool IsOpen () const
Interface Category:
API.
Purpose:
Determines if window is open or closed.
IsOpen is part of TWindow's open and close protocol. Developers should override the HandleOpen and HandleClose functions to implement specific open or close behavior.
Calling Context:
You can call this function directly.
Parameters:
Return Value:
Returns true if the window is open, false otherwise.
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.