Class: TSystemWindowSurrogate

Declaration: SystemWindow.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TLayerableSurrogate

Inherited By:

None.

Purpose:

TSystemWindowSurrogate is a functional, heavyweight reference to a window. This class provides a client with complete access to a window, except for creating and destroying the window. It is identical to the class TSystemWindow, although TSystemWindow also creates and destroys windows. TSystemWindowSurrogate uses semaphores to protect its data members, along with the cached vis area and time stamp.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

You would not normally derive from this class. Instead derive from TLayerableSurrogate.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TSystemWindowSurrogate::TSystemWindowSurrogate

TSystemWindowSurrogate (const TSystemWindowSurrogate & otherWindow)
TSystemWindowSurrogate (const TLayerableReference & otherWindow)
TSystemWindowSurrogate (const TSystemWindow & otherWindow)
TSystemWindowSurrogate ()

Interface Category:

API.

Purpose:

Copy constructor.
Create from a reference to a window.
Create from a real window.
Default constructor.

Calling Context:

Called to copy an object.
Called to create from a lightweight reference.
Called to create from the real window.
Called by the stream-in operators.

Parameters:

const TSystemWindowSurrogate & otherWindow -Other surrogate to copy from.
const TLayerableReference & otherWindow -Reference to create from.
const TSystemWindow & otherWindow -Real window to create from.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws TSystemWindowException(kReferenceToWrongLayerable) if otherWindow in constructor case (2) refers to a layer.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSystemWindowSurrogate::~TSystemWindowSurrogate

virtual ~ TSystemWindowSurrogate ()

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:

Not multithread safe.

Other Considerations:

Has no effect on window.

Member Function: TSystemWindowSurrogate::operator=

const TSystemWindowSurrogate & operator =(const TSystemWindowSurrogate & otherWindow)
const TSystemWindowSurrogate & operator =(const TLayerableReference & otherWindow)
const TSystemWindowSurrogate & operator =(const TSystemWindow & otherWindow)

Interface Category:

API.

Purpose:

Assignment operator.
Convert from reference.
Convert from real window.

Calling Context:

Called when an object is assigned to another compatible object.
Called to convert from a reference.
Called to convert from a real window.

Parameters:

const TSystemWindowSurrogate & otherWindow -Surrogate to copy from.
const TLayerableReference & otherWindow -Reference to convert from.
const TSystemWindow & otherWindow -Real window to convert from.

Return Value:

A non-const reference to the left-hand side object.

Exceptions:

Throws TSystemWindowException(kReferenceToWrongLayerable) if otherWindow in assignment case (2) refers to a layer.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSystemWindowSurrogate::GetVisArea

void GetVisArea (TGArea & area ) const

Interface Category:

API.

Purpose:

Gets the visible area of the window.

Calling Context:

Called when a client wants the visible area of the window.

Parameters:

TGArea & area -The visible area of the window, returned by the function.

Return Value:

None.

Exceptions:

Throws TSystemWindowException(kThisLayerableNonexistant) if the window referred to by this surrogate does not exist.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSystemWindowSurrogate::GetVisAreaTimeStamp

TPseudoTimeStamp GetVisAreaTimeStamp () const

Interface Category:

API.

Purpose:

Gets the time stamp of the visible area.

Calling Context:

Called to determine the time stamp of the visible area. This is used to determine if the visible area has changed.

Parameters:

Takes no parameters.

Return Value:

A times tamp representing the version of the visible area.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSystemWindowSurrogate::SetExtent

void SetExtent (const TGArea &, bool addToUpdate)

Interface Category:

API.

Purpose:

Sets the extent of the window.

Calling Context:

Called to change the position, shape, and/or size of a window.

Parameters:

const TGArea & -A reference to the new area of the window.
bool addToUpdate -Set to true to generate update notifications.

Return Value:

None.

Exceptions:

Throws TSystemWindowException(kThisLayerableNonexistant) if the window referred to by this surrogate does not exist.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSystemWindowSurrogate::GetWindowPort

TGrafPort * GetWindowPort () const

Interface Category:

API.

Purpose:

Gets a GrafPort for the window.

Calling Context:

Called by a client that needs to draw to the window.

Parameters:

Takes no parameters.

Return Value:

A pointer to a GrafPort derivative.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

This port automatically clips to the window's visible area. The port also synchronizes with the Window Server. Keep in mind that an attempt to draw to the port after this window is destroyed generates either a TSystemWindowException(kThisLayerableNonexistant) or a TSemaphoreException.

Member Function: TSystemWindowSurrogate::SetBackground

void SetBackground (const TAttributeState & backFill, const MDrawable & newBackground, EBGStyle newStyle =TSystemWindowSurrogate :: kCentered)
void SetBackground (const TAttributeState & backFill)

Interface Category:

API.

Purpose:

Sets the background for the window using the constant backFill, the background value from MDrawable, and the style tag for centering the window.
Sets the background for the window to the constant backFill.

Calling Context:

Call this function directly to set all three parameters for the new background.
Call this function directly to only set the new background fill.

Parameters:

const TAttributeState & backFill -A reference to the background fill value.
const MDrawable & newBackground -A reference to the MDrawable background value.
EBGStyle newStyle =TSystemWindowSurrogate :: kCentered -Sets the window style to centered, rather than scaled or tiled.
const TAttributeState & backFill -A reference to the background fill value.

Return Value:

None.

Exceptions:

Throws a TSystemWindowException(kThisLayerableNonexistant) exception if this window does not exist.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSystemWindowSurrogate::MoveExtent

void MoveExtent (const TGPoint &)

Interface Category:

API.

Purpose:

Repositions the window.

Calling Context:

Call this function directly.

Parameters:

const TGPoint & -The difference between the windowÕs old location and the new location of the window.

Return Value:

None.

Exceptions:

Throws a TSystemWindowException(kThisLayerableNonexistant) exception if the layer or window does not exist.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSystemWindowSurrogate::GetExtent

void GetExtent (TGArea & area) const

Interface Category:

API.

Purpose:

Returns the current extent of the window.

Calling Context:

Call this function directly.

Parameters:

TGArea & area -A reference to the area of the window, which is set by the function.

Return Value:

None.

Exceptions:

Throws a TSystemWindowException(kThisLayerableNonexistant) if the window or layer does not exist.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSystemWindowSurrogate::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in system window surrogate objects.

Parameters:

TStream & -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 no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TSystemWindowSurrogate::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out system window surrogate objects.

Parameters:

TStream & -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:

Not multithread safe.

Other Considerations:

None.

Member Function: TSystemWindowSurrogate::operator==

bool operator ==(const TSystemWindowSurrogate &) const

Interface Category:

API.

Purpose:

Tests for equality between this window and the specified window. Windows are equal if and only if their identifiers are equal.

Calling Context:

Call this function directly.

Parameters:

const TSystemWindowSurrogate & -A reference to the other window that is to be compared to this window.

Return Value:

Returns true if the identifiers for the two windows are equal; otherwise, returns false.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

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