Selection & Clipboard functions

FLTK global copy/cut/paste functions declared in <FL/Fl.H> More...

Functions
static void	Fl::add_clipboard_notify (Fl_Clipboard_Notify_Handler h, void *data=0)
	FLTK will call the registered callback whenever there is a change to the selection buffer or the clipboard.
static int	Fl::clipboard_contains (const char *type)
	Returns non 0 if the clipboard contains data matching type.
static void	Fl::copy (const char *stuff, int len, int destination=0, const char *type=Fl::clipboard_plain_text)
	Copies the data pointed to by stuff to the selection buffer (destination is 0), the clipboard (destination is 1), or both (destination is 2).
static int	Fl::dnd ()
	Initiate a Drag And Drop operation.
static void	Fl::paste (Fl_Widget &receiver)
	Backward compatibility only.
static void	Fl::paste (Fl_Widget &receiver, int source, const char *type=Fl::clipboard_plain_text)
	Pastes the data from the selection buffer (source is 0) or the clipboard (source is 1) into receiver.
static void	Fl::remove_clipboard_notify (Fl_Clipboard_Notify_Handler h)
	Stop calling the specified callback when there are changes to the selection buffer or the clipboard.
static void	Fl::selection (Fl_Widget &owner, const char *, int len)
	Changes the current selection.
static Fl_Widget *	Fl::selection_owner ()
	back-compatibility only: Gets the widget owning the current selection
static void	Fl::selection_owner (Fl_Widget *)
	Back-compatibility only: The single-argument call can be used to move the selection to another widget or to set the owner to NULL, without changing the actual text of the selection.

Variables
static char const *const	Fl::clipboard_image = "image"
	Denotes image data.
static char const *const	Fl::clipboard_plain_text = "text/plain"
	Denotes plain textual data.

Detailed Description

FLTK global copy/cut/paste functions declared in <FL/Fl.H>

Function Documentation

add_clipboard_notify()

void Fl::add_clipboard_notify ( Fl_Clipboard_Notify_Handler  h, void *  data = 0  )

static

FLTK will call the registered callback whenever there is a change to the selection buffer or the clipboard.

The source argument indicates which of the two has changed. Only changes by other applications are reported.

Example:

void clip_callback(int source, void *data) {
    if ( source == 0 ) printf("CLIP CALLBACK: selection buffer changed\n");
    if ( source == 1 ) printf("CLIP CALLBACK: clipboard changed\n");
}
[..]
int main() {
    [..]
    Fl::add_clipboard_notify(clip_callback);
    [..]
}

Note

Some systems require polling to monitor the clipboard and may therefore have some delay in detecting changes.

clipboard_contains()

static int Fl::clipboard_contains ( const char *  type )

static

Returns non 0 if the clipboard contains data matching type.

type can be Fl::clipboard_plain_text or Fl::clipboard_image.

copy()

static void Fl::copy ( const char *  stuff, int  len, int  destination = 0, const char *  type = Fl::clipboard_plain_text  )

static

Copies the data pointed to by stuff to the selection buffer (destination is 0), the clipboard (destination is 1), or both (destination is 2).

Copying to both is only relevant on X11, on other platforms it maps to the clipboard (1). len is the number of relevant bytes in stuff. type is always Fl::clipboard_plain_text. The selection buffer is used for middle-mouse pastes and for drag-and-drop selections. The clipboard is used for traditional copy/cut/paste operations.

Note

This function is, at present, intended only to copy UTF-8 encoded textual data. To copy graphical data, use the Fl_Copy_Surface class. The type argument may allow in the future to copy other kinds of data.

dnd()

int Fl::dnd ( )

static

Initiate a Drag And Drop operation.

The selection buffer should be filled with relevant data before calling this method. FLTK will then initiate the system wide drag and drop handling. Dropped data will be marked as text.

Create a selection first using: Fl::copy(const char *stuff, int len, 0)

paste() [1/2]

void Fl::paste ( Fl_Widget &  receiver )

static

Backward compatibility only.

This calls Fl::paste(receiver, 0);

See also

Fl::paste(Fl_Widget &receiver, int clipboard, const char* type)

paste() [2/2]

static void Fl::paste ( Fl_Widget &  receiver, int  source, const char *  type = Fl::clipboard_plain_text  )

static

Pastes the data from the selection buffer (source is 0) or the clipboard (source is 1) into receiver.

The selection buffer (source is 0) is used for middle-mouse pastes and for drag-and-drop selections. The clipboard (source is 1) is used for copy/cut/paste operations.

If source is 1, the optional type argument indicates what type of data is requested from the clipboard. At present, Fl::clipboard_plain_text (requesting text data) and Fl::clipboard_image (requesting image data) are possible. Set things up so the handle function of the receiver widget will be called with an FL_PASTE event some time in the future if the clipboard does contain data of the requested type. While processing the FL_PASTE event:

• if type is Fl::clipboard_plain_text, the text string from the specified source is in Fl::event_text() with UTF-8 encoding, and the number of bytes in Fl::event_length(). If Fl::paste() gets called during the drop step of a files-drag-and-drop operation, Fl::event_text() contains a list of filenames (see Drag and Drop Events).
• if type is Fl::clipboard_image, the pointer returned by Fl::event_clipboard() can be safely cast to type Fl_Image * to obtain a pointer to the pasted image. Furthermore, starting with FLTK 1.3.4, the image is of type Fl_RGB_Image across all platforms. If receiver accepts the clipboard image, receiver.handle() should return 1 and the application should take ownership of this image (that is, delete it after use). Conversely, if receiver.handle() returns 0, the application must not use the image.

The receiver should be prepared to be called directly by this, or for it to happen later, or possibly not at all. This allows the window system to take as long as necessary to retrieve the paste buffer (or even to screw up completely) without complex and error-prone synchronization code in FLTK.

Platform details for image data:

• Unix/Linux platform: Clipboard images in PNG or BMP formats are recognized. Requires linking with the fltk_images library.
• MSWindows platform: Both bitmap and vectorial (Enhanced metafile) data from clipboard can be pasted as image data.
• Mac OS X platform: Both bitmap (TIFF) and vectorial (PDF) data from clipboard can be pasted as image data.

selection()

void Fl::selection ( Fl_Widget &  owner, const char *  text, int  len  )

static

Changes the current selection.

The block of text is copied to an internal buffer by FLTK (be careful if doing this in response to an FL_PASTE as this may be the same buffer returned by event_text()). The selection_owner() widget is set to the passed owner.

selection_owner() [1/2]

static Fl_Widget * Fl::selection_owner ( )

inlinestatic

back-compatibility only: Gets the widget owning the current selection

See also

Fl_Widget* selection_owner(Fl_Widget*)

selection_owner() [2/2]

void Fl::selection_owner ( Fl_Widget *  owner )

static

Back-compatibility only: The single-argument call can be used to move the selection to another widget or to set the owner to NULL, without changing the actual text of the selection.

FL_SELECTIONCLEAR is sent to the previous selection owner, if any.

Copying the buffer every time the selection is changed is obviously wasteful, especially for large selections. An interface will probably be added in a future version to allow the selection to be made by a callback function. The current interface will be emulated on top of this.