Constructors & DestructorThe IClipboard class provides support for writing data to and reading data from the system clipboard. Although you can only store a single item of data in the clipboard, you can store this item in multiple formats. IClipboard predefines several system clipboard formats. In addition, any application can create and register additional private formats.
Before you can write any data to, or read any data from, the clipboard, you first open it. Only a single application at a time can open the clipboard. If an application tries to open the clipboard but another application already has it open, it waits until the clipboard is available. Therefore, the default behavior of the clipboard classes minimizes the time the clipboard is open.
If you use the default behavior of IClipboard, the clipboard functions that require an open clipboard will open it when needed and close it when finished. You turn off the default behavior of IClipboard when you explicitly open the clipboard by calling IClipboard::open. If you open the clipboard in this manner, IClipboard functions will not close the clipboard. If you explicitly open the clipboard, close the clipboard by calling IClipboard::close. You can turn off the default behavior of IClipboard to place several different formats of your data on the clipboard without opening and closing it to write each format.
All clipboard operations must be associated with a window. You provide this window on the IClipboard constructor. If necessary, IClipboard makes this window the owner of the clipboard. The clipboard owner is the window associated with data written to the clipboard. As such, it is also the window that the operating system sends messages to for events relating to the clipboard. The IClipboard object establishes this window as the system clipboard owner when you call IClipboard::empty. If you call IClipboard::owner before calling empty, your window will not be returned because it is not yet the system clipboard owner.
You process clipboard events by creating and attaching an IClipboardHandler object to your clipboard owner window. In particular, if you use delayed rendering, you must attach an IClipboardHandler object to your clipboard owner window. The window dispatcher calls this handler when a request is made to the clipboard for data that has not been placed there yet.
Because the clipboard should only be kept open for a short time, create IClipboard objects as temporary objects with a short lifetime. This helps ensure that the clipboard is only open for the time necessary.
The IClipboard destructor always closes the clipboard if it is still open.
Constructors & DestructorUse these members to construct and destruct clipboard objects. You cannot copy or assign IClipboard objects because the copy constructor and assignment operator are private.
![[view class]](../images/viewcls1.gif) |
public:
virtual ~IClipboard()
Calls close to close the clipboard if it is open.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
IClipboard(const IWindowHandle& clipboardWindow)
Creates clipboard objects. You construct an IClipboard object by providing the window handle for the object to use for the owner of the clipboard.
| IInvalidParameter | The clipboard window handle is not valid. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Clipboard Data TransferThese members move data to and from the clipboard. You can request delayed rendering of data by calling setText, setBitmap, setHandle, or setData. with a 0 data pointer or handle. For delayed rendering, create an IClipboardHandler. and attach it to the clipboard owner window to process requests to render the data when it is needed. Use delayed rendering when you have complex data formats or multiple data formats. It allows you to postpone moving the data to the clipboard until it is needed.
These members open the clipboard as needed and may close it after transferring data, unless you have explicitly opened the clipboard by calling open.
|
public:
virtual IBitmapHandle bitmap()
If data of the format IClipboard::bitmapFormat exists on the clipboard, this function creates a copy of the bitmap and returns its IBitmapHandle. An IInvalidRequest exception occurs if the format does not exist on the clipboard. You should call the function hasBitmap prior to calling this function to ensure that a bitmap exists on the clipboard.
This function opens the clipboard if it is not already open. It also closes it after copying the bitmap to the clipboard unless you have explicitly opened the clipboard by calling open.
| IInvalidRequest | No data of the requested format exists on the clipboard. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
virtual void* data(const char* format)
Returns a void* value. This value can either be a pointer or handle to the data returned from the clipboard. It is your responsibility to know the type of the value because it is based on the format of the data.
This function always leaves the clipboard open. You must copy the data before closing the clipboard because you lose access to the data after you close the clipboard.
| IInvalidRequest | No data of the requested format exists on the clipboard. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
virtual bool hasBitmap() const
Returns true if the clipboard has data with the format IClipboard::bitmapFormat.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
virtual bool hasData(const char* format) const
Returns true if the clipboard has data of the requested format. It also returns true if 0 is provided as the format and any format exists on the clipboard.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
virtual bool hasText() const
Returns true if the clipboard has data with the format IClipboard::textFormat.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
virtual IClipboard& setBitmap(const IBitmapHandle& bitmap)
Copies the passed bitmap and places the handle of the copy on the clipboard with the format bitmapFormat. Because IClipboard makes a copy of the bitmap, the application is not responsible for maintaining the lifetime of the passed bitmap or for deleting the copy when it is no longer needed.
This function opens the clipboard if it is not already open. It also closes it after placing the bitmap on the clipboard unless you have explicitly opened the clipboard by calling open.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
virtual IClipboard& setData( const char* format, const void* data, unsigned long dataLength )
Copies the passed data buffer and places it on the clipboard with the format specified. Register any private formats before placing data of the indicated format on the clipboard by calling registerFormat. If the pointer to the data is 0, create an IClipboardHandler object to process requests to render the data.
This function opens the clipboard if it is not already open. It also closes it after copying the data to the clipboard unless you have explicitly opened the clipboard by calling open.
| IAccessError | The operating system's request to acquire shared storage failed. |
| IAccessError | The operating system's request to put the data on the clipboard failed. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
virtual IClipboard& setHandle( const char* format, unsigned long handle )
Makes handle shareable (so that it can be accessed by other processes) and places it on the clipboard. Use this function to copy bitmaps and metafiles to the clipboard. setBitmap uses this function to place the bitmap on the clipboard.
This function opens the clipboard if it is not already open. It also closes it after copying the handle to the clipboard unless you have explicitly opened the clipboard by calling open.
| IAccessError | The operating system's request to place the handle on the clipboard failed. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
virtual IClipboard& setText(const char* text)
Copies text and places it on the clipboard with the format textFormat.
This function opens the clipboard if it is not already open. It also closes it after retrieving copying the text to the clipboard unless you have explicitly opened the clipboard by calling open.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
virtual IString text()
Returns textFormat data as an IString object.
If IClipboard::textFormat data exists on the clipboard, it returns the data as an IString object. An IInvalidRequest exception occurs if the format does not exist on the clipboard. Call hasText before calling this function to ensure that text exists on the clipboard.
This function opens the clipboard if it is not already open. It also closes it after retrieving the text from the clipboard unless you have explicitly opened the clipboard by calling open.
| IInvalidRequest | No data of the requested format exists on the clipboard. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Clipboard FormatsUse these members to register and query the clipboard formats. Register all private clipboard formats before using them.
|
Returns the requested clipboard format. Use the returned format to query or set data on the clipboard.
public:
static IString format(const Cursor& cursor)
Returns the format of the data at the cursor location.
| IInvalidParameter | The cursor is not valid. |
| IInvalidRequest | No data of the format indicated by the cursor exists on the clipboard. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
public:
static IString format(const FormatHandle& handle)
Returns the clipboard format of the format handle.
| IInvalidRequest | No data of the format handle exists on the clipboard. Ensure that the handle is valid. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
static FormatHandle formatAsHandle(const char* format)
Returns a clipboard format as a handle. Use this handle to perform clipboard operations that are not supported by the IClipboard class.
| IInvalidRequest | No data of the requested format exists on the clipboard. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
unsigned long formatCount() const
Returns the number of clipboard formats in the clipboard.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
static IString primaryFormat()
Returns the primary format of the data on the clipboard. The primary format is the first format you place on the clipboard after you call empty. An IInvalidRequest results if there is no data on the clipboard.
| IInvalidRequest | No data is on the clipboard. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
static FormatHandle registerFormat( const char* privateFormat, EElementSize elementSize = k8Bit )
Registers privateFormat as a private format and returns its format handle. Use the optional argument elementSize to specify an element size other than 8 bits on those platforms that support it (currently only Motif-based platforms).
| IAccessError | The operating system's request to register the format failed. See the exception text provided with the exception for further details about the failure. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Clipboard OwnershipThe clipboard owner is the window responsible for the data on the clipboard. IClipboard::empty establishes the window you provided on the IClipboard constructor as the clipboard owner. If you use delayed rendering, attach a handler to the clipboard owner window to process the delayed request to put the data on the clipboard.
|
public:
IWindowHandle owner() const
Returns the current clipboard owner window. The owner of the clipboard is established when the clipboard is emptied. If you have provided a clipboard window on the IClipboard constructor but have not yet emptied the clipboard, this function does not return your owner window unless your owner window was already the clipboard owner.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
Clipboard Predefined FormatsIClipboard provides a number of predefined clipboard formats that you can use for many standard data formats. You can use these formats without first registering them. You can also define additional clipboard formats by calling registerFormat before using them.
|
public:
static const char * const bitmapFormat
Defines a bitmap format for data on the clipboard.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
This format is implemented by the ICCCM format PIXMAP.
This format is implemented by the OS/2 format SZFMT_BITMAP.
This format is implemented by the Windows format CF_BITMAP.
|
public:
static const char * const displayBitmapFormat
Defines a bitmap representation of a private data format for clipboard data displayed in a Clipboard Viewer window. The data on the clipboard is identical to bitmapFormat.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
This format is implemented by the OS/2 format SZFMT_DSPBITMAP.
This format is implemented by the Windows format CF_DSPBITMAP.
|
public:
static const char * const displayMetafileFormat
Defines a metafile representation of a private data format displayed in a Clipboard Viewer window. The data on the clipboard is identical to metafileFormat.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
This format is implemented by the OS/2 format SZFMT_DSPMETAFILE.
This format is implemented by the Windows format CF_DSPENHMETAFILE.
|
public:
static const char * const displayTextFormat
Defines a text representation of a private data format displayed in a Clipboard Viewer window. The data on the clipboard is identical to textFormat.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
This format is implemented by the OS/2 format SZFMT_DSPTEXT.
This format is implemented by the Windows format CF_DSPTEXT.
|
public:
static const char * const metafileFormat
Defines a metafile format for data on the clipboard.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
This format is implemented by the OS/2 format SZFMT_METAFILE.
This format is implemented by the Windows format CF_ENHMETAFILE.
|
public:
static const char * const paletteFormat
Defines a palette format for data on the clipboard.
| Windows | OS/2 | AIX |
| Yes | Yes | No |
This format is implemented by the OS/2 format SZFMT_PALETTE.
This format is implemented by the Windows format CF_PALETTE.
|
public:
static const char * const textFormat
Defines a text format for data on the clipboard. The data is an array of text characters with a terminating null character.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
This format is implemented by the ICCCM format STRING.
This format is implemented by the OS/2 format SZFMT_TEXT.
This format is implemented by the Windows CF_TEXT.
Clipboard SetupThe clipboard setup members handle opening and closing the clipboard and clearing the initial contents of the clipboard.
|
public:
virtual IClipboard& close()
Closes the clipboard.
If you manually open the clipboard by calling open, you must also close the clipboard when you are finished transferring data. If you do not close the clipboard, other applications will wait indefinitely when they try to open the clipboard.
| IAccessError | The operating system's request to close the clipboard failed. See the text of the exception for further information. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
virtual IClipboard& empty()
Clears the clipboard of all formats of data and establishes the window provided on the constructor as the clipboard owner.
This function opens the clipboard if it is not already open.
| IAccessError | The operating system's request to empty the clipboard failed. See the text of the exception for further information. |
| IAccessError | The operating system request to establish the owner of the clipboard failed. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
virtual bool isOpen() const
Returns true if this IClipboard object has opened the clipboard.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
public:
virtual IClipboard& open()
Opens the clipboard.
This function prevents other threads or processes from changing or examining the contents of the clipboard. Therefore, only keep the clipboard open for the time needed to place data on or remove data from the clipboard.
All IClipboard functions open the clipboard when needed. Unless you call this function to open the clipboard, they also close the clipboard when they are finished transferring data. Therefore, if you use this function to open the clipboard, you must also explicitly close the clipboard by calling close.
| IAccessError | The operating system's request to open the clipboard failed. See the exception text for further information about the failure. |
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
enum EElementSize { k8Bit=8,
k16Bit=16,
k32Bit=32 }| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
|
typedef unsigned long FormatHandle
A FormatHandle is a unique number (typically an atom) used by the operating system to identify a clipboard format.
| Windows | OS/2 | AIX |
| Yes | Yes | Yes |
