## IupClipboard (since 3.0)

Creates an element that allows access to the clipboard. Each clipboard should be destroyed using IupDestroy, but you can use only one for the entire application because it does not store any data inside. Or you can simply create and destroy every time you need to copy or paste.

### Creation

    Ihandle* IupClipboard(void); [in C]
    iup.clipboard{} -> (ih: ihandle) [in Lua]
    clipboard() [in LED]

Returns: the identifier of the created element, or NULL if an error occurs.

### Attributes

ADDFORMAT (write-only): register a custom format for clipboard data given its name. The registration remains valid even after the element is destroyed. A new format must be added before used. (since 3.7)

EMFAVAILABLE (read-only) [Windows Only]: informs if there is a Windows Enhanced Metafile available at the clipboard. (Since 3.2)

FORMAT: set the current format to be used by the FORMATAVAILABLE and FORMATDATA attributes. This is a custom format string. The application copy and paste functions must know what it is copying and pasting in FORMATDATA based on that string. (since 3.7)

FORMATAVAILABLE (read-only): informs if there is a data in the FORMAT available at the clipboard. If FORMAT is not set returns NULL. (since 3.7)

FORMATDATA: sets or retrieves the data from the clipboard in the format defined by the FORMAT attribute. If FORMAT is not set returns NULL. If set to NULL clears the clipboard data. When set the FORMATDATASIZE attribute must be set before with the data size. When retrieved FORMATDATASIZE will be set and available after data is retrieved. (since 3.7)

FORMATDATASTRING [Windows and GTK Only]: sets/gets FORMATDATA and FORMATDATASIZE considering data being a string in the system format. (since 3.29)

FORMATDATASIZE: size of the data on the clipboard. Used by the FORMATDATA attribute processing. (since 3.7)

IMAGE (write-only): name of an image to copy to the clipboard. If set to NULL clears the clipboard data. (GTK 2.6)

IMAGEAVAILABLE (read-only): informs if there is an image available at the clipboard. (GTK 2.6)

NATIVEIMAGE: native handle of an image to copy or paste, to or from the clipboard. In Win32 is a HANDLE of a DIB. In GTK is a GdkPixbuf*. In Motif is a Pixmap. If set to NULL clears the clipboard data. The returned handle in a paste must be released after used (GlobalFree(handle), g_object_unref(pixbuf) or XFreePixmap(display, pixmap)). After copy, do NOT release the given handle. See IUP-IM Functions for utility functions on image native handles. (GTK 2.6)

SAVEEMF (write-only) [Windows Only]: saves the EMF from the clipboard to the given filename. (Since 3.2)

SAVEWMF (write-only) [Windows Only]: saves the WMF from the clipboard to the given filename. (Since 3.2)

TEXT: copy or paste text to or from the clipboard. If set to NULL clears the clipboard data.

TEXTAVAILABLE (read-only): informs if there is a text available at the clipboard.

WMFAVAILABLE (read-only) [Windows Only]: informs if there is a Windows Metafile available at the clipboard. (Since 3.2)

### Notes

In Windows when "TEXT" format data is copied to the clipboard, the system will automatically store other text formats too if those formats are not already stored. This means that when copying "TEXT" Windows will also store "Unicode Text" and "OEM Text", but only if those format were not copied before. So to make sure the system will copy all the other text formats clear the clipboard before copying you own data (you can simply set TEXT=NULL before setting the actual value).

### Examples

    Ihandle* clipboard = IupClipboard();
    IupSetAttribute(clipboard, "TEXT", IupGetAttribute(text, "VALUE"));
    IupDestroy(clipboard);

    Ihandle* clipboard = IupClipboard();
    IupSetAttribute(text, "VALUE", IupGetAttribute(clipboard, "TEXT"));
    IupDestroy(clipboard);