Programming Guide

Changing Your Part's Content

Users can change the content of your part through a variety of standard editing actions involving keyboard input, menu commands, scripting, and so on. How you can support those tasks is described throughout this book, with additional information and other programming texts.

This section summarizes the content-changing tasks of adding and removing embedded parts, and it notes the ways in which you must keep OpenDoc and other parts informed when you make content changes of any kind.

Adding an Embedded Part

Embedding is a process that can combine elements of storage, layout, data transfer, menu handling, and control manipulation. This section summarizes the embedding process; the summary is presented in this chapter because embedding involves such a fundamental change to a part's storage configuration.

In terms of the stored persistent objects involved, embedding breaks down to these basic alternatives:

• Your part embeds either a new or preexisting frame into its content.

• The embedded frame displays the content of either a new or preexisting part.

You create a new embedded frame by calling your draft's CreateFrame method; you embed a preexisting frame by calling your draft's AcquireFrame method. In situations where you must explicitly instantiate the part object to embed, you create a new part by calling your draft's CreatePart method, or you obtain an existing part by calling your draft's AcquirePart method.

Detailed procedures for embedding a part within your part are described in detail in "Pasting from the Clipboard", "Dropping", and "Using a Tool Palette to Embed Parts". See those sections for more information. In summary, however, you perform these tasks when you embed:

1. You decide, based on your own part's content model and on information accompanying the transferred data, what area is to be given to the embedded part for display:

   • You retrieve or define a frame shape for the embedded frame. (The part may or may not arrive with a suggested frame or frame shape).

   • You decide where to position the embedded frame in your part's content; based on that position, you will eventually create an external transform to use for positioning the facets of the embedded frame.

2. For each of the embedded part's frames that are to show the embedded part, you create or retrieve a part object (if necessary), and then you create or retrieve an embedded frame object.

   • If the part you are embedding is already attached to a frame, you do not create another frame object and you must manipulate the part itself. If the part you are embedding is not already attached to a frame, then you must create a frame object for it.

     The embedded part is stored in your part's draft, but not within your part itself.

   • If you created a frame object for the embedded part, attach that part to the frame.

     You store a reference to the frame somewhere in your part's content. The frame object itself is stored in your part's draft, but not in your part.

3. If the embedded part's frame is presently visible, you create a new facet (or facets) to display the embedded part.

4. As necessary or appropriate, you perform other tasks related to embedding, such as those described in "Working with Embedded Frames and Facets". Finally, you notify OpenDoc and your own containing part that you have changed your part's content.

Removing an Embedded Part

To remove an embedded part from your part, you must remove all the facets of the embedded part's display frame, release or remove the embedded part's frame, and redisplay your own part's content. Follow the instructions in "Removing an Embedded Frame".

This procedure illustrates the fact that your part is not actually concerned with removing embedded parts themselves. Under user instruction or for other reasons, your part may have reason to remove one or more embedded frames; once the last display frame of a given embedded part is removed from your part, that part is no longer embedded in your part.

Making Content Changes Known

Whenever you make any significant change to your part's content, whether it involves adding, deleting, moving, or otherwise modifying your intrinsic content or your embedded frames, you must make those changes known to OpenDoc and to all containing parts of your part.

• Call your draft's SetChangedFromPrev method. This marks the draft as dirty, giving your part the opportunity to write itself to storage when the draft is closed.

• Call the ContentUpdated method of each of your part's display frames in which the change occurred, passing it an identifying update ID obtained in one of three ways:

  • Returned from a call to the session object's UniqueChangeID method (if the content change originated in your part's intrinsic content)

  • Propagated from a link destination (see "Link Update ID")

  • Propagated from a call to your EmbeddedFrameUpdated method (see "The EmbeddedFrameUpdated Method of your Part Editor")

  Calling ContentUpdated notifies your containing parts (and their containing parts, and so on) that your content has changed. The notification is necessary to enable all containing parts to update any link sources that they maintain.

You should call these methods as soon as is appropriate after making any content changes. You may not have to make the calls immediately after every single change; it may be more efficient to wait for a pause in user input, for example, or until the active frame changes. In addition to sending these notifications, you must of course also update your part's display if appropriate; this may involve adding or removing facets, adjusting intrinsic content, and invalidating areas that need to be redrawn.