Previous: Cursors, Up: Part V Some Useful Functions [Contents][Index]

### 33.4 Clipboard

Clipboard is implemented in the Forms Library using the X selection mechanism, more specifically the `XA_PRIMARY` selection. X selection is a general and flexible way of sharing arbitrary data among applications on the same server (the applications are of course not necessarily running on the same machine). The basic (and over-simplified) concept of the X selection can be summarized as follows: the X Server is the central point of the selection mechanism and all applications running on the server communicate with other applications through the server. The X selection is asynchronous in nature. Every selection has an owner (an application represented by a window) and every application can become owner of the selection or lose the ownership.

The clipboard in Forms Library is a lot simpler than the full-fledged X selection mechanism. The simplicity is achieved by hiding and handling some of the details and events that are of no interests to the application program. In general terms, you can think of a clipboard as a read-write buffer shared by all applications running on the server. The major functionality you want with a clipboard is the ability to post data onto the clipboard and request the content of the clipboard.

To post data onto the clipboard, use the following routine

    typedef int (*FL_LOSE_SELECTION_CB)(FL_OBJECT *obj, long type);

    int fl_stuff_clipboard(FL_OBJECT *obj, long type,
                           const void *data, long size,
                           FL_LOSE_SELECTION_CB callback);

where `size` is the size (in bytes) of the content pointed to by `data`. If successful, the function returns a positive value and the data will have been copied onto the clipboard. The callback is the function that will be called when another application takes ownership of the clipboard. For textual content the application that loses the clipboard should typically undo the visual cues about the selection. If no action is required when losing the ownership a `NULL`q callback can be passed. The `obj` argument is used to obtain the window (owner) of the selection. `type` is currently unused. At the moment the return value of `lose_selection_callback()` is also unused. The data posted onto the clipboard are available to all applications that manipulate `XA_PRIMARY`, such as xterm etc.

To request the current clipboard content use the following routine

    typedef int (*FL_SELECTION_CB)(FL_OBJECT *obj, long type,
                                   const void * data, long size);

    int fl_request_clipboard(FL_OBJECT *obj, long type,
                             FL_SELECTION_CB callback);

where `callback` is the callback function that gets called when the clipboard content is obtained. The content `data` passed to the callback function should not be modified.

One thing to remember is that the operation of the clipboard is asynchronous. Requesting the content of the clipboard merely asks the owner of the content for it and you will not have the content immediately (unless the asking object happens to own the selection). XForms main event loop takes care of the communication between the requesting object and the owner of the clipboard and breaks up and re-assembles the content if it exceeds the maximum protocol request size (which has a guaranteed minimum of 16 kB, but typically is larger). If the content of the clipboard is successfully obtained the main loop invokes the lose selection callback of the prior owner and then the requesting object’s callback function.

The function returns a positive number if the requesting object owns the selection (i.e., the callback could beinvoked before the function returned) and 0 otherwise.

If there is no selection the selection callback is called with an empty buffer and the length of the buffer is set to 0. In that case `fl_request_clipboard()` returns -1.

Previous: Cursors, Up: Part V Some Useful Functions [Contents][Index]