Overview

User-defined clipboard interface.

#include <Ultralight/CAPI/CAPI_Clipboard.h>

The library uses this to read and write data to the system's clipboard, as whole multi-format payloads (ULClipboardData: an ordered set of (type, value) entries keyed by a MIME type or an application-defined type string).

The library currently reads and writes these well-known types: text/plain, text/html, and text/uri-list. Your implementation should map each type it supports to the matching OS clipboard format and simply skip types it doesn't recognize.

Note: The library only calls the ULClipboard callbacks on the thread you created the Renderer or App on, so your implementation doesn't need to be safe to call from more than one thread.

See also: ulPlatformSetClipboard()

Classes
struct	ULClipboard
	User-defined clipboard interface. More...

Functions
ULClipboardData	ulCreateClipboardData (void)
	Create an empty clipboard payload.
ULClipboardData	ulCreateClipboardDataFromText (ULString text)
	Create a clipboard payload holding a single text/plain entry.
ULClipboardData	ulCreateClipboardDataRef (ULClipboardData data)
	Create another owned reference to an existing clipboard payload.
void	ulDestroyClipboardData (ULClipboardData data)
	Destroy a clipboard payload (you should only destroy payloads you have explicitly created via the functions above).
void	ulClipboardDataSetText (ULClipboardData data, ULString type, ULString text)
	Set the text value for a type, replacing any existing entry with the same type.
void	ulClipboardDataSetBytes (ULClipboardData data, ULString type, ULBuffer bytes)
	Set the bytes value for a type, replacing any existing entry with the same type.
ULString	ulClipboardDataGetText (ULClipboardData data, ULString type)
	Get the text value for a type.
ULBuffer	ulClipboardDataGetBytes (ULClipboardData data, ULString type)
	Get the bytes value for a type.
bool	ulClipboardDataIsText (ULClipboardData data, ULString type)
	Whether or not the entry for a type holds text.
bool	ulClipboardDataHas (ULClipboardData data, ULString type)
	Whether or not an entry exists for a type.
void	ulClipboardDataRemove (ULClipboardData data, ULString type)
	Remove the entry for a type (does nothing if no such entry exists).
size_t	ulClipboardDataGetSize (ULClipboardData data)
	Get the number of entries.
ULString	ulClipboardDataGetTypeAt (ULClipboardData data, size_t index)
	Get the type of the entry at a certain index, in insertion order.
ULString	ulClipboardDataGetSourceURL (ULClipboardData data)
	Get the URL of the document this payload came from (can be empty).
void	ulClipboardDataSetSourceURL (ULClipboardData data, ULString url)
	Set the URL of the document this payload came from.

Typedefs
typedef void(*)	ULClipboardClearCallback(void *user_data)
	The callback invoked when the library wants to clear the system's clipboard.
typedef ULClipboardData(*)	ULClipboardReadCallback(void *user_data)
	The callback invoked when the library wants to read from the system's clipboard.
typedef void(*)	ULClipboardWriteCallback(void *user_data, ULClipboardData data)
	The callback invoked when the library wants to write a payload to the system's clipboard, replacing its previous contents.

Function Documentation

◆ ulClipboardDataGetBytes()

ULBuffer ulClipboardDataGetBytes	(	ULClipboardData	data,
		ULString	type )

Get the bytes value for a type.

Returns: Returns a new buffer, or NULL when there is no entry for type or its value isn't bytes. Destroy the returned buffer via ulDestroyBuffer() when done.

◆ ulClipboardDataGetSize()

size_t ulClipboardDataGetSize ( ULClipboardData data )

Get the number of entries.

◆ ulClipboardDataGetSourceURL()

ULString ulClipboardDataGetSourceURL ( ULClipboardData data )

Get the URL of the document this payload came from (can be empty).

Returns: Returns a new string. Destroy the returned string via ulDestroyString() when done.

◆ ulClipboardDataGetText()

ULString ulClipboardDataGetText	(	ULClipboardData	data,
		ULString	type )

Get the text value for a type.

Returns: Returns a new string, or NULL when there is no entry for type or its value isn't text. Destroy the returned string via ulDestroyString() when done.

