For example, when a user clicks on a hypertext link that is embedded within the WebRunner Sample, the viewer switches the page to display the new content. The view does not display new windows--it simply reuses the current window. This functionality is accomplished by communicating with the embedded ("in-place") link and the containing WebRunner Sample viewer. The communication is made possible using a command that is sent from the link to the embedding viewer. Links of this type are distinguished by a downward-pointing link arrow.
WebRunner Sample takes a different approach when a user drags a hypertext link within the program and embeds it in another location. Whenever a user clicks on this "out-of-place" hypertext link it opens into a new WebRunner document. Links of this type are always followed by a sideways arrow.
Both of these actions are performed in the MouseDown member function of the hypertext link's view, TWebLinkView. The flow of control is illustrated here to help clarify the complex Document framework interactions that are taking place.
The Document framework offers a way for a document component view (in fact, any view that descends from MGUIBundle) to get access to its model using the member function GetModelReference. With the resulting reference, a view can create a model pointer that accesses and locks the model so that it can be communicated with. This model pointer gives access to the TAtomicModelOn<TWebLink>, which in turn gives access to its TWebLink value.
TWebLink holds another TModelReference that either refers to the embedding WebRunner Sample (if this link is embedded), or to an invalid document. The view asks TWebLink for this reference, and then checks for its validity.
Communicating through document commands provides several benefits. For example, you can take advantage of all the document commands that are streamed into a persistent state along with the document. If the program unexpectedly fails during operation, you can still achieve unlimited levels of Undo and Redo.
This operation can be complicated by the lock placed on the link component in creating a TModelPointer. Although it provides easy synchronization in a multithreaded environment, you might want to remove all the text in the hypertext viewer, along with all its embedded components. Unfortunately, this includes the link that you are currently working with.
You can solve this dilemma by limiting the scope of the model pointer to the time needed to retrieve information from it. By creating an enclosing scope that ends before the command is fired, you can avoid a deadlock by releasing the lock when it is no longer needed.
Acquiring the
viewer's reference
The user's mouse click is handled by TWebLinkView. The first thing it does is determine whether it should open the document in-place or out-of-place. Since this information is stored in the TWebLink object that is wrapped into the component's atomic model, the view must go through the Document framework to communicate with its persistent state.
In-place opening
When the parent viewer reference is valid, it is embedded within a WebRunner Sample viewer document. The program uses this reference to send a command to the viewer, indicating that it needs to change to a different page.
Out-of-place opening
When the parent viewer reference is not valid, the link view must open a new WebRunner Sample document to display the required information. Because TWebLink already supports this functionality, the view only needs to repeat the original operations to lock the component and then retrieve the TWebLink from its atomic model. The view has access to the TWebLink, it can use TWebLink::OpenWebDocument to force the opening of a new hypertext viewer.
[Contents]
[Previous]
[Next]
Click the icon to mail questions or corrections about this material to Taligent personnel.
Generated with WebMaker