Class: TGUIEmbedderModelSelection

Declaration: GUICompoundDocumentEmbedder.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TModelSelection, MDataExchanger, MEmbeddedComponentAccessor

Inherited By:

TGUIEmbedderModelSelectionFor

Purpose:

The class supports selection on a TGUIEmbedderModel. It provides protocol and implementation for selecting embedded components. It derives from MDataExchanger and MEmbeddedComponentAccessor and implements the protocol associated with these mixin classes. This enables the data exchange and frame layout command suites.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

Developers will usually derive from TGUIEmbedderSelectionFor rather than this class.

Concurrency:

Multithread safe.

Resource Use:

No special requirements.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::TGUIEmbedderModelSelection

TGUIEmbedderModelSelection (const TModelReference & theModelRef)
TGUIEmbedderModelSelection (const TGUIEmbedderModel & theModel)
TGUIEmbedderModelSelection (const TGUIEmbedderModelSelection &)
TGUIEmbedderModelSelection ()

Interface Category:

API.

Purpose:

Creates a selection on the specified model.
Creates a selection on the specified model.
Copy constructor.
Default constructor.

Calling Context:

Called by any client object.
Called by any client object.
Called to copy an object.
Called by the stream-in operators and

Parameters:

const TModelReference & theModelRef -The model to select.
const TGUIEmbedderModel & theModel -The model to select.
const TGUIEmbedderModelSelection & -The selection to copy.
Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::~TGUIEmbedderModelSelection

virtual ~ TGUIEmbedderModelSelection ()

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:

None.

Member Function: TGUIEmbedderModelSelection::SelectComponent

virtual void SelectComponent (const TDocumentComponentReference &)

Interface Category:

API.

Purpose:

Selects the specified component. The selection does not verify that this component is a child of the selected model.

Calling Context:

Called by any client object.

Parameters:

const TDocumentComponentReference & -The component to select.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::DeselectComponent

virtual void DeselectComponent (const TDocumentComponentReference &)

Interface Category:

API.

Purpose:

Deselects the specified component. The component may or may not have been previously selected.

Calling Context:

Called by any client object.

Parameters:

const TDocumentComponentReference & -The component to deselect.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::DeselectAllComponents

virtual void DeselectAllComponents ()

Interface Category:

API.

Purpose:

Deselects any and all components selected by this selection.

Calling Context:

Called by any client object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::GetSelectedComponentCount

virtual long GetSelectedComponentCount () const

Interface Category:

API.

Purpose:

Returns the count of components selected by this selection.

Calling Context:

Called by any client object.

Parameters:

Takes no parameters.

Return Value:

Returns the count of selected components.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::IsSelected

virtual bool IsSelected (const TDocumentComponentReference &) const

Interface Category:

API.

Purpose:

Determines if a specific component is selected by this selection.

Calling Context:

Called by any client object.

Parameters:

const TDocumentComponentReference & -The component to test for selection.

Return Value:

Returns true if the specified component is selected.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::GetSelectedComponents

virtual void GetSelectedComponents (TCollectionOf < TDocumentComponentReference > &) const

Interface Category:

API.

Purpose:

Returns a list of all the components selected by this selection.

Calling Context:

Called by any client.

Parameters:

TCollectionOf < TDocumentComponentReference > & -The component references as returned by this function. The caller owns the reference objects.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::GetComponentArea

virtual void GetComponentArea (const TDocumentComponentReference &, TGArea &) const

Interface Category:

API.

Purpose:

Returns the area associated with a component in the model specified by this selection. Gets the area from the TComponentArea for the specified component.

Calling Context:

Called by any client object.

Parameters:

const TDocumentComponentReference & -A reference to the component.
TGArea & -The area associated with the component as returned by this function.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::SetComponentArea

virtual void SetComponentArea (const TDocumentComponentReference &, const TGArea &)

Interface Category:

API.

Purpose:

Sets the area associated with a component in the model specified by this selection.

Calling Context:

Called by any client object.

Parameters:

const TDocumentComponentReference & -A reference to the component.
TGArea & -The new area for the component.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::AddInterests

virtual void AddInterests (TSetOf < TInterest > & set)

Interface Category:

API.

Purpose:

Returns interests to connect for notification on changes to the area associated with components in the model selected by this selection. Returns the model's GetComponentAreaChangedInterest().

Calling Context:

Called by an client object.

Parameters:

TSetOf < TInterest > & set -The set of interests as returned by this function. The caller owns the interests.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::DeselectAll

virtual void DeselectAll ()

Interface Category:

API.

Purpose:

Deselects all data selected by this selection. IsEmpty must return true after this call.

Calling Context:

Called by any client object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::SelectWholeModel

virtual void SelectWholeModel ()

Interface Category:

API.

Purpose:

Selects all the data in the model associated by this selection. This is only the data in the model at the time the function is called. IsEmpty must return false after this call.

Calling Context:

Called by any client object.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::CreateAvailableTypesList

virtual void CreateAvailableTypesList (TSequenceOf < TTypeDescription > & theTypes) const

Interface Category:

API.

Purpose:

Creates and returns a list of model types this selection can produce. The order is most to least preferred.

Calling Context:

Called as part of type negotiation for data exchange.

Parameters:

TSequenceOf < TTypeDescription > & theTypes -The type descriptions as returned by this function. The caller owns the types.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::ChooseTypes

virtual void ChooseTypes (const TSequenceOf < TTypeDescription > & theChoices, TSequenceOf < TTypeDescription > & theChosenTypes) const

Interface Category:

API.

Purpose:

Choose all the types from theChoices that this selection can accept. The order is most to least preferred.

Calling Context:

Called as part of type negotiation for data exchange.

Parameters:

const TSequenceOf < TTypeDescription > & theChoices -The types available.
TSequenceOf < TTypeDescription > & theChosenTypes -The types this selection can accept. Must be alias to TTypeDescriptions in theChoices.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::GetModelForReading

const TGUIEmbedderModel * GetModelForReading () const

Interface Category:

API.

Purpose:

Returns a const pointer to the model specified by this selection.

Calling Context:

Called by any client object.

Parameters:

Takes no parameters.

Return Value:

Returns the model.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::GetModelForWriting

TGUIEmbedderModel * GetModelForWriting () const

Interface Category:

API.

Purpose:

Returns a non-const pointer to the model specified by this selection.

Calling Context:

Called by any client object.

Parameters:

Takes no parameters.

Return Value:

Returns the model.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::operator=

TGUIEmbedderModelSelection & operator =(const TGUIEmbedderModelSelection &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

Called when an object is assigned to another compatible object.

Parameters:

const TGUIEmbedderModelSelection & -The right-hand side object.

Return Value:

Returns a 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: TGUIEmbedderModelSelection::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:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::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:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::HandleCopyData

virtual TModel * HandleCopyData (const TTypeDescription &) const

Interface Category:

API.

Purpose:

Copies the selected data in the specified type. The function creates the model of the appropriate type and then calls HandleCopyDataInto. If the type is not recognized by this class, HandleCreateModel is called to allow derived classes the opportunity to create the model.

Calling Context:

Called by CopyData.

Parameters:

const TTypeDescription & -The type to copy data in.

Return Value:

Returns the copy of the selected data.

Exceptions:

Throws TCompoundDocumentException::kTypeUnacceptable if the type is cannot be created by this selection.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::HandleCopyDataInto

virtual void HandleCopyDataInto (TModel &) const

Interface Category:

API.

Purpose:

Copies the selected data into the specified model. The model must be of a type chosen by ChooseTypes.

Calling Context:

Called by CopyDataInto.

Parameters:

TModel & -The model to copy the data into.

Return Value:

None.

Exceptions:

Throws TCompoundDocumentException::kTypeUnacceptable if the model is not of a type understood by this selection.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::HandleReplaceData

virtual TModel * HandleReplaceData (TModel * theData)

Interface Category:

API.

Purpose:

Replaces the data selected by this selection with new data.

Calling Context:

Called by ReplaceData

Parameters:

TModel * theData -The data to replace selected data.

Return Value:

Returns the data to be used to undo this operation.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::HandleOrphanData

virtual TModel * HandleOrphanData ()

Interface Category:

API.

Purpose:

Orphans the data selected by this selection.

Calling Context:

Called by OrphanData.

Parameters:

Takes no parameters.

Return Value:

Returns the orphaned data to be used to undo this operation.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::CreateSelectedComponentIterator

virtual TIteratorOver < TDocumentComponentReference > * CreateSelectedComponentIterator () const

Interface Category:

API.

Purpose:

Creates an iterator over references to all components selected by this selection.

Calling Context:

Called by derived classes.

Parameters:

Takes no parameters.

Return Value:

Returns the iterator.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::CopyDataIntoEmbedderModel

virtual void CopyDataIntoEmbedderModel (TEmbedderModel &) const

Interface Category:

API.

Purpose:

Copies selected data into an instance of TEmbedderModel.

Calling Context:

Called by HandleCopyDataInto and derived classes.

Parameters:

TEmbedderModel & -The model to copy data into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::CopyDataIntoGUIEmbedderModel

virtual void CopyDataIntoGUIEmbedderModel (TGUIEmbedderModel &) const

Interface Category:

API.

Purpose:

Copies selected data into an instance of TGUIEmbedderModel.

Calling Context:

Called by HandleCopyDataInto and derived classes.

Parameters:

TGUIEmbedderModel & -The model to copy data into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::MoveDataIntoGUIEmbedderModel

virtual void MoveDataIntoGUIEmbedderModel (TGUIEmbedderModel &)

Interface Category:

API.

Purpose:

Moves selected data into an instance of TGUIEmbedderModel. The data is moved out of the select model.

Calling Context:

Called by HandleOrphanData and derived classes.

Parameters:

TGUIEmbedderModel & -The model to move data into.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::MoveDataOutofEmbedderModel

virtual void MoveDataOutofEmbedderModel (TEmbedderModel &)

Interface Category:

API.

Purpose:

Moves data out of an instance of TEmbedderModel and into the selected model. A new TComponent area is created for each component moved from the TEmbedderModel.

Calling Context:

Called by HandleReplaceData and derived classes.

Parameters:

TEmbedderModel & -The model to move data from.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::MoveDataOutofGUIEmbedderModel

virtual void MoveDataOutofGUIEmbedderModel (TGUIEmbedderModel &)

Interface Category:

API.

Purpose:

Moves data out of an instance of TGUIEmbedderModel and into the selected model.

Calling Context:

Called by HandleReplaceData and derived classes.

Parameters:

TGUIEmbedderModel & -The model to move data from.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::HandleCreateModel

virtual TModel * HandleCreateModel (const TTypeDescription &) const

Interface Category:

API.

Purpose:

Creates an instance of a model of the specified type.

Calling Context:

Called by HandleCopyData.

Parameters:

const TTypeDescription & -The type of model to create.

Return Value:

Returns the created model or NIL if the type is not understood.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Not multithread safe.

Other Considerations:

None.

Member Function: TGUIEmbedderModelSelection::IsEmpty

bool IsEmpty () const

Interface Category:

API.

Purpose:

Indicates whether or not the selection is empty. The selection is considered empty if no embedded components are selected.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns true if empty, false otherwise.

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.