The Clipboard class manages cut, copy and paste between applications.

The Clipboard class manages data transfer between applications on behalf of the user. Depending on the host system, behaviour between platforms can vary.

On Windows the clipboard is tightly integrated by default, allowing it to support native Windows applications. This reduces the default feature set, but ensures that the clipboard behaves in a way that the user would expect it to. If historical buffering is enabled with the CPF::HISTORY_BUFFER option then the clipboard API will actively monitor the clipboard and store copied data in the local clipboard: file cache. This results in additional overhead to clipboard management.

On Linux the clipboard is localised and data is shared between Parasol applications only.

Multiple clipboard objects can be created, but they will share the same group of clipped data for the logged-in user.

There is a limit on the number of clipped items that can be stored in the clipboard. Only 1 grouping of each datatype is permitted (for example, only one group of image clips may exist at any time). In historical buffer mode there is a fixed limit to the clip count and the oldest members are automatically removed.

Structure

The Clipboard class consists of the following fields:

Access

Name

Type

Comment

Flags CPF Optional 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 Provides a hook for responding to drag and drop requests.

Applications can request data from a clipboard if it is in drag-and-drop mode by sending a DATA::REQUEST to the Clipboard's DataFeed action. Doing so will result in a callback to the function that is referenced in the RequestHandler, which must be defined by the source application. The RequestHandler function must follow this template:

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

The function will be expected to send a DATA::RECEIPT to the object referenced in the Requester paramter. The receipt must provide coverage for the referenced Item and use one of the indicated Datatypes as the data format. If this cannot be achieved then ERR::NoSupport should be returned by the function.

Actions

The following actions are currently supported:

Clear Destroys all cached data that is stored in the clipboard.

DataFeed This action can be used to place data in a clipboard.

ERR acDataFeed(*Object, OBJECTID Object, DATA Datatype, APTR Buffer, INT Size)

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.
Size	The size of the data in Buffer.

Data can be sent to a clipboard object via the DataFeed action. Currently, only the DATA::TEXT type is supported. All data that is sent to a clipboard object through this action will replace any stored information that matches the given data type.

Methods

The following methods are currently supported:

AddFile Add files to the clipboard.

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

Parameter	Description
Datatype	Set this argument to indicate the type of data you are copying to the clipboard.
Path	The path of the file to add.
Flags	Optional flags.

This method is used to add a file to the clipboard. You are required to specify the type of data that is represented by the file. This allows the file content to be pasted by other applications that understand the data. Adding files to the clipboard with a known datatype can be very efficient compared to other methods, as it saves loading the data into memory until the user is ready to paste the content.

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 Picture 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	The Files argument was not correctly specified.
NullArgs	Function call missing argument value(s)

AddObjects Extract data from objects and add it all to the clipboard.

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

Parameter	Description
Datatype	The type of data representing the objects, or NULL for automatic recognition.
Objects	Array of object ID's to add to the clipboard.
Flags	Optional flags.

Data can be saved to the clipboard directly from an object if the object's class supports the SaveToObject() action. The clipboard will ask that the object save its data directly to a cache file, completely removing the need for the client to save the object data to an interim file for the clipboard.

Certain classes are recognised by the clipboard system and will be added to the correct datatype automatically (for instance, Picture objects will be put into the CLIPTYPE::IMAGE data category). If an object's class is not recognised by the clipboard system then the data will be stored in the CLIPTYPE::OBJECT category to signify that there is a class in the system that recognises the data. If you want to over-ride any aspect of this behaviour, force the Datatype parameter with one of the available CLIPTYPE values.

This method supports groups of objects in a single clip, thus requires an array of object ID's 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.

AddText Adds a block of text to the clipboard.

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

Parameter	Description
String	The text to add to the clipboard.

Plain UTF-8 text can be added to the clipboard using the AddText() method.

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, CSTRING ** Files, CEF * Flags)

Parameter	Description
Filter	Filter down to the specified data type. This parameter will be updated to reflect the retrieved data type when the method returns. Set to zero to disable.
Index	If the `Filter` parameter is zero and clipboard history is enabled, this parameter refers to a historical clipboard item, with zero being the most recent.
Datatype	The resulting datatype of the requested clip data.
Files	The resulting location(s) of the requested clip data are returned in this parameter; terminated with a `NULL` entry. The client must free the returned array with FreeResource().
Flags	Result flags are returned in this parameter. If `DELETE` is defined, the client must delete the files after use in order to support the 'cut' operation.

This method returns a list of items that are on the clipboard. The caller must declare the types of data that it supports (or zero if all datatypes are recognised).

The most recently clipped datatype is always returned. To scan for all available clip items, set the Filter parameter to zero and repeatedly call this method with incremented Index numbers until the error code ERR::OutOfRange is returned.

On success this method will return a list of files (terminated with a NULL entry) in the Files parameter. Each file is a readable clipboard entry - how the client reads it depends on the resulting Datatype. Additionally, the IdentifyFile() function could be used to find a class that supports the data. The resulting Files array is a memory allocation that must be freed with a call to FreeResource().

If this method returns the CEF::DELETE flag in the Flags parameter, the client must delete the source files after successfully copying the data. When cutting and pasting files within the file system, using MoveFile() is recommended as the most efficient method.

Error Codes

Okay	A matching clip was found and returned.
Args	Invalid arguments passed to function.
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.

Remove Remove items from the clipboard.

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

Parameter	Description
Datatype	The datatype(s) that will be deleted (datatypes may be logically-or'd together).

The Remove() method will clear all items that match a specified datatype. Clear multiple datatypes by combining flags in the Datatype parameter. To clear all content from the clipboard, use the Clear() action instead of this method.

Error Codes

Okay	Operation successful.
AccessMemory	The clipboard memory data was not accessible.
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 Picture 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