Class: TEmbedderTextView

Declaration: EmbedderText.h

Taxonomy Categories:

Member Functions:

Interface Category:

API.

Inherits From:

TDocumentTextView

Inherited By:

None.

Purpose:

Derived from TDocumentTextView, this is a specialized text view that supports embedded document components. It creates, deletes, and positions the TFrameView used to display the embedded components. It is designed to be used in conjunction with TEmbedderTextModel and TEmbedderTextSelection.

Instantiation:

Allocate on the heap or the stack.

Deriving Classes:

There are no special requirements for deriving classes.

Concurrency:

Multithread safe. Uses Document Frameworks concurrency mechanism.

Resource Use:

No special requirements.

Member Function: TEmbedderTextView::TEmbedderTextView

TEmbedderTextView (TGUIBundle * theBundle)
TEmbedderTextView ()
TEmbedderTextView (const TEmbedderTextView & other)

Interface Category:

API.

Purpose:

Constructor for creating a document text view with the specified bundle attributes.
Default constructor.
Copy constructor.

Calling Context:

Call this function directly.
Called by the stream-in operators. This constructor is protected.
Called to copy an object. This constructor is protected. Note that views cannot be copied or assigned.

Parameters:

TGUIBundle * theBundle -The bundle to be associated with the view.
Takes no parameters.
const TEmbedderTextView & other -The object to copy.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::~TEmbedderTextView

virtual ~ TEmbedderTextView ()

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:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::GetEmbedderTextModel

virtual const TEmbedderTextModel * GetEmbedderTextModel () const

Interface Category:

API.

Purpose:

Provides access to the model associated with this view as a TEmbedderTextModel.

Calling Context:

Called by clients who need access to the model.

Parameters:

Takes no parameters.

Return Value:

A const pointer to a TEmbedderTextModel. If the model associated with this view is another subtype, this function returns nil.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

The caller must acquire a TDocumentComponentReadEntry or a TTextRepresentationReadEntry before calling this function.

Other Considerations:

None.

Member Function: TEmbedderTextView::AdoptCurrentSelection

virtual void AdoptCurrentSelection (MTextSelection * selection)

Interface Category:

API.

Purpose:

Adopts the selection object and sets it as the current selection.

Calling Context:

Call this function directly.

Parameters:

MTextSelection * selection -The new current selection to be adopted.

Return Value:

None.

Exceptions:

Throws TTextEditException::kInvalidSelectionType if the selection is not a TEmbedderTextSelection.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::GetTextSelection

virtual const MTextSelection * GetTextSelection () const

Interface Category:

API.

Purpose:

Provides read access to the current selection.

Calling Context:

Call this function directly.

Parameters:

Takes no parameters.

Return Value:

Returns a const pointer to the current selection. Returns nil if the current selection is not a TEmbedderTextSelection.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleAfterConnectionToViewRoot

virtual void HandleAfterConnectionToViewRoot ()

Interface Category:

API.

Purpose:

Performs setup actions required after connection to the view root. Calls the inherited function and connects for component notification. Creates initial views to display the components embedded in the model.

Calling Context:

Called by the View system after the view has been connected to the root.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleBeforeDisconnectionFromViewRoot

virtual void HandleBeforeDisconnectionFromViewRoot ()

Interface Category:

API.

Purpose:

Performs cleanup actions required after disconnection from the view root. Calls the inherited functions and disconnects for component notification. Removes the subviews for embedded components from the view hierarchy.

Calling Context:

Called by the View system before the view has been disconnected from the view hierarchy.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::CreateComponentView

virtual void CreateComponentView (const TDocumentComponent &, const TGRect &)

Interface Category:

API.

Purpose:

Creates the TFrameView objects used to display the embedded components. Sets the initial state of the view object to selected if a component falls within the current selection. Adds the frame view into the view hierarchy.

Calling Context:

Called by HandleAfterConnectionToViewRoot.

Parameters:

const TDocumentComponent & -The document component for which to create a TFrameView.
const TGRect & -The desired size of the frame view.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::DeleteComponentView

virtual void DeleteComponentView (const TDocumentComponentReference &)

Interface Category:

API.

Purpose:

Given a document component reference, orphans the frame view used to to display that document component from the view hierarchy. Deletes the storage for the view.

Calling Context:

Called by HandleRemoveComponent.

Parameters:

const TDocumentComponentReference & -The reference for the component for which the view is to be removed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::UpdateComponentView

