class PClipboard: public PObject

A class representing the system clipboard.

Inheritance:


Public Classes

[more]enum Format
Pre-defined formats for data that may be stored or transferred in the clipboard.

Public Methods

[more] PClipboard ( const PInteractor * owner )
Create a clipboard object to allow access to the system clipboard.
[more] ~PClipboard ()
End access to the system clipboard deleting the clipboard object.
[more]BOOL InUse ()
Determine if the clipboard was already in use.
[more]BOOL HasFormat ( Format fmt )
Determine if there is data in the clipboard of the specified format.
[more]BOOL HasFormat ( const PString & fmt )
Determine if there is data in the clipboard of the specified format.
[more]DWORD GetSize ( const PString & fmt )
Get the size of the data in the clipboard for the specifed format.
[more]BOOL GetData ( const PString & fmt, void * data, DWORD max )
Get the data from the clipboard to the specified memory block.
[more]BOOL SetData ( const PString & fmt, const void * data, DWORD len )
Set the data in the clipboard to the data specified by the memory block and length.
[more]PString GetText ()
Get the data from the clipboard as a string if it is available in the Text format.
[more]BOOL SetText ( const PString & str )
Set the data in the clipboard to the text specified by the string in the Text format.
[more]PPixelImage GetPixels ()
Get the data from the clipboard as a pixel image if it is available in the Pixels format.
[more]BOOL SetPixels ( const PPixelImage & img )
Set the data in the clipboard to the pixel image specified in the Pixels format.
[more]PPictImage GetPict ()
Get the data from the clipboard as a picture image if it is available in the Picture format.
[more]BOOL SetPict ( const PPictImage & pic )
Set the data in the clipboard to the picture image specified in the Picture format.

Public

[more] New functions for class

Protected Fields

[more]const PInteractor* owner
The interactor that öwns" the open clipboard.


Inherited from PObject:

Public

Run Time Type functions

Comparison functions

I/O functions

Miscellaneous functions


Documentation

A class representing the system clipboard. This is a platform dependent entity for temporary storage and/or transfering between applications of user data in a set of possible formats.

There are only a few primitive data types supported, with all remaining types supported through a generic mechanism. The types are simple text, pixel images and picture images. All other types are represented by an arbitrary string and the data is placed in a simple memory block. The interpretation of that memory block is application dependent.

The clipboard only ever contains one item of data, though this data may be available in a number of different formats. For example, a string contained in a drawing package may be placed in the clipboard in several ways: as a simple ANSI character sequence, as a pixel image of the rendered font, as a sequence of drawing commands that set the font, colours and a draw text command, or, finally, as an internal format containing the raw data structure used by the package.

When transferring data between applications, only those that recognise the format name string will be able to use that format of data. Typically, an application places data in the clipboard in multiple formats for maximum portability across applications.

o PClipboard( const PInteractor * owner )
Create a clipboard object to allow access to the system clipboard. As the clipboard is a system resource, it can only be accessed by one user at a time. This locking mechanism is made based on the interactor. Only one interactor can öwn" the clipboard at any given time. The destruction of this object releases the lock.
Parameters:
owner - The interactor that öwns" the clipboard.

o ~PClipboard()
End access to the system clipboard deleting the clipboard object. It is very important that the clipboard object is destroyed as this releases the lock on the clipboard preventing access by any other user, even in other applications.

o New functions for class

oBOOL InUse()
Determine if the clipboard was already in use. If this returns TRUE then all other clipboard functions will fail.

Returns:
TRUE if clipboard cannot be used.

oenum Format
Pre-defined formats for data that may be stored or transferred in the clipboard. There are individual functions available to access each type of data in the correct format.

o Text
Simple lines of text

o Image
Pixel image

o Picture
Picture image

oBOOL HasFormat( Format fmt )
Determine if there is data in the clipboard of the specified format.

Returns:
TRUE if data can be retrieved in the required format.
Parameters:
fmt - Format type identifier to check for.

oBOOL HasFormat( const PString & fmt )
Determine if there is data in the clipboard of the specified format.

Returns:
TRUE if data can be retrieved in the required format.
Parameters:
fmt - Format type name string to check for.

oDWORD GetSize( const PString & fmt )
Get the size of the data in the clipboard for the specifed format. This is for the generic data format as the pre-defined format data operations inherently know the size of the data being transferred.

Returns:
size in bytes of the data.
Parameters:
fmt - Format type name string to check for.

oBOOL GetData( const PString & fmt, void * data, DWORD max )
Get the data from the clipboard to the specified memory block. The size of the memory block must be greater than or equal to the length of the data in the clipboard.

This function will fail if the clipboard was already in use when the object was constructed.

Returns:
TRUE if the data was completely copied.
Parameters:
fmt - Format type name string to check for.
data - Pointer to memory to receive the data.
max - Size of the block of memory.

oBOOL SetData( const PString & fmt, const void * data, DWORD len )
Set the data in the clipboard to the data specified by the memory block and length.

The previous contents of the clipboard is lost on the first call to SetData for a particular clipboard object. Further calls to data setting functions will add the new format to the clipboard and not lose the previously set data. Once the PClipboard object is destroyed the next construction resets this mechanism so that data is lost once more.

This function will fail if the clipboard was already in use when the object was constructed.

Returns:
TRUE if the data was completely copied.
Parameters:
fmt - Format type name string to check for.
data - Pointer to memory block to transfer.
len - Number of bytes to transfer to clipboard.

oPString GetText()
Get the data from the clipboard as a string if it is available in the Text format.

This function will fail, returning an empty string, if the clipboard was already in use when the object was constructed.

Returns:
String that was in the clipboard or empty string if the clipboard data was not available in this format.

oBOOL SetText( const PString & str )
Set the data in the clipboard to the text specified by the string in the Text format.

The previous contents of the clipboard is lost on the first call to SetText for a particular clipboard object. Further calls to data setting functions will add the new format to the clipboard and not lose the previously set data. Once the PClipboard object is destroyed the next construction resets this mechanism so that data is lost once more.

This function will fail if the clipboard was already in use when the object was constructed.

Returns:
TRUE if the data was copied.
Parameters:
str - New text to place in the clipboard.

oPPixelImage GetPixels()
Get the data from the clipboard as a pixel image if it is available in the Pixels format.

This function will fail, returning an empty image, if the clipboard was already in use when the object was constructed.

Returns:
String that was in the clipboard or an empty (1 bit) image if the clipboard data was not available in this format.

oBOOL SetPixels( const PPixelImage & img )
Set the data in the clipboard to the pixel image specified in the Pixels format.

The previous contents of the clipboard is lost on the first call to SetPixels for a particular clipboard object. Further calls to data setting functions will add the new format to the clipboard and not lose the previously set data. Once the PClipboard object is destroyed the next construction resets this mechanism so that data is lost once more.

This function will fail if the clipboard was already in use when the object was constructed.

Returns:
TRUE if the data was copied.
Parameters:
img - Pixel image to place into the clipboard.

oPPictImage GetPict()
Get the data from the clipboard as a picture image if it is available in the Picture format.

This function will fail, returning an empty image, if the clipboard was already in use when the object was constructed.

Returns:
String that was in the clipboard or an empty image if the clipboard data was not available in this format.

oBOOL SetPict( const PPictImage & pic )
Set the data in the clipboard to the picture image specified in the Picture format.

The previous contents of the clipboard is lost on the first call to SetPict for a particular clipboard object. Further calls to data setting functions will add the new format to the clipboard and not lose the previously set data. Once the PClipboard object is destroyed the next construction resets this mechanism so that data is lost once more.

This function will fail if the clipboard was already in use when the object was constructed.

Returns:
TRUE if the data was copied.
Parameters:
pic - Picture image to place into the clipboard.

oconst PInteractor* owner
The interactor that öwns" the open clipboard.


This class has no child classes.

Alphabetic index HTML hierarchy of classes or Java



This page was generated with the help of DOC++.