Class: TLayerableSurrogate

Declaration: SystemWindow.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TAbstractLayerableReference

Inherited By:

TSystemLayerSurrogate TSystemWindowSurrogate

Purpose:

TLayerableSurrogate is a functional, copyable, heavyweight reference to a window or layer. This is an abstract base class that is derived from TAbstractLayerableReference. TLayerableSurrogate is used as a common base for TSystemWindowSurrogate and TSystemLayerSurrogate. It is not intended that developers should create TLayerableSurrogate objects. Instead, you should derive classes from TLayerableSurrogate.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

TSystemWindowSurrogate and TSystemLayerSurrogate both derive from this class.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TLayerableSurrogate::~TLayerableSurrogate

virtual ~ TLayerableSurrogate ()

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:

This function does not affect the window or layer.

Member Function: TLayerableSurrogate::GetOwningThread

virtual void GetOwningThread (TThreadHandle & theThread) const

Interface Category:

API.

Purpose:

Gets the thread that created the window.

Calling Context:

Called when a client needs the thread that the window belongs to. Generally the WindowServer.

Parameters:

TThreadHandle & returnedThread -The owning thread. This is returned by the function.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLayerableSurrogate::CreateInterest

virtual TInterest * CreateInterest (const TToken & theChange) const

Interface Category:

API.

Purpose:

Creates a TSystemWindowInterest in this window or layer.

Calling Context:

Called by a client who wants to receive notification about this window or layer.

Parameters:

const TToken & theChange -The notification type that the client is interested in, and for which notification is sent.

Return Value:

A pointer to a TSystemWindowInterest.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLayerableSurrogate::Hide

void Hide ()

Interface Category:

API.

Purpose:

Hides the window or layer.

Calling Context:

Called when a client wants to make a window or layer invisible.

Parameters:

Takes no parameters.

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: TLayerableSurrogate::Show

void Show ()

Interface Category:

API.

Purpose:

Shows the window or layer.

Calling Context:

Called when a client wants to make the window or layer visible.

Parameters:

Takes no parameters.

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: TLayerableSurrogate::BringToFront

void BringToFront ()

Interface Category:

API.

Purpose:

Brings this window or layer to the front of its containing layer.

Calling Context:

Called by a client when they need the window or layer in front of others in containing layer.

Parameters:

Takes no parameters.

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: TLayerableSurrogate::SendToBack

void SendToBack ()

Interface Category:

API.

Purpose:

Sends this window or layer to the back of containing layer.

Calling Context:

Called by a client when they need the window or layer behind all others in containing layer.

Parameters:

Takes no parameters.

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: TLayerableSurrogate::MoveToFrontOf

bool MoveToFrontOf (const TAbstractLayerableReference & aWindow, bool doReparent =false)

Interface Category:

API.

Purpose:

Brings this window or layer in front of the specified window or layer.

Calling Context:

Called by a client to move the window or layer in front of another particular window or layer.

Parameters:

const TAbstractLayerableReference & aWindow -A reference to the other window or layer to move in front of.
bool doReparent =false -Set to false if the client wants this window or layer to remain in the same layer.

Return Value:

None.

Exceptions:

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

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLayerableSurrogate::MoveToBackOf

bool MoveToBackOf (const TAbstractLayerableReference & aWindow, bool doReparent =false)

Interface Category:

API.

Purpose:

Sends this window or layer behind the specified window or layer.

Calling Context:

Called by a client to move the window or layer behind another specified window or layer.

Parameters:

const TAbstractLayerableReference & aWindow -A reference to the other window or layer to move behind.
bool doReparent =false -Set to false if the client wants the window or layer to remain in the same layer.

Return Value:

None.

Exceptions:

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLayerableSurrogate::PutInDesktopLayer

bool PutInDesktopLayer (bool onTop =true)

Interface Category:

API.

Purpose:

Moves this window or layer to the root layer.

Calling Context:

Called if the client wants to put this window or layer in the root layer.

Parameters:

bool onTop =true -Set to true if window or layer is to be on top of other windows in the layer; otherwise, set to false if this window or layer is to be behind all others.

Return Value:

Returns true if successful; otherwise, returns false.

Exceptions:

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

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLayerableSurrogate::PutInLayer

bool PutInLayer (TSystemLayerSurrogate & newLayer, bool onTop =true)

Interface Category:

API.

Purpose:

Moves this window or layer to another layer.

Calling Context:

Called if the client wants to put this window or layer into a different layer.

Parameters:

TSystemLayerSurrogate & newLayer -A reference to the other layer to which this window or layer is to be added.
bool onTop =true -Set to true if this window or layer is to be added to the top of the new layer.

Return Value:

Returns true if successful; otherwise, returns false.

Exceptions:

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

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLayerableSurrogate::SetVisibility

void SetVisibility (bool makeVisible)

Interface Category:

API.

Purpose:

Sets the visibility state of the window or layer.

Calling Context:

Called to change the visibility state of the window or layer.

Parameters:

bool makeVisible -Set to true to make the window or layer visible; otherwise, set to false to make it not visible.

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: TLayerableSurrogate::TLayerableSurrogate

TLayerableSurrogate (const TLayerableSurrogate & otherWindow)
TLayerableSurrogate (const TLayerableReference & otherWindow)
TLayerableSurrogate (const TSystemLayerable & otherWindow)
TLayerableSurrogate ()

Interface Category:

API.

Purpose:

Copy constructor.
Copy from a reference.
Create from real window or layer.
Default constructor.

Calling Context:

Called to copy an object. Only for internal use by Copy. Developers should treat as protected.
Called to copy from a reference.
Called to create a from a real window or layer.
Only for internal use by Resurrect. Developers should treat as protected.

Parameters:

const TLayerableSurrogate & otherWindow -Surrogate to copy from.
const TLayerableReference & otherWindow -Reference to copy from.
const TSystemLayerable & otherWindow -Real Layerable to create from.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLayerableSurrogate::operator=

const TLayerableSurrogate & operator =(const TLayerableSurrogate & otherWindow)
const TLayerableSurrogate & operator =(const TLayerableReference & otherWindow)
const TLayerableSurrogate & operator =(const TSystemLayerable & otherWindow)

Interface Category:

API.

Purpose:

Assignment operator.
Convert from a reference.
Convert from real layerable.

Calling Context:

Called when an object is assigned to another compatible object.
Called to convert from a LayerableReference.
Called to convert from a Layerable.

Parameters:

const TLayerableSurrogate & otherWindow -Surrogate to copy from.
const TLayerableReference & otherWindow -Reference to convert from.
const TSystemLayerable & otherWindow -Real window or layer to convert from.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLayerableSurrogate::GetContainingLayer

TLayerableReference GetContainingLayer () const

Interface Category:

API.

Purpose:

Returns the layer that contains this window or layer.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the TLayerableReference containing layer for this window or layer.

Exceptions:

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

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLayerableSurrogate::operator<<=

virtual TStream & operator <<= (TStream &)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in window surrogate objects.

Parameters:

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

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLayerableSurrogate::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out window surrogate objects.

Parameters:

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

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TLayerableSurrogate::operator==

bool operator ==(const TLayerableSurrogate &) const

Interface Category:

API.

Purpose:

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

Calling Context:

Call this function directly.

Parameters:

const TLayerableSurrogate & -A reference to the other window or layer for the equality comparison.

Return Value:

Returns true if the specified window or layer identifier is equal to this window or layer identifier; 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.