Parasol Framework
  • Modules
  • Classes
  • Wiki

Clipboard Class

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
NameTypeComment
  FlagsCPFOptional flags.
NameDescription
CPF::DRAG_DROPEnables drag and drop mode. The clipboard content will be private and not share data with the host system in this mode.
CPF::HISTORY_BUFFEREnables 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::HOSTThis indicator is automatically set when a clipboard was created due to incoming content from the host system.
  RequestHandlerFUNCTIONProvides 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, LONG 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:

NameComment
ClearDestroys all cached data that is stored in the clipboard.
DataFeedThis action can be used to place data in a clipboard.
ERR acDataFeed(*Object, OBJECTID Object, DATA Datatype, APTR Buffer, LONG Size)
InputDescription
ObjectMust 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.
DatatypeThe type of data being sent.
BufferThe data being sent to the target object.
SizeThe 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:

NameComment
AddFileAdd files to the clipboard.
ERR clip::AddFile(OBJECTPTR Object, CLIPTYPE Datatype, CSTRING Path, CEF Flags)
InputDescription
DatatypeSet this argument to indicate the type of data you are copying to the clipboard.
PathThe path of the file to add.
FlagsOptional 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:

NameDescription
CLIPTYPE::AUDIOAn audio clip that is recognised by the Sound class (such as wav's and mp3's).
CLIPTYPE::DATARaw information that is uncategorised can be defined as a data clip.
CLIPTYPE::FILEPure file references are stored as file clips. This type is typically used by file managers for moving and copying files.
CLIPTYPE::IMAGEImages that are recognised by the Picture class may be stored as this type (such as jpeg's and png files).
CLIPTYPE::OBJECTAn object that has been deserialised into binary form.
CLIPTYPE::TEXTPlain 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:

NameDescription
CEF::DELETERequests that the original file source is deleted if a successful paste operation takes place.
CEF::EXTENDInstead of replacing existing clipboard data, add the new data to the group.

Error Codes

OkayThe files were added to the clipboard.
MissingPathThe Files argument was not correctly specified.
NullArgsFunction call missing argument value(s)
AddObjectsExtract data from objects and add it all to the clipboard.
ERR clip::AddObjects(OBJECTPTR Object, CLIPTYPE Datatype, OBJECTID * Objects, CEF Flags)
InputDescription
DatatypeThe type of data representing the objects, or NULL for automatic recognition.
ObjectsArray of object ID's to add to the clipboard.
FlagsOptional 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

OkayThe objects were added to the clipboard.
ArgsInvalid arguments passed to function.
AddTextAdds a block of text to the clipboard.
ERR clip::AddText(OBJECTPTR Object, CSTRING String)
InputDescription
StringThe text to add to the clipboard.

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

Error Codes

OkayOperation successful.
CreateFileA new file could not be created.
NullArgsFunction call missing argument value(s)
GetFilesRetrieve the most recently clipped data as a list of files.
ERR clip::GetFiles(OBJECTPTR Object, CLIPTYPE Filter, LONG Index, CLIPTYPE * Datatype, CSTRING ** Files, CEF * Flags)
InputDescription
FilterFilter 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.
IndexIf the Filter parameter is zero, this parameter may be set to the index of the desired clip item.
DatatypeThe resulting datatype of the requested clip data.
FilesThe resulting location(s) of the requested clip data are returned in this parameter; terminated with a NULL entry. You are required to free the returned array with FreeResource().
FlagsResult flags are returned in this parameter. If DELETE is set, you need to 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

OkayA matching clip was found and returned.
ArgsInvalid arguments passed to function.
NoDataNo clip was available that matched the requested data type.
OutOfRangeThe specified Index is out of the range of the available clip items.
RemoveRemove items from the clipboard.
ERR clip::Remove(OBJECTPTR Object, CLIPTYPE Datatype)
InputDescription
DatatypeThe 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

OkayOperation successful.
AccessMemoryThe clipboard memory data was not accessible.
NullArgsFunction call missing argument value(s)
Clipboard class documentation © Paul Manias 2003-2024

CEF Type

NameDescription
CEF::DELETERequests that the original file source is deleted if a successful paste operation takes place.
CEF::EXTENDInstead of replacing existing clipboard data, add the new data to the group.
Clipboard module documentation © Paul Manias 2003-2024

CLIPTYPE Type

Clipboard types

NameDescription
CLIPTYPE::AUDIOAn audio clip that is recognised by the Sound class (such as wav's and mp3's).
CLIPTYPE::DATARaw information that is uncategorised can be defined as a data clip.
CLIPTYPE::FILEPure file references are stored as file clips. This type is typically used by file managers for moving and copying files.
CLIPTYPE::IMAGEImages that are recognised by the Picture class may be stored as this type (such as jpeg's and png files).
CLIPTYPE::OBJECTAn object that has been deserialised into binary form.
CLIPTYPE::TEXTPlain text files such as ASCII and UTF-8 must be identified through this clip type.
Clipboard module documentation © Paul Manias 2003-2024

CPF Type

Clipboard flags

NameDescription
CPF::DRAG_DROPEnables drag and drop mode. The clipboard content will be private and not share data with the host system in this mode.
CPF::HISTORY_BUFFEREnables 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::HOSTThis indicator is automatically set when a clipboard was created due to incoming content from the host system.
Clipboard module documentation © Paul Manias 2003-2024

Class Info

IDID_CLIPBOARD
CategoryIO
Includemodules/clipboard.h
Version1

Class List

  • Audio
    • Audio
    • Sound
  • Core
    • File
    • MetaClass
    • Module
    • StorageDevice
    • Task
    • Thread
    • Time
  • Data
    • Compression
    • Config
    • Script
    • XML
  • Effects
    • BlurFX
    • ColourFX
    • CompositeFX
    • ConvolveFX
    • DisplacementFX
    • FilterEffect
    • FloodFX
    • ImageFX
    • LightingFX
    • MergeFX
    • MorphologyFX
    • OffsetFX
    • RemapFX
    • SourceFX
    • TurbulenceFX
    • WaveFunctionFX
  • Extensions
    • Scintilla
    • ScintillaSearch
  • Graphics
    • Bitmap
    • Clipboard
    • Display
    • Document
    • Font
    • Picture
    • Pointer
    • Surface
    • SVG
  • Network
    • ClientSocket
    • HTTP
    • NetSocket
    • Proxy
  • Vectors
    • Vector
    • VectorClip
    • VectorColour
    • VectorEllipse
    • VectorFilter
    • VectorGradient
    • VectorGroup
    • VectorImage
    • VectorPath
    • VectorPattern
    • VectorPolygon
    • VectorRectangle
    • VectorScene
    • VectorShape
    • VectorSpiral
    • VectorText
    • VectorTransition
    • VectorViewport
    • VectorWave