$Id: README,v 1.2 2001/08/27 16:11:16 cactus Exp $ -*- text -*-

Bonobo Clipboard
================

This is a moniker-based clipboard supporting both embedding and
linking. Accessing it is done via the Bonobo::Clipboard and
Bonobo::ClipboardStore interfaces, and the "clipboard:" moniker.
Up-to-date information and new releases will be available at

	http://cactus.rulez.org/projects/gnome/bonobo-clipboard
	   

Pasting and linking
-------------------

The Bonobo Clipboard provides two monikers to data target
applications: the pasting and the linking monikers. The pasting
moniker represents a static copy of the data source application's
state at the time the clipboard was set. The linking moniker
represents a live link to the data source, i.e. if the data source
changes, the data represented by the linking moniker changes as well.


The Clipboard Store
-------------------

The Clipboard Store is an external storage that eases the creation of
pasting monikers. If your application doesn't use large data sets, it
can be a good choice to just use the Clipboard Store, that saves the
data target application's state either via the PersistStream or the
PersistStorage interface. For applications that handle large blobs of
data, the overhead of transporting the data to the Clipboard Store,
and the memory requirements of storing a copy can be large, so
implementing an app-specific persistency scheme is strongly advised.

The Clipboard Store is accessed via the Bonobo::ClipboardStore
interface. Bootstrapping it is done by resolving the
OAFIID:Bonobo_Clipboard_Store moniker.


To store data on the clipboard ("copy" or "cut")
------------------------------------------------

Data is not really placed on the clipboard -- instead, you provide two
monikers which can be resolved at embedding/linking time by the data
target application. Obviously, to create the pasting moniker, you need
to either implement some kind of storage or rollback mechanism, or use
the Clipboard Store (see above). Both the pasting and the linking
monikers are optional.

To actually put the monikers on the clipboard, resolve the "clipboard:"
moniker for the Bonobo::Clipboard interface, and use the
setClipboard() method.

You can also use the client-side utility functions from
bonobo-clipboard-util.h if your application is using the GNOME Bonobo
implementation.


To retrieve data from the clipboard ("paste" and "link")
--------------------------------------------------------

Data target applications should allow users to "Paste" and "Link Here"
the clipboard based on the current clipboard state and the container
application's abilities.

A compound document container should allow both pasting and linking
the clipboard contents into the edited document. Remember to store the
internal state of the embedded object in the document (retrieved via a
Bonobo::Persist* interface), but store only the moniker for linked objects.

A simple (non-compound) editor needs not support linking. A very easy
solution to pasting is to resolve the pasting moniker for
Bonobo::PersistStream, and save the state in the container app's
native format.


Notifications
-------------

It is always a good idea to synchronize the user interface with the
actual state of the clipboard. To enable/disable Edit/Paste and
Edit/Link Here (for example), resolve the "clipboard:" moniker for the
Bonobo::EventSource interface and watch for events of type
Bonobo/Clipboard::changed.


X connectivity
--------------

There is currently a one-way connection from the Bonobo Clipboard to
the X clipboard. The Bonobo Clipboard server offers the contents of
the pasting moniker as a stream to X clients via the
Bonobo::PersistStream interface. The names of the available targets
are the same as the MIME types supported by the object available from
the pasting moniker by resolving it for Bonobo::PersistStream.
Additionally, "text/plain" is also offered as "STRING" and "TEXT", to
further support legacy applications.
