Class Documentation

Name:Clipboard
Version:1.0
ID:ID_CLIPBOARD
Status:Stable
Category:I/O
Date:November 2003
Author:Rocklyte Systems
Copyright:  Rocklyte Systems (c) 2001-2003. All rights reserved.
Short:  The Clipboard class manages cut, copy and paste operations.



Description

The Clipboard class manages data transfer between applications on behalf of the user. It holds a data cache of clipped items that originate from source applications, and these can be retrieved and 'pasted' into target applications. The Clipboard class is provided for the primary purpose of allowing applications to implement the traditional 'cut', 'copy' and 'paste' actions.

Only one clipboard object is allowed in the system at any time per user. This object is given a standardised, global name of "SystemClipboard" and is typically created at startup as part of the boot process. The object is shared and available to all applications. Items that are passed to the clipboard object are stored in the user directory "temp:clipboard/". Clipped items are persistent, so if the machine is turned off, all currently clipped items will still be accessible on the next restart. There is a limit on the amount of clipped items that can be stored in the clipboard object. Only 1 of each datatype is permitted (for example, only one 'image' clip may exist at any time) and there is a preset limitation on the total number of clips that can be stored in the history cache.

NOTE: When using a clipboard for copy and paste operations, it is wise to keep the object locked for the entire duration, releasing it only when you are finished with the use of its files. Failure to do so will cause issues in the event that a secondary task uses the clipboard while you are using clipboard file data. It is considered to be good form if you always lock the clipboard object when you use it, rather than messaging instructions to the clipboard.

Actions

The Clipboard class supports the following actions:

Clear  Destroys all cached data that is stored in the clipboard.
DataChannel  This action can be used to place data in a clipboard.
GetUnlistedField  Special field types are suppored via unlisted fields.

Methods

The Clipboard class implements the following methods:

AddClipboardFiles  Add files to the clipboard.
AddClipboardObject  Extract data from an object and add it to the clipboard.
AddClipboardObjects  Extract data from objects and add it all to the clipboard.
AddClipboardText  Adds a block of text to the clipboard.
DeleteClip  Retrieve the most recently clipped data as a list of files.
GetClipboardFiles  Retrieve the most recently clipped data as a list of files.
PasteClipboardFiles  Performs the 'paste' operation on file items.
Action:DataChannel
Short:This action can be used to place data in a clipboard.

Data can be sent to a Clipboard object via the DataChannel 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.


Action:GetUnlistedField
Short:Special field types are suppored via unlisted fields.

The following unlisted field types are supported by the Clipboard class:

File(Datatype, Index) Where Datatype is a recognised data format (e.g. TEXT) and Index is between 0 and the Items() field. If you don't support multiple clipped items, use an index of zero. On success, this field will return a file location that points to the clipped data.

Items(Datatype) Returns the total number of items available for the specified data type.


Method:AddClipboardFiles()
Short:Add files to the clipboard.
Arguments:
LONG Datatype  Set this argument to indicate the type of data you are copying to the clipboard.
STRING Files  The locations of the files to add.
LONG Flags  Optional flags.

This method is used to add file(s) of information to the clipboard. You add files to the clipboard as a string of locations, each separated by a semi-colon, for copying to the clipboard data cache. The information may then be used by other applications if they understand the clipboard content. You are required to specify the type of data that you are adding through the Datatype parameter. Recognised data types are:

FlagDescription
CLIP_AUDIOAudio clips are any type of audio that is recognised by the Sound class (such as wav's and mp3's).
CLIP_DATARaw information that is uncategorised can be defined as a data clip.
CLIP_FILEFile references are stored as file clips. This type is typically used by file managers and file dialog boxes.
CLIP_IMAGEImages that are recognised by the Picture class may be stored as this type (such as jpeg's and png files).
CLIP_TEXTStandard ASCII and UTF-8 formatted text should be identified through this clip type.

If you specify CLIP_FILE as the Datatype, the location strings will be copied directly to the clipboard and the original file source will not be cached. If the CLIP_FILE type is used in conjunction with the CLF_DELETE flag then the original file source will be deleted if it is copied from the clipboard successfully (this is typically used to implement the 'cut' operation).

Each time that a new set of clip data is added to the clipboard, the history buffer is filled by a new clipping entry. When the history buffer is full, the oldest entry is removed each time that a new clip is added.

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

FlagsDescription
CLF_DELETEMay be set in conjunction with the CLIP_FILE data type if the original file source should be deleted after use.
CLF_EXTENDInstead of replacing the existing clipboard data, add the clip item to what already exists for the specified datatype.
Result
ERR_Okay  The files were added to the clipboard.
ERR_Args  Invalid arguments were specified.
ERR_MissingLoation  The Files argument was not correctly specified.

Method:AddClipboardObject()
Short:Extract data from an object and add it to the clipboard.
Arguments:
LONG Datatype  The type of data that you want the object data to be recognised as, or NULL for automatic recognition.
OBJECTID ObjectID  The object containing the data to add.
LONG Flags  Optional flags.

This method is a simple implementation of the AddClipboardObjects method and is intended primarily for script usage. Please see the AddClipboardObjects method for details on adding objects to the clipboard.

Result
ERR_Okay  The object was added to the clipboard.
ERR_Args  Invalid arguments were specified.

Method:AddClipboardObjects()
Short:Extract data from objects and add it all to the clipboard.
Arguments:
LONG Datatype  The type of data that you want the object data to be recognised as, or NULL for automatic recognition.
*OBJECTID Objects  Array of shared object ID's to add to the clipboard.
LONG 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 you 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 CLIP_IMAGE data category). If an object's class is not recognised by the clipboard system then the data will be stored in the CLIP_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, you need to force the Datatype parameter with one of the available CLIP* types.