◆ ulClipboardDataGetTypeAt()

ULString ulClipboardDataGetTypeAt	(	ULClipboardData	data,
		size_t	index )

Get the type of the entry at a certain index, in insertion order.

Returns: Returns a new string, or NULL when index is out of range. Destroy the returned string via ulDestroyString() when done.

◆ ulClipboardDataHas()

bool ulClipboardDataHas	(	ULClipboardData	data,
		ULString	type )

Whether or not an entry exists for a type.

◆ ulClipboardDataIsText()

bool ulClipboardDataIsText	(	ULClipboardData	data,
		ULString	type )

Whether or not the entry for a type holds text.

◆ ulClipboardDataRemove()

void ulClipboardDataRemove	(	ULClipboardData	data,
		ULString	type )

Remove the entry for a type (does nothing if no such entry exists).

◆ ulClipboardDataSetBytes()

void ulClipboardDataSetBytes	(	ULClipboardData	data,
		ULString	type,
		ULBuffer	bytes )

Set the bytes value for a type, replacing any existing entry with the same type.

Note: The payload retains bytes; you can still destroy your ULBuffer afterwards.

◆ ulClipboardDataSetSourceURL()

void ulClipboardDataSetSourceURL	(	ULClipboardData	data,
		ULString	url )

Set the URL of the document this payload came from.

The library sets this when copying page content; on Windows it becomes the HTML clipboard format's SourceURL.

◆ ulClipboardDataSetText()

void ulClipboardDataSetText	(	ULClipboardData	data,
		ULString	type,
		ULString	text )

Set the text value for a type, replacing any existing entry with the same type.

Use bare MIME types (text/plain, not text/plain;charset=utf-8)– the library normalizes charset-suffixed spellings at its own boundaries.

◆ ulCreateClipboardData()

ULClipboardData ulCreateClipboardData ( void )

Create an empty clipboard payload.

Returns: Returns a payload you own; call ulDestroyClipboardData() when finished (unless you return it from a ULClipboardReadCallback, where the library consumes it).

◆ ulCreateClipboardDataFromText()

ULClipboardData ulCreateClipboardDataFromText ( ULString text )

Create a clipboard payload holding a single text/plain entry.

Returns: Returns a payload you own; call ulDestroyClipboardData() when finished (unless you return it from a ULClipboardReadCallback, where the library consumes it).

◆ ulCreateClipboardDataRef()

ULClipboardData ulCreateClipboardDataRef ( ULClipboardData data )

Create another owned reference to an existing clipboard payload.

You can use this to keep a payload that was passed to you as a borrowed handle (eg, the payload passed to your ULClipboardWriteCallback) beyond the call that provided it.

Returns: Returns a new owned reference; call ulDestroyClipboardData() when finished.

◆ ulDestroyClipboardData()

void ulDestroyClipboardData ( ULClipboardData data )

Destroy a clipboard payload (you should only destroy payloads you have explicitly created via the functions above).

Typedef Documentation

◆ ULClipboardClearCallback

typedef void(*) ULClipboardClearCallback(void *user_data)

The callback invoked when the library wants to clear the system's clipboard.

◆ ULClipboardReadCallback

typedef ULClipboardData(*) ULClipboardReadCallback(void *user_data)

The callback invoked when the library wants to read from the system's clipboard.

You should return a payload you created via ulCreateClipboardData() holding one entry per format you can read (at minimum the text/plain entry, if the clipboard holds text). The library takes ownership of the result and will call ulDestroyClipboardData() when done.

You can return NULL for an empty clipboard.

◆ ULClipboardWriteCallback

typedef void(*) ULClipboardWriteCallback(void *user_data, ULClipboardData data)

The callback invoked when the library wants to write a payload to the system's clipboard, replacing its previous contents.

You should write all of the payload's entries in one atomic clipboard transaction (on Windows: one OpenClipboard / EmptyClipboard / SetClipboardData per entry / CloseClipboard cycle), skipping any types you don't support.

Note: data is borrowed: valid only until the callback returns. Use ulCreateClipboardDataRef() to keep it beyond that (eg, for delayed rendering).

Go to the source code of this file.