virtual void UpdateComponentView (const TDocumentComponent &, const TGRect & area)

Interface Category:

API.

Purpose:

Changes the area and/or location of an embedded frame view.

Calling Context:

Called by HandleComponentAreaChanged.

Parameters:

const TDocumentComponent & -The component for which the view should be changed.
const TGRect & area -The new location and size.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::GetComponentViewArea

virtual TGRect GetComponentViewArea (const TDocumentComponent &) const

Interface Category:

API.

Purpose:

Given a document component, returns its size and position for the purpose of displaying the component in a TFrameView. To determine the location of the view, this function finds the insertion offset of the character that represents the component, then maps it to a view coordinate. The size is determined by calling TEmbedderTextModel::GetComponentSize. Clients who want to position the components differently can override this function.

Calling Context:

Called internally by TEmbedderTextView functions who need to create or change embedded frame views.

Parameters:

const TDocumentComponent & -The component for which to retrieve the view area.

Return Value:

Returns a TGRect that represents the componentÕs size and location.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::ChoosePreferredType

virtual bool ChoosePreferredType (const TGPoint & whereDropped, const TSequenceOf < TTypeDescription > & availableTypes, TTypeDescription & chosenType) const

Interface Category:

API.

Purpose:

Sets the chosenType to the preferred type description based on the sequence of available types. Calls the inherited function from TDocumentTextView to accept text types. If the type is not text, this function is specialized to accept TEmbedderModel as a type.

Calling Context:

Called by the Drag and Drop Framework.

Parameters:

const TGPoint & whereDropped -The location at which an item was dropped.
const TSequenceOf < TTypeDescription > & availableTypes -The list of available types.
TTypeDescription & chosenType -The type that has been chosen.

Return Value:

Returns true if the drop item is of an acceptable type. That is, it is either text or an embedder model.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::AcceptDrop

virtual bool AcceptDrop (const TGPoint & whereDropped, const TTypeDescription & theType, const TScrapItem & theItem)

Interface Category:

API.

Purpose:

Handles item dropped into this view. Calls the inherited function to accept text types. If the drop item is not text, this function accepts embedder model. The embedder model is copied and adopted into the TEmbedderTextModel associated with this view.

Calling Context:

Called by the Drag and Drop Framework.

Parameters:

const TGPoint & whereDropped -The location at which an item was dropped.
const TTypeDescription & theType -The type of the dropped item.
const TScrapItem & theItem -The dropped item.

Return Value:

Returns true if the dropped item is acceptable. That is, it is either text or an embedder model.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::operator=

TEmbedderTextView & operator =(const TEmbedderTextView &)

Interface Category:

API.

Purpose:

Assignment operator.

Calling Context:

This function should not be called because views cannot be assigned.

Parameters:

const TEmbedderTextView & -The source object.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleActivate

virtual void HandleActivate ()

Interface Category:

API.

Purpose:

Called to do any processing necessary when the view is activated. Calls the inherited function from TDocumentTextView. If the current selection contains any components that are displayed in this view, this functions sets the status of the subframe views to selected.

Calling Context:

Called by the View system or derived classes.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleDeactivate

virtual void HandleDeactivate ()

Interface Category:

API.

Purpose:

Called to do any processing necessary when the view is activated. Calls the inherited function from TDocumentTextView. Sets all subframe view to the unselected state.

Calling Context:

Called by the View system.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleTextChanged

virtual void HandleTextChanged (const TNotification &)

Interface Category:

API.

Purpose:

The notification handler for changes in the text representation. In addition to the processing done by calling the inherited function, it repositions all embedded subviews if the location of their representative character has changed.

Calling Context:

Called by the Notificaion Framework when a text changed notification is received.

Parameters:

const TNotification & -The text change notification.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleConnectForNotification

virtual void HandleConnectForNotification ()

Interface Category:

API.

Purpose:

Connects for notification from the text model. In addition to the text-related notification initiated by calling the inherited function, it also connects for component-added, component-removed, and component-changed notification.

Calling Context:

Called by HandleAfterConnectionToViewRoot.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleDisconnectNotification

virtual void HandleDisconnectNotification ()

Interface Category:

API.

Purpose:

Disconnects notification from the text model. In addition to the text related notification initiated by calling the inherited function, it also disconnects notification for component-added, component-removed, and component-changed.

Calling Context:

Called by HandleBeforeDisconnectFromViewRoot.

Parameters:

Takes no parameters.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleAddedComponent

virtual void HandleAddedComponent (const TNotification &)