This method supports groups of objects in a single clip, thus requires you to pass an array of object ID's, terminated with a NULL entry.

Optional flags that may be passed to this method are the same as those specified in the AddClipboardFiles method. The CLF_DELETE flag has no effect on objects.

This method should always be called directly and not messaged to the clipboard, unless you are able to guarantee that the source objects are shared.

Result
ERR_Okay  The objects were added to the clipboard.
ERR_Args  Invalid arguments were specified.

Method:AddClipboardText()
Short:Adds a block of text to the clipboard.
Arguments:
STRING String  The text to add to the clipboard.

Text can be added to the clipboard using the AddClipboardText method. This is the simplest way of passing text to the clipboard, although passing text through the data channel system may also be convenient in certain circumstances. Text is passed to the clipboard via the String parameter and it must be terminated with a null byte.

Result
ERR_Okay  The object was added to the clipboard.
ERR_Args  Invalid arguments were specified.
ERR_File  Failed to open a new file for output.

Method:DeleteClip()
Short:Retrieve the most recently clipped data as a list of files.
Arguments:
LONG Datatype  The datatype(s) that you want to delete (datatypes may be logically-or'd together).

The DeleteClip method will clear all of the data that has been cached against a particular datatype. You may clear multiple datatypes by OR'ing clip types in the Datatype parameter. Refer to the AddClipboardFiles method for a list of available clip types. If you want to clear all content from the clipboard, use the Clear action instead of this method.

Result
ERR_Okay  The datatype was cleared successfully.
ERR_Args  The required arguments were not specified.

Method:GetClipboardFiles()
Short:Retrieve the most recently clipped data as a list of files.
Arguments:
LONG Datatype  The types of data that you recognise for retrieval are specified here (for example CLIP_TEXT, CLIP_AUDIO, CLIP_FILE...). You may logical-OR multiple data types together. This parameter will be updated to reflect the retrieved data type when the method returns.
LONG Index  If the Datatype parameter is NULL, this parameter may be set to the index of the clip item that you want to retrieve.
*STRING Files  The 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 FreeMemory().
LONG Flags  Result flags are returned in this parameter. If CLF_DELETE is set, you need to delete the files after use in order to support the 'cut' operation.

To retrieve items from a clipboard, you must use the GetClipboardFiles method. You must declare the types of data that you support (or NULL if you recognise all datatypes) so that you are returned a recognisable data format.

The most recent clip is always returned, so if you support text, audio and image clips and the most recent clip is an audio file, any text and image clips on the history buffer will be ignored by this routine. If you want to scan all available clip items, set the Datatype parameter to NULL 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 you read it depends on the resulting Datatype - although you may use the IdentifyFile() function to determine a class that supports the data. Note that the resulting Files array is a memory allocation that must be freed using the FreeMemory() function.

If this method returns the CLF_DELETE flag in the Flags parameter, you must delete the source files after successfully copying out the data. If you are not successful in your operation, do not proceed with the deletion or the user will have lost the original data. When cutting and pasting files within the file system, simply using the file system's 'move file' functionality may be useful for fast file transfer.

Result
ERR_Okay  A matching clip was found and returned.
ERR_Args  Arguments were not specified.
ERR_OutOfRange  The specified Index is out of the range of the available clip items.
ERR_NoData  No clip was available that matched the requested data type.

Method:PasteClipboardFiles()
Synonym:PasteFiles
Short:Performs the 'paste' operation on file items.
Arguments:
STRING Destination  The destination path for the file items. Must be identifiable as a directory location, otherwise the file(s) will be copied to a destination file.
LONG Target  Set this parameter to a valid drawable and the paste operation will open interactive windows (such as progress bars and user confirmations) during the paste operation. This is usually set to the "Desktop" object.

The PasteClipboardFiles method is used to implement file-paste operations for the CLIP_FILE datatype in a convenient way for the developer. The correct handling for both copy and cut operations is implemented for you.

You are required to specify a destination path for the file items. This should be a directory (denoted by a trailing slash or colon character), although you may specify a single target file if you wish.

Confirmation windows are automatically handled by this routine when duplicate file names or errors are encountered during procesing. Any windows will open on whatever drawable you specify as the Target (this should be set to either the Desktop object, or a screen that you have created). If the Target is set to NULL, the routine will discover the most appropriate space for opening new windows. If the Target is set to -1, the routine will overwrite all files by default and not inform the user if errors are encountered.

Result
ERR_Okay  The paste operation was performed successfully (this code is returned even if there are no files to be pasted).
ERR_Args  Invalid arguments were specified.
ERR_File  A non-specific file error occurred during the paste operation.