Programming Guide: Storage and Data Transfer

# Programming Guide

## Storage and Data Transfer

All the data of all parts in a document, plus all information about frames and embedding, is stored in a single document file. OpenDoc does not require the user to manually manage the various file formats that make up a compound document; OpenDoc manages and holds all the pieces. This makes storage easier for developers and exchanging documents easier for users.

OpenDoc uses the same data-storage concepts for data transfer (clipboard, drag and drop, and linking) that it uses for document storage.

### Storage Basics

The OpenDoc storage system manages persistent storage for parts. It is a high-level persistent storage mechanism that enables multiple part editors to share a single document file effectively. The storage system is implemented on top of the native storage facilities for each platform that supports OpenDoc.

Storage in OpenDoc is based on a system of structured elements, each of which can contain one or more data streams. The data of each part in a document is kept in at least one storage unit, distinct from the data of other parts. Storage units can also include references to other storage units, and OpenDoc uses chains of such references to store the embedding relationships of the parts within a document.

Storage units and other elements of structured storage of OpenDoc are described further in "Storage".

Figure 14. Multiple Data Streams in a Single OpenDoc Document (Shown on OS/2)

View figure.

### Document Drafts

OpenDoc documents have a history that can be preserved and inspected through the mechanism of drafts. A draft is a captured record of the state of a document at a given time; the user decides when to save the current state of a document as a new draft and when to delete older drafts. All drafts are stored together in the same document, with no redundantly stored data.

The OpenDoc draft mechanism helps in the creation of shared documents. When several users share a document, each in turn can save the current state of the document as a draft and then make any desired changes. Users can always look back through the drafts of the document they and others have created. Also, if translation occurs during the process of sharing documents, the user can consult an older draft to regain access to formatting information that might have been lost in translation. Figure 15 and Figure 16 show examples of a dialog box through which the user can manipulate drafts.

Figure 15. Draft History Window (Shown on OS/2)

View figure.

Figure 16. Draft History Window (Shown on Windows)

View figure.

Parts also interact with their drafts to create the objects needed for embedding other parts and to create links to data sources. See "Drafts" for more information.

### Stationery

OpenDoc gives the user additional aids for constructing compound documents. One aid, central to the user's ability to create new kinds of parts, is by using the stationery icon.

Stationery is a snapshot of a document that can be used to imbed content into other documents. It is never opened; when the user attempts to open a stationery part a copy of that part is created and opened instead. Users can create stationery parts or documents with specific formatting and content, to create letterhead, forms, or types of documents. Stationery parts can be embedded in documents, or they can exist as stand-alone documents themselves.

A stationery document can also be created by setting the stationery button on in the Presentation page of the Document Properties notebook. The Document Properties notebook is accessable by selecting Document Properties... from the Document pull-down menu.

Figure 17 shows an icon for a stationery document on the desktop. The user drags the stationery icon and drops it onto the document, at which time a copy of the part is embedded in the document and opened into a frame, displaying the part's initial contents.

Figure 17. Dragging a Stationery Part from the Desktop into a Window (Shown on OS/2)

View figure.

It is typically through the use of stationery that users first gain access to your part editor. When you develop and ship a part editor, you can also provide one or more stationery documents. Part registration creates default stationery as well. To create a part using your part editor, the user does not launch the editor; instead, the user double-clicks on your stationery document or drags it into an open document window.

### Data Transfer

OpenDoc includes several built-in data-transfer features that allow users to create and edit OpenDoc documents more easily than is usual with conventional applications. Users can put any kind of media into a document with simple commands, and OpenDoc helps your part editor respond to those commands.

In OpenDoc data transfer, the source is the part (or the portion of its content) that provides the data being transferred, and the destination is the part (or the location in its content) that receives the transferred data.

#### Clipboard

Clipboard data transfer allows for easy exchange of information among documents, using menu commands familiar to most users. OpenDoc supports clipboard transfer of any kind of data, including multipart compound data, into any document.

Clipboard transfer is a two-stage process. The user first selects some portion of the content of the source part (possibly including embedded parts) and places a copy of that content onto the clipboard buffer by executing the Cut or Copy command. At any subsequent time, prior to another cut or copy, the user can copy the clipboard data to the destination (back into the same part, into another part in the same document, or into another document) by executing the Paste command.

As noted in "Embedding Compared to Incorporating", OpenDoc allows for an intelligent form of pasting in data transfer, anticipating user expectations about the result of a pasting operation when the destination holds a different kind of data from the source. Subject to user override, the destination part can decide whether to embed the data as a separate part, or incorporate it as content data into itself.

Clipboard transfer is discussed in detail in "Handling Pasted or Dropped Data".

#### Drag and Drop

Drag-and-drop data transfer is similar to Clipboard transfer, except that it involves direct user manipulation of the data being transferred, rather than the intermediate use of the Clipboard. OpenDoc supports drag and drop within documents, across documents, and to the desktop. Users can even drop non-OpenDoc data into OpenDoc parts.

Figure 18 shows the use of drag and drop to transfer a piece of information from a spreadsheet part to a text part within a document. As with Clipboard transfer, OpenDoc uses intelligent pasting in drag and drop; the spreadsheet part includes a plain-text version of the selection being dragged, so that the destination part (the text part) can directly incorporate it at the location of the drop.

Figure 18. Using Drag and Drop within a Document (Shown on OS/2)

View figure.

Drag and drop works equally well between separate documents. As far as user experience is concerned, the data-transfer facilities of OpenDoc actually blur the distinction between a part and a document. If the user drags a closed document (represented as an icon on the desktop) into an open document window, a copy of the transferred document either becomes an embedded part in the window's document or is incorporated into the intrinsic content of the document's root part. Likewise, if the user selects the frame of an embedded part in an open document window and drags or otherwise moves that part to the desktop, it immediately becomes a separate, closed document represented by icon as shown in Figure 19.

Figure 19. Dragging a Part to the Desktop (Shown on OS/2)

View figure.

Drag and drop is discussed in detail in "Drag and Drop".

#### Linking

Linking allows the user to view, within a part's frame, data that is a live copy of data in a different location. The data can be in the same frame, in a different frame, in a different part, or in a different document. When the data in the source location changes, OpenDoc updates the copy at the destination, automatically or manually, depending on user preference.

Linked data can include embedded parts, and the source of a link can be in the same part as its destination, in a different part in the same document, or in an entirely different document. Figure 20 shows a simple example of linking between two parts in a document. In this example, whenever the user changes the values in the linked spreadsheet cells, the bar graph adjusts its display accordingly.

Figure 20. Linking Spreadsheet Data to a Bar Chart

View figure.

Users create a link when pasting data, either by selecting Paste Link or Paste As. The Paste As dialog box is used to link the source of the data to its destination. (See Figure 64 for an example of the dialog box.) This simple user interface to linking makes the use of links more attractive to users than some other systems do.

Linking is discussed in detail in "Linking".

[ Top | Previous | Next | Contents | Index | Documentation Homepage ]