Interface Category:

API.

Purpose:

Notification handler for when a document component is added. Creates a TFrameView to display the new component by calling CreateComponentView.

Calling Context:

Called by the Notificaion Framework when a document component is added.

Parameters:

const TNotification & -The component-added notification.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleRemovedComponent

virtual void HandleRemovedComponent (const TNotification &)

Interface Category:

API.

Purpose:

Notification handler for when a document component is removed. Deletes the frame view for this component by calling DeleteComponentView.

Calling Context:

Called by the Notificaion Framework when a document component is removed.

Parameters:

const TNotification & -The component-removed notification.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleComponentAreaChanged

virtual void HandleComponentAreaChanged (const TNotification &)

Interface Category:

API.

Purpose:

Notification handler for when the size or location of a document component changes. Changes the size and location of the frame view for this component by calling UpdateComponentView.

Calling Context:

Called by the Notificaion Framework when a component area changed notification is received.

Parameters:

const TNotification & -The component area changed notification.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleCreateComponentView

virtual TFrameView * HandleCreateComponentView (const TDocumentComponent & comp, const TGRect & viewRect) const

Interface Category:

API.

Purpose:

Creates and returns a TFrameView that is of size viewRect and is used to display the document component passed in as a parameter. Sets the initial selected state to false. This function can be overridden to create a different type of TFrameView.

Calling Context:

Called by CreateComponentView.

Parameters:

const TDocumentComponent & comp -The component for which a view is created.
const TGRect & viewRect -The desired size of the view.

Return Value:

A pointer to the newly created TFrameView. The caller assumes storage for the returned object.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleUpdateComponentAreaView

virtual void HandleUpdateComponentAreaView (const TGRect &, TFrameView & theEmbeddedComponentView)

Interface Category:

API.

Purpose:

Changes the size and location of theEmbeddedComponentView by calling SetAllocatedAreaInParent.

Calling Context:

Call this function directly.

Parameters:

const TGRect & -The new view size and location.
TFrameView & theEmbeddedComponentView -The view to be changed.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleDroppedTextModel

virtual void HandleDroppedTextModel (const TGPoint & whereDropped, TTextModel * modelToAdopt)

Interface Category:

API.

Purpose:

Processes a dropped text model item. The model parameter is absorbed into the model associated with this view, and any embedded components are copied and adopted.

Calling Context:

Called internally by AcceptDrop.

Parameters:

const TGPoint & whereDropped -The drop location.
TTextModel * modelToAdopt -The dropped text model to be absorbed and adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleDroppedEmbedderModel

virtual void HandleDroppedEmbedderModel (const TGPoint & whereDropped, TEmbedderModel * modelToAdopt)

Interface Category:

API.

Purpose:

Processes a dropped embedder model. The model parameter is absorbed into the model associated with this view, and any embedded components are copied and adopted.

Calling Context:

Called internally by AcceptDrop.

Parameters:

const TGPoint & whereDropped -The drop location.
TEmbedderModel * modelToAdopt -The dropped embedder model to be absorbed and adopted.

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::HandleRepositionAllComponentViews

virtual void HandleRepositionAllComponentViews ()

Interface Category:

API.

Purpose:

Repositions embedded component views for this text view.

Calling Context:

Called by document framework classes.

Parameters:

Takes no parameters. -

Return Value:

None.

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::operator<<=

virtual TStream & operator <<= (TStream & fromwhere)

Interface Category:

API.

Purpose:

Stream-in operator.

Calling Context:

Called to stream in data.

Parameters:

TStream & fromwhere -Reference to stream to read from.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::operator>>=

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

Interface Category:

API.

Purpose:

Stream-out operator.

Calling Context:

Called to stream out data.

Parameters:

TStream & towhere -Reference to stream to write to.

Return Value:

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

Exceptions:

Throws no exceptions, passes all exceptions through.

Concurrency:

Multithread safe.

Other Considerations:

None.

Member Function: TEmbedderTextView::SetAllocatedArea

virtual void SetAllocatedArea (const TGArea &)
virtual void SetAllocatedArea (const TGRect &)

Interface Category:

API.

Purpose:

Set the allocated area of this view based on the TGArea parameter.
Set the allocated area of this view based on the TGRect parameter.

Calling Context:

May be called directly.
May be called directly.

Parameters:

const TGArea & -Reference to TGArea to set the allocated area of this to.
const TGRect & -Reference to TGRect to set the allocated area of this to.

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.