Previous: Cursors, Up: Part V Some Useful Functions [Contents][Index]
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]