NovaTK::Clipboard Class Reference

List of all members.


Detailed Description

Provides an interface to the system clipboard. A clipboard is used for the sharing of data between applications. The user select data such as text, an image, a file, etc... in another application and paste that into a different application. When an application wants to make data available to the clipboard, it must obtain ownership of the clipboard. Only one window and application may own the clipboard at any time. There can only be one instance of the Clipboard class thus this class cannot be instantiated by applications. Instead a reference to the Clipboard is provided by GetClipboard. Clipboard data can be exchanged in a variety of formats. The format of the clipboard is determined by the application who currently owns the clipboard. Typically it is possible to request a conversion to some formats but not others. NovaTK presents a set of standard clipboard formats that are available across all platforms to assist with portability. Also available are additional formats that are platform-specific. These formats are prefixed with a string identifying the platform, for example: "WIN32_WAVE" or "X11_BITMAP". Applications themselves may also define their own formats if none of the pre-defined formats are suitable. It is advisable to use the NovaTK standard formats in preference to platform-specific formats as it will simplify porting of your application.

Formats:

See also:
GetClipboard

Public Types

enum  Mode { ModeSelection, ModeClipboard }

Public Member Functions

NOVATKAPI void FreeData (void *data)
NOVATKAPI void * GetData (Window *requestor, const NString &format, size_t &size, Mode mode=ModeClipboard)
NOVATKAPI NString GetText (Window *requestor, Mode mode=ModeClipboard)
NOVATKAPI ImageGetImage (Window *requestor, Mode mode=ModeClipboard)
NOVATKAPI bool IsDataAvailable (const NString &format, Mode mode=ModeClipboard) const
NOVATKAPI NStatus SetData (Window *owner, const NString &format, const void *data, size_t len, Mode mode=ModeClipboard)
NOVATKAPI NStatus SetImage (Window *owner, const Image *image, Mode mode=ModeClipboard)
NOVATKAPI NStatus SetText (Window *owner, const NString &str, Mode mode=ModeClipboard)

Member Enumeration Documentation

The mode specifies which clipboard mechanism is to be used. For most systems, this will ONLY be Clipboard. X11, however, supports two clipboard mechanisms: Selection and Clipboard. Otherwise known as Primary and Clipboard. The Selection mode is ONLY supported under X11 and is not availabe on any other platforms.

Enumerator:
ModeSelection  [X11 ONLY] Whenever text is selected in an application, it is made available to the clipboard and is typically pasted using the middle mouse button.
ModeClipboard  This mode represents the most common operation of the clipboard where the user can select something such as text, cut/copy the selection and paste it into another application or the same application.


Member Function Documentation

void NovaTK::Clipboard::FreeData ( void *  data  ) 

Releases memory allocated by GetData. This function must be used with the data returned by GetData instead of attempting to free the data yourself as some platforms may require special procedures for freeing the shared data obtained from their clipboard.

void * NovaTK::Clipboard::GetData ( Window requestor,
const NString format,
size_t &  size,
Mode  mode = ModeClipboard 
)

Obtains the raw data stored on the clipboard. It is up to the application to convert the data to something useful.

Parameters:
requestor - The window who is requesting the data.
format - The desired format of the data.
size - The size of the data in bytes will be stored in the referenced variable.
mode - The desired clipboard mechanism. For most purposes this should be left as ModeClipboard.
Returns:
A pointer to the data from the clipboard upon success or NULL upon failure. Reasons for failure include: The clipboard has no owner(No data stored), the clipboard data could not be converted to the requested format or the data transfer failed. Memory allocated for the returned data MUST be freed using FreeData.

NString NovaTK::Clipboard::GetText ( Window requestor,
Mode  mode = ModeClipboard 
)

Obtains the clipboard data as text. The data stored on the clipboard must be in a format that can be converted to a string. Thus if the data stored on the clipboard is an image, for example, this function will fail.

Parameters:
requestor - The window who is requesting the data.
mode - The desired clipboard mechanism. For most purposes this should be left as ModeClipboard.
Returns:
A string containing the text from clipboard or an empty string if no text was retrieved from the clipboard.

Image * NovaTK::Clipboard::GetImage ( Window requestor,
Mode  mode = ModeClipboard 
)

Obtains the clipboard data and converts it to an Image. The data stored on the clipboard must be in a format that can be converted to an Image. Thus if the data stored on the clipboard is text, for example, this function will fail. Alternatively, for Image-compatible formats, one can call GetData instead to obtain the raw Image data which has been converted to the format specified by Image::GetFormat.

Note:
If using GetData to retrieve image data, NovaTK will store the image width and height in the first 8 bytes of the returned data with the two values each occupying 4 bytes. As a result the data returned is the size of the image data plus 8 bytes.

bool NovaTK::Clipboard::IsDataAvailable ( const NString format,
Mode  mode = ModeClipboard 
) const

Returns:
TRUE if there is data available that can be converted to the specified format, otherwise returns FALSE.

NStatus NovaTK::Clipboard::SetData ( Window owner,
const NString format,
const void *  data,
size_t  len,
Mode  mode = ModeClipboard 
)

Claims ownership of the clipboard and sets the data stored on the clipboard as well as specifies the format of the data.

Parameters:
owner - Specifies the window that is claiming ownership of the clipboard.
format - Specifies the format of the data.
data - A pointer to the raw data to be stored on the clipboard.
len - The size of the data in bytes.
mode - The desired clipboard mechanism. For most purposes this should be left as ModeClipboard.
Returns:
NOVATK_SUCCESS upon success.

NStatus NovaTK::Clipboard::SetImage ( Window owner,
const Image image,
Mode  mode = ModeClipboard 
)

Claims ownership of the clipboard and stores the specified image on the clipboard.

Parameters:
owner - Specifies the window that is claiming ownership of the clipboard.
image - A pointer to the image to be stored on the clipboard. The image will be converted as needed by NovaTK.
mode - The desired clipboard mechanism. For most purposes this should be left as ModeClipboard.
Returns:
NOVATK_SUCCESS upon success.

NStatus NovaTK::Clipboard::SetText ( Window owner,
const NString str,
Mode  mode = ModeClipboard 
)

Claims ownership of the clipboard and stores the specified text on the clipboard.

Parameters:
owner - Specifies the window that is claiming ownership of the clipboard.
str - A string containing the text to be stored on the clipboard.
mode - The desired clipboard mechanism. For most purposes this should be left as ModeClipboard.
Returns:
NOVATK_SUCCESS upon success.


The documentation for this class was generated from the following files:

Generated on Sat Sep 13 22:34:18 2008 for NovaTK by  doxygen 1.5.5