FLTK 1.4.4: Selection & Clipboard functions

FLTK 1.4.4

Loading...
Searching...
No Matches
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 data to the selection buffer, the clipboard, or both.
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.
static int | Fl::selection_to_clipboard ()
| Returns the current selection_to_clipboard mode.
static void | Fl::selection_to_clipboard (int mode)
| Copies selections on X11 directly to the clipboard if enabled.

## 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);
[..]
}
Fl::add_clipboard_notify
static void 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 clip...
Definition Fl.cxx:529

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

## ◆ clipboard_contains()

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

Returns non 0 if the clipboard contains data matching `type`.

The clipboard can contain both text and image data; in that situation this function returns non 0 to both requests. This function is not meant to check whether the clipboard is empty. This function does not allow to query the selection buffer because FLTK allows to copy/paste non-textual data only from/to the clipboard.

Parameters

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

## ◆ copy()

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

Copies data to the selection buffer, the clipboard, or both.

The `destination` can be:

- 0: selection buffer (see note below)
- 1: clipboard
- 2: both

The selection buffer exists only on the X11 platform and is used for middle-mouse pastes and for drag-and-drop selections. The clipboard is used for traditional copy/cut/paste operations. On all other platforms the selection buffer (`destination` = 0) is mapped to the clipboard, i.e. on platforms other than X11 all `destinations` are equivalent and the data is always copied to the clipboard.

Note
  Please see Fl::selection_to_clipboard() to enable duplication of the selection buffer to the clipboard on X11, i.e. if `destination` = 0 (selection buffer) and Fl::selection_to_clipboard() is enabled, then the data is copied to both the selection buffer and the clipboard. This makes the X11 behavior similar to other platforms but keeps the selection buffer for X11 specific inter process communication.

`type` should always be `Fl::clipboard_plain_text` which is the default. Other values are ignored and reserved for future extensions.

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 to copy other kinds of data in the future.

Parameters

  [in] | stuff | text data to be copied
  [in] | len | the number of relevant bytes in `stuff`
  [in] | destination | 0 = selection, 1 = clipboard, 2 = both (see description)
  [in] | type | usually plain text (see description)

## ◆ 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]

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.

The handle function of `receiver` can process the FL_PASTE event as follows:

- If the `receiver` widget is known to only receive text data, the text string from the specified `source` is in Fl::event_text() with UTF-8 encoding, and the number of bytes is 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 the `receiver` widget can potentially receive non-text data, use Fl::event_clipboard_type() to determine what sort of data is being sent. If Fl::event_clipboard_type() returns Fl::clipboard_plain_text, proceed as above. It it returns Fl::clipboard_image, the pointer returned by Fl::event_clipboard() can be safely cast to type Fl_RGB_Image * to obtain a pointer to the pasted image. 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.
  - Windows 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]

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.

## ◆ selection_to_clipboard() [1/2]

int Fl::selection_to_clipboard | ( |  | ) |
| inlinestatic

Returns the current selection_to_clipboard mode.

See also
  void selection_to_clipboard(int)

## ◆ selection_to_clipboard() [2/2]

void Fl::selection_to_clipboard | ( | int | mode | ) |
| inlinestatic

Copies selections on X11 directly to the clipboard if enabled.

This method can be called on all platforms. Other platforms than X11 are not affected by this feature.

If this is switched on (`mode` = 1), Fl::copy() copies all data to the clipboard regardless of its `destination` argument. If the destination is 0 (selection buffer) data is copied to both the selection buffer and the clipboard.

Drag and drop is also affected since drag-and-drop data is copied to the selection buffer.

You can use this to make the experience of data selection and copying more like that on other platforms (Windows, macOS, and even Wayland).

The default operation mode is the standard X11 behavior (disabled).

Note
  This feature is experimental and enabling it may have unexpected side effects. It is your own responsibility if you enable it.

Since
  1.4.0

Parameters

  [in] | mode | 1 = enable selection_to_clipboard, 0 = disable selection_to_clipboard

See also
  copy(const char *, int, int, const char *)