Manages copied, cut and dragged data for paste operations.

The Clipboard class stores references to copied data so that applications can offer cut, copy, paste and drag-and-drop workflows. Clipboard entries are grouped by datatype and are exposed to consumers as readable files, allowing large items to be pasted without first loading their contents into application memory.

Multiple Clipboard objects can be created, but they share the same clipboard store for the current process and user session. Each datatype normally has one active group of items. Adding a new group for the same datatype replaces the previous group unless the CEF::EXTEND flag is used.

On Windows, text and file references are integrated with the host clipboard when possible, so Kōtuku applications can exchange those datatypes with native Windows applications. If CPF::HISTORY_BUFFER is enabled, the clipboard actively monitors host changes and caches copied data in the local clipboard: volume. This enables limited history at the cost of additional monitoring and storage overhead.

On Linux and other non-Windows builds, clipboard storage is local to Kōtuku applications unless platform-specific host integration is supplied by the display driver.

When history buffering is active, a fixed number of clip groups is retained and the oldest group is removed when the limit is exceeded. Cached clipboard files are kept under clipboard: and stale generated files are cleaned up during display initialisation.

Structure

The Clipboard class consists of the following fields:

Access

Name

Type

Comment

Flags CPF Optional clipboard behaviour flags.

Name	Description
CPF::DRAG_DROP	Enables drag and drop mode. The clipboard content will be private and not share data with the host system in this mode.
CPF::HISTORY_BUFFER	Enables the history buffer. Note that this results in active clipboard monitoring and the program will make copies of all potential clipboard content - whether it is used or not.
CPF::HOST	This indicator is automatically set when a clipboard was created due to incoming content from the host system.

RequestHandler FUNCTION Callback for drag-and-drop data requests.

When the clipboard is in drag-and-drop mode, applications can request source data by sending a DATA::REQUEST to DataFeed(). The request is forwarded to the callback stored in RequestHandler, which must be supplied by the source application.

The callback uses this signature:

ERR RequestHandler(*Clipboard, OBJECTPTR Requester, int Item, BYTE Datatypes[4])

The callback is expected to send a DATA::RECEIPT to the object referenced by Requester. The receipt must cover Item and use one of the preferred datatypes supplied in Datatypes. If the request cannot be fulfilled, the callback should return ERR::NoSupport.

Actions

The following actions are currently supported:

Clear Removes all cached clipboard data.

ERR acClear(*Object)

Clear deletes the generated clipboard cache and removes all clip records tracked by the current process. Use Remove() to delete only selected datatypes.

DataFeed Sends data to the clipboard or handles drag-and-drop requests.

ERR acDataFeed(*Object, OBJECTID Object, DATA Datatype, std::span<const int8_t> Buffer)

Parameter	Description
Object	Must refer to the unique ID of the object that you represent. If you do not represent an object, set this parameter to the current task ID.
Datatype	The type of data being sent.
Buffer	The data being sent to the target object.

For regular clipboard writes, DataFeed currently accepts DATA::TEXT. Text received through this action replaces the current text clip and is cached as a generated file unless the host clipboard accepts it and no history buffer is active.

When the clipboard is in drag-and-drop mode, DataFeed also accepts DATA::REQUEST. Requests are forwarded to the RequestHandler callback so the source application can provide the requested data to the requester.

Error Codes

Okay	Operation successful.
Terminate	Termination requested
Write	Error writing data
NoSupport	Operation not supported
FieldNotSet	A required field value is undefined
CreateObject	A call to CreateObject() failed
NullArgs	Function call missing argument value(s)

Methods

The following methods are currently supported:

AddFile Adds a file reference to the clipboard.

ERR clip::AddFile(OBJECTPTR Object, CLIPTYPE Datatype, STRVIEW Path, CEF Flags)

Parameter	Description
Datatype	Identifies the type of data represented by the file.
Path	Path of the file to add.
Flags	Optional flags.

Use AddFile() when the data to copy is already available as a file. The method stores the file path as a clipboard entry and associates it with a CLIPTYPE value so that paste targets can decide whether they understand the content. This is efficient for large items because the clipboard does not need to load the file contents into memory.

If the clipboard can publish the file reference to the host platform, and history buffering is disabled, the method may return after updating the host clipboard. Otherwise the file reference is recorded in the Kōtuku clipboard store.

Recognised data types are:

Name	Description
CLIPTYPE::AUDIO	An audio clip that is recognised by the Sound class (such as wav's and mp3's).
CLIPTYPE::DATA	Raw information that is uncategorised can be defined as a data clip.
CLIPTYPE::FILE	Pure file references are stored as file clips. This type is typically used by file managers for moving and copying files.
CLIPTYPE::IMAGE	Images that are recognised by the Image class may be stored as this type (such as jpeg's and png files).
CLIPTYPE::OBJECT	An object that has been deserialised into binary form.
CLIPTYPE::TEXT	Plain text files such as ASCII and UTF-8 must be identified through this clip type.

Optional flags that may be passed to this method are as follows:

Name	Description
CEF::DELETE	Requests that the original file source is deleted if a successful paste operation takes place.
CEF::EXTEND	Instead of replacing existing clipboard data, add the new data to the group.

Error Codes

Okay	The files were added to the clipboard.
MissingPath	`Path` was not specified.
NullArgs	Function call missing argument value(s)

AddObjects Saves objects to clipboard cache files.

ERR clip::AddObjects(OBJECTPTR Object, CLIPTYPE Datatype, OBJECTID * Objects, CEF Flags)

Parameter	Description
Datatype	Type of data represented by the objects, or zero for automatic recognition.
Objects	Zero-terminated array of object IDs to add to the clipboard.
Flags	Optional flags.

Use AddObjects() to copy one or more objects by asking each object to save itself to a generated file in the clipboard: volume. This avoids requiring the caller to create temporary files before copying object data.

If Datatype is CLIPTYPE::NIL, the clipboard chooses a datatype from the source object's class where possible. Image objects are stored as CLIPTYPE::IMAGE, sound objects are stored as CLIPTYPE::AUDIO, and unrecognised classes are stored as CLIPTYPE::OBJECT. Set Datatype explicitly to override this automatic selection.

All objects in a single call must belong to the same class. The Objects array must be terminated with a zero entry.

Optional flags that may be passed to this method are the same as those specified in the AddFile() method. The CEF::DELETE flag has no effect on objects.

Error Codes

Okay	The objects were added to the clipboard.
Args	Invalid arguments passed to function
Lock	Failed to lock a required resource
CreateFile	A new file could not be created
NullArgs	Function call missing argument value(s)

AddText Adds a block of text to the clipboard.

ERR clip::AddText(OBJECTPTR Object, STRVIEW String)

Parameter	Description
String	UTF-8 text to add to the clipboard.

Use AddText() to place plain UTF-8 text on the clipboard. Empty strings are ignored and return ERR::Okay.

On Windows, the text is also published to the host clipboard when supported. If history buffering is disabled and the host clipboard accepts the text, no local cache file is created.

Error Codes

Okay	Operation successful.
CreateFile	A new file could not be created
NullArgs	Function call missing argument value(s)

GetFiles Retrieve the most recently clipped data as a list of files.

ERR clip::GetFiles(OBJECTPTR Object, CLIPTYPE Filter, INT Index, CLIPTYPE * Datatype, kt::vector<std::string> * Files, CEF * Flags)

Parameter	Description
Filter	Datatype filter. Set to zero to accept any datatype.
Index	History index to read when Filter is zero. Zero is the most recent clip group.
Datatype	Datatype of the returned clip group.
Files	An empty string array is required to receive the file list.
Flags	Result flags. If the delete flag is set, delete the files after use to complete a cut operation.

GetFiles() returns clipboard entries as readable file paths. The caller can request a specific set of datatypes through Filter, or pass CLIPTYPE::NIL to accept any datatype.

Without history buffering, only the most recent clip group is available. With history buffering enabled, pass CLIPTYPE::NIL as Filter and increment Index to scan retained history from newest to oldest until ERR::OutOfRange is returned.

On success, Datatype reports the datatype of the returned clip and Files receives the matching file paths. How the caller reads each file depends on Datatype; IdentifyFile() can also be used to find a class that supports the data. Files must refer to an empty caller-owned array and remains owned by the caller after the method returns.

If CEF::DELETE is returned in Flags, the caller must delete the source files after successfully copying the data in order to complete a cut operation. When cutting and pasting files within the same file system, MoveFile() is usually the most efficient way to consume those entries.

Error Codes

Okay	A matching clip was found and returned.
NoData	No clip was available that matched the requested data type.
OutOfRange	The specified `Index` is out of the range of the available clip items.
NullArgs	Function call missing argument value(s)

Remove Removes selected datatypes from the clipboard.

ERR clip::Remove(OBJECTPTR Object, CLIPTYPE Datatype)

Parameter	Description
Datatype	Datatype flags to remove. Values may be combined.

Remove() clears all active clip groups whose datatype matches Datatype. Multiple datatypes can be removed by combining CLIPTYPE flags. To clear all content from the clipboard, use Clear().

Error Codes

Okay	Operation successful.
NullArgs	Function call missing argument value(s)

CEF Type

Name	Description
CEF::DELETE	Requests that the original file source is deleted if a successful paste operation takes place.
CEF::EXTEND	Instead of replacing existing clipboard data, add the new data to the group.

CLIPTYPE Type

Clipboard types

Name	Description
CLIPTYPE::AUDIO	An audio clip that is recognised by the Sound class (such as wav's and mp3's).
CLIPTYPE::DATA	Raw information that is uncategorised can be defined as a data clip.
CLIPTYPE::FILE	Pure file references are stored as file clips. This type is typically used by file managers for moving and copying files.
CLIPTYPE::IMAGE	Images that are recognised by the Image class may be stored as this type (such as jpeg's and png files).
CLIPTYPE::OBJECT	An object that has been deserialised into binary form.
CLIPTYPE::TEXT	Plain text files such as ASCII and UTF-8 must be identified through this clip type.

CPF Type

Clipboard flags

Name	Description
CPF::DRAG_DROP	Enables drag and drop mode. The clipboard content will be private and not share data with the host system in this mode.
CPF::HISTORY_BUFFER	Enables the history buffer. Note that this results in active clipboard monitoring and the program will make copies of all potential clipboard content - whether it is used or not.
CPF::HOST	This indicator is automatically set when a clipboard was created due to incoming content from the host system.

Clipboard Class

Structure

Actions

Methods

CEF Type

CLIPTYPE Type

CPF Type