Re: OLE Clipboard

[ERDI Gergo <cactus cactus rulez org>]

On Wed, 25 Jul 2001, Nathan Cullen wrote:

> ERDI Gergo asked me to talk about how the OLE clipboard works.

Thank you very much both for this writeup and the discussion we had
yesterday.

To summarize, the basis of the OLE Clipboard is a specific structure that
holds clipboard data in some pre-defined formats (most importantly, plain
text and picture) and an IStream/IStorage. The situation is made even
messyer with the addition of an IUnknown whose sole purpose is to bind the
lifetime managment of the clipboard data to.

This is necessary because OLE's IPersistStream does not allow saving data
into multiple content types. We can clearly do better by using Monikers
and stripping the set of pre-defined formats by using 
Bonobo::PersistStream's capabilities.

The standard behaviour for OLE containers is to first try to insert data
from the clipboard in their native format, and only use
separate Embeddables if this fails or if the user specifically requests.
(e.g. by pasting an Excel range into Word, by default you will get a Word
table containing the contents of the cells from the region, and not an
embedded Excel document). Wether adopting this is a good idea or not is up
to discussion, the design I am implementing will of course enable this (it
has to, to support non-compound-document data targets).

So here's a step-by-step description of how this will work. [Nathan:
This is 100% the same as what we discussed yesterday.] The modelled
use case is:
1, User selects a region in Gnumeric, and places it on the clipboard
2, User pastes it into an AbiWord document
3, User includes a link to it into an AbiWord document
4, User pastes it into a gEdit document

1,
The user selects a cell region, and clicks Edit/Copy. Let's say Gnumeric
does not implement its own data persistancy mechanism (since the data sets
are really small, it wouldn't really be worth it), so it creates a
PersistStream that contains all the data on the cells in the selected
region, and also creates a Moniker that is something like
myfile.gnumeric!Sheet1!A1:C10.
It then passes the PersistStream and the Moniker to the Clipboard Store
(CS). The CS stores the moniker and reads the data from the
PersistStream into a Stream (also saving the PersistStream object's IID)
and then passes a `clipboardstore:' moniker and the linking moniker to the
real Clipboard.

2.
The user switches to AbiWord, positions the cursor to where he wants to
embed the stylesheet region and clicks Edit/Paste.
AbiWord gets the pasting moniker (which is a dummy moniker pointing to
the CS) and, since it supports compound documents, resolves it
for Bonobo::Embeddable.
Then the CS kicks in: when its moniker is resolved, a new moniker is
created from the iid stored before, then this moniker is resolved to the
requested interface and then it is QI'd for Bonobo::PersistStream, and its
state is restored from the Stream stored before.

So AbiWord gets a nice new, embeddable Gnumeric component that has the
correct data in it, regardless of wether the data in the actual Gnumeric
spreadsheet was changed since Edit/Copy was selected or if Gnumeric is
actually still running.

3.
Then the user positions the cursor somewhere else, and clicks Edit/Link
here. The same happens but the ClipboardStore is not used (the linking
moniker is a straight file!item!item moniker, so it is simply resolved
for Bonobo::Embeddable).

4.
The user switches to gEdit and clicks Edit/Paste.  Since gEdit does not
support compound documents, it needs a text/plain representation of the
data. So it resolves the pasting moniker for PersistStream. The CS, again,
creates a new Gnumeric object from the IID, loads back the state, and
gives back a PersistStream interface. gEdit saves the data in text/plain
format from the PersistStream, and concatenates it to the text.

-- 
   .--= ULLA! =---------------------.   `We are not here to give users what
   \     http://cactus.rulez.org     \   they want'  -- RMS, at GUADEC 2001
    `---= cactus cactus rulez org =---'
A Microsoft feltalata a program nelkuli hibat!