API

Clip Library API reference

The clip library lives in the clip namespace:

namespace clip {
  ... all functions and types listed in this document are here ...
}

And it includes a set of APIs:

• High-level API: To do operations in just one function call
• Common API: Common data types used in high/low level APIs.
• Low-level API: To do operations atomically (lock clipboard / set multiple clipboard formats / unlock clipboard)
• Platform-specific functions

You shouldn't mix calls of both APIs. Because the high-level API tries to lock the clipboard, and if you are using the low-level API you will already have the clipboard locked.

High-level API

These functions are meant to be used as one function call. Internally each function will lock the clipboard, do the request, and unlock the clipboard. If you need to do several operations atomically with the clipboard content, it's prefered to use the low-level API

has()

bool has(format f);

Returns true if current content of the clipboard can be converted to the given format.

Returns false if this function cannot lock the clipboard to check its content (this is not a common case), or return false if the clipboard isn't convertible to the given format.

clear()

bool clear();

Clears the clipboard content. Returns true if the request is successful.

get_text()

bool get_text(std::string& value);

set_text()

bool set_text(const std::string& value);

get_image()

bool get_image(image& img);

get_image_spec()

bool get_image_spec(image_spec& spec);

set_image()

bool set_image(const image& img);

Common API

format type

typedef size_t format;

A number which indicates the format of the clipboard data. You cannot make any assumption about this number and it depends on the specific platform.

empty_format()

format empty_format();

text_format()

format text_format();

image_format()

format image_format();

ErrorCode enum

enum class ErrorCode;

ErrorCode::CannotLock

Happens when the clipboard cannot be locked because other application has it locked. It shouldn't be common but can happen, mainly on Windows if a buggy app locks the clipboard for a long period of time to update its content.

ErrorCode::ImageNotSupported

Happens when on macOS if the image in the pasteboard has a format that is not supported/not recognized (plannar or NSFloatingPointSamplesBitmapFormat), or on Windows this can happen if the given image_spec::bits_per_pixel is not supported.

error_handler

typedef void (*error_handler)(ErrorCode code);

error_handler get_error_handler();
void set_error_handler(error_handler f);

image_spec struct

image class

Low-level API

Set of functions to handle custom user data, and lock/unlock the clipboard manually to do several operations atomically.

register_format()

format register_format(const std::string& name);

Registers a new clipboard format which you can identify between different instances of your application. It's recommended to use an unique name for your format (e.g. com.mydomain.MyApp.MyFormat).

On Windows: It returns empty_format() in case that the format cannot be registered. Windows has a limited number of custom formats (values in the range 0xC000 through 0xFFFF), but it's not common to reach that limit. More info in RegisterClipboardFormatA documentation.

lock class

Platform-specific

set_x11_wait_timeout() / get_x11_wait_timeout()

void set_x11_wait_timeout(int msecs);
int get_x11_wait_timeout();

In Linux (X11), the clipboard content is passed directly between processes (the process owner of the clipboard data must respond with the data when other process asks for it). This timeout variable specifies how much time we should wait the other process to finally get the data.

Details: we send a convert selection request to the selection owner and the clipboard data is received through a SelectionNotify, if we didn't receive the notification in the given timeout span we assume that there is no clipboard content available.