Class: TDocumentPresenter

Declaration: BasicDocument.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

None.

Inherited By:

TGUIDocumentPresenter

Purpose:

TDocumentPresenter is an abstract base class for transient document presentations. Document presenters are transient objects and are not stored persistently.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Derived classes provide concrete presenters for specific types of documents. Derived classes must override the pure virtual functions HandleOpen and HandleClose.

Concurrency:

Not multithread safe.

Resource Use:

No special requirements.

Member Function: TDocumentPresenter::TDocumentPresenter

TDocumentPresenter (const TDocumentReference &, const TPlaceReference&)

Interface Category:

API.

Purpose:

Creates a document presenter on the specified document in the specified place.

Calling Context:

Called only by derived classes.

Parameters:

const TDocumentReference & -The document being presented.
const TPlaceReference & -The place in which the document is being presented.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This constructor is protected. Preconditions: Assertion (const TDocumentReference& is for a valid document). Assertion (const TPlaceReference& is for a valid place).

Member Function: TDocumentPresenter::~TDocumentPresenter

virtual ~ TDocumentPresenter ()

Interface Category:

API.

Purpose:

Destructor.

Calling Context:

Called to destroy the document presenter.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentPresenter::Open

void Open() ;

Interface Category:

API.

Purpose:

Opens the presenter. For example, a GUI-based presenter would create and open its document window at this time.

Calling Context:

Called by a Place to open the presenter on the document.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentPresenter::Close

void Close() ;

Interface Category:

API.

Purpose:

Closes the presenter. For example, a GUI-based presenter would close and delete its document window.

Calling Context:

Called by a Place to close the presenter on the document.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentPresenter::Print

void Print (const TPrinter &)

Interface Category:

API.

Purpose:

Prints this document presenter to the specified printer.

Calling Context:

Call this function directly.

Parameters:

const TPrinter & -The printer to which to print this document presenter.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentPresenter::RequestClose

void RequestClose() ;

Interface Category:

API.

Purpose:

Requests that the presenter be closed by the owning Place. The presenter is not closed immediately by this function, but rather when the Place calls close.

Calling Context:

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: TDocumentPresenter::IsOpen

bool IsOpen() const ;

Interface Category:

API.

Purpose:

Determines whether the presenter is open.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if the presenter is open; false otherwise.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentPresenter::GetReference

TDocumentPresenterReference GetReference() const ;

Interface Category:

API.

Purpose:

Returns an address-space independent reference to this presenter. The reference is good for as long as this presenter exists in memory.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a reference to this presenter.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentPresenter::GetPresentingPlace

TPlaceReference GetPresentingPlace() const ;

Interface Category:

API.

Purpose:

Returns a reference to the place in which this presenter is presenting.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a reference to the place containing this presenter.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentPresenter::GetPresenterSessionStore

TPresenterSessionStore* GetPresenterSessionStore() const ;

Interface Category:

API.

Purpose:

Returns an alias to the presenter session store for this presenter. The store can be used to store place/user-specific information for this presenter.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

TPresenterSessionStore* -An alias to the presenter session store for this presenter. The alias is good for the lifetime of the presenter.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentPresenter::GetLocale

TLocale GetLocale () const

Interface Category:

API.

Purpose:

Returns the locale for this document presenter.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns the locale for this document presenter.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentPresenter::Adopt

static void Adopt (TDocumentPresenter *)

Interface Category:

API.

Purpose:

Adopts the specified TDocumentPresenter. This class maintains a dictionary of document presenter and document presenter reference pairs. This static function along with Orphan, Lookup, and LookupFor provide for static lookup of local TDocumentPresenters. This function places the specified TDocumentPresenter and its reference into the dictionary.

Calling Context:

Call this function directly.

Parameters:

TDocumentPresenter * -The document presenter to adopt.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentPresenter::Orphan

static TDocumentPresenter * Orphan (const TDocumentPresenterReference &)

Interface Category:

API.

Purpose:

Orphans the specified TDocumentPresenter. This class maintains a dictionary of document presenter and document presenter reference pairs. This static function along with Orphan, Lookup, and LookupFor provide for static lookup of local TDocumentPresenters. This function locates the reference in the dictionary, deletes it, and returns the document presenter that was paired with it in the dictionary.

Calling Context:

Call this function directly.

Parameters:

const TDocumentPresenterReference & -The object to orphan.

Return Value:

Returns the document presenter associated with the orphaned reference, or NIL if it wasn't in the dictionary.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentPresenter::Lookup

static TDocumentPresenter * Lookup (const TDocumentPresenterReference &)

Interface Category:

API.

Purpose:

Looks up the specified reference in the dictionary. This class maintains a dictionary of document presenter and document presenter reference pairs. This static function along with Orphan, Lookup, and LookupFor provide for static lookup of local TDocumentPresenters. This function locates the reference in the dictionary, and returns the document presenter that was paired with it in the dictionary.

Calling Context:

Call this function directly.

Parameters:

const TDocumentPresenterReference & -The reference to look up in the dictionary.

Return Value:

Returns the document presenter associated with the specified reference.

Exceptions:

Throws TDocumentException::kNILObject if the reference was located in the dictionary and its document presenter was NIL.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentPresenter::LookupFor

static TDocumentPresenter * LookupFor (const TDocumentReference &)

Interface Category:

API.

Purpose:

Looks up the document presenter for the specified document in the dictionary. This class maintains a dictionary of document presenter and document presenter reference pairs. This static function along with Orphan, Lookup, and LookupFor provide for static lookup of local TDocumentPresenters.

Calling Context:

Call this function directly.

Parameters:

const TDocumentReference & -The document for whom to look up a document presenter in the dictionary.

Return Value:

Returns the document presenter found, or NIL.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentPresenter::HandleOpen

virtual void HandleOpen() =0 ;

Interface Category:

API.

Purpose:

Creates presenter-specific objects such as windows and menus, and opens the presenter.

Calling Context:

Called by Open.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

This function is a pure virtual function and must be overridden by classes deriving from TDocumentPresenter. None.

Member Function: TDocumentPresenter::HandleClose

virtual void HandleClose() =0 ;

Interface Category:

API.

Purpose:

Closes the presenter and deletes presenter-specific objects.

Calling Context:

Called by Close.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TDocumentPresenter::HandlePrint

virtual void HandlePrint (const TPrinter &)

Interface Category:

API.

Purpose:

Prints the document presenter to the specified printer. This function is called from Print and performs the actual printing.

Calling Context:

Called from Print.

Parameters:

const TPrinter & -The printer to which to print the document presenter.

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.