Clipboard handling
Name
ggiWmhClipboardOpen, ggiWmhClipboardClose, ggiWmhClipboardAdd, ggiWmhClipboardAddCB, ggiWmhClipboardGet, ggiWmhClipboardTypeIter : Clipboard handling
Synopsis
#include <ggi/wmh.h> typedef int (ggiwmh_clipboard_callback)(void *user, const char *mime_type, void *data, size_t *size); #define GGIWMH_CLIPBOARD_ADD (0x01) #define GGIWMH_CLIPBOARD_GET (0x02) #define GGIWMH_SELECTION_ADD (0x04) #define GGIWMH_SELECTION_GET (0x08) #define GGIWMH_CLIPBOARD_ADD_ALL (0x05) int ggiWmhClipboardOpen(ggi_visual_t vis, uint32_t flags); int ggiWmhClipboardClose(ggi_visual_t vis); int ggiWmhClipboardAdd(ggi_visual_t vis, const char *mime_type, void *data, size_t size); int ggiWmhClipboardAddCB(ggi_visual_t vis, const char *mime_type, ggiwmh_clipboard_callback *callback, void *user); int ggiWmhClipboardGet(ggi_visual_t vis, const char *mime_type, void *data, size_t *size); struct ggiwmh_clipboard_type_iter { struct gg_iter iter; /* Placeholder for result */ char *mime_type; /* Internal */ void *_state; void *_ctxt; }; int ggiWmhClipboardTypeIter(ggi_visual_t vis, struct ggiwmh_clipboard_type_iter *iter);
Description
ggiWmhClipboardOpen opens the clipboard. Use the flag GGIWMH_CLIPBOARD_ADD_ALL when about to store data on the clipboard (cut or copy), and GGIWMH_CLIPBOARD_GET when getting data from the clipboard (paste). Do not keep the clipboard open for extensive periods of time, the system might misbehave if you do.
For applications wishing to support the X11 behaviour or pasting the currently marked selection when the middle pointer button is pressed should open the clipboard with GGIWMH_SELECTION_ADD when something is selected, and with GGIWMH_SELECTION_GET when the middle pointer button is pressed. It may also (optionally) open the clipboard with GGIWMH_CLIPBOARD_ADD (instead of GGIWMH_CLIPBOARD_ADD_ALL) when Cut or Copy is used in an Edit menu.
ggiWmhClipboardClose closes the clipboard after opening it and performing the desired operations.
ggiWmhClipboardAdd adds data of the given size to the clipboard formatted according to the indicated mime_type. Several versions of the same data (but with different types) may be added to the clipboard, but has to be added inside the same open/close transaction.
ggiWmhClipboardAddCB adds a mime_type without data to the clipboard. The data for this type need only be generated in case someone requests it. In order to free resources, the application may listen for events of type GII_SLI_CODE_WMH_CLIPBOARD_DESTROY or GII_SLI_CODE_WMH_SELECTION_DESTROY, as this indicates when someone else has become clipboard owner. When someone does request the data, the callback function is called with user and mime_type as the two first arguments. The other two arguments in the callback function (data and size) should be implemented to follow the same rules as in the ggiWmhClipboardGet function described below.
ggiWmhClipboardGet retrieves the clipboard content of the indicated mime_type. By setting data to NULL, the application may query the size of the clipboard contents. If data is not NULL, the clipboard content is copied, but possibly truncated.
ggiWmhClipboardTypeIter is used to iterate over the available content types on the clipboard.
When adding text content to the clipboard, notice that even though MIME prescribes line endings to be encoded as CR/NL pairs, this interface does not expects that. Just use a single NL character to mark a line ending. Further, if you do specify a size instead of using the GGIWMH_CLIPBOARD_STRLEN define, make sure that a string terminator (NUL) is included when you add data, but do not count on it being present when you get data from the clipboard.
Return Value
All the above functions return GGI_OK on success. If something fails, they return a gg-error(3) code.
ggiWmhClipboardGet returns GGI_ENOSPACE if the content has been truncated. It still updates *size in this case.
ggiWmhClipboardGet returns GGI_ENOMATCH if the requested mime_type is not available.
ggiWmhClipboardAdd, ggiWmhClipboardAddCB and ggiWmhClipboardGet return GGI_ENOTALLOC if the clipboard has not been previously opened with the appropriate flag.
Examples
The following demonstrates how to list all available mime types currently available on the clipboard:
struct gg_stem *stem; struct ggiwmh_clipboard_type_iter clip_iter; ggiWmhClipboardOpen(stem, GGIWMH_CLIPBOARD_GET); ggiWmhClipboardTypeIter(stem, &clip_iter); GG_ITER_FOREACH(&clip_iter) { printf("type: %s\n", clip_iter.mime_type); } GG_ITER_DONE(&clip_iter); ggiWmhClipboardClose(stem);
The following demonstrates how to add text content to the clipboard:
struct gg_stem *stem; ggiWmhClipboardOpen(stem, GGIWMH_CLIPBOARD_ADD_ALL); ggiWmhClipboardAdd(stem, GGIWMH_MIME_TEXT, "This is a clipboard example\r\n" "with two lines", GGIWMH_CLIPBOARD_STRLEN); ggiWmhClipboardClose(stem);