$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.