### IClipboard

  The 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.

### IClipboard - Member Functions and Data by Group

### Constructors & Destructor

Use these members to construct and destruct clipboard objects. You cannot copy or assign IClipboard objects because the copy constructor and assignment operator are private.

~IClipboard

      public:
      virtual ~IClipboard()

  Calls close to close the clipboard if it is open.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

IClipboard

      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.

  clipboardWindow
    A valid window handle used for clipboard data transfer. If you call empty, it establishes this window as the owner of the clipboard.

Exception

  IInvalidParameter | The clipboard window handle is not valid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Clipboard Data Transfer

These 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.

bitmap

      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.

Exception

  IInvalidRequest | No data of the requested format exists on the clipboard.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

data

      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.

Exception

  IInvalidRequest | No data of the requested format exists on the clipboard.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

hasBitmap

      public:
      virtual bool hasBitmap() const

  Returns true if the clipboard has data with the format IClipboard::bitmapFormat.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

hasData

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

hasText

      public:
      virtual bool hasText() const

  Returns true if the clipboard has data with the format IClipboard::textFormat.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setBitmap

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setData

      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.

Exception

  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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setHandle

      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.

Exception

  IAccessError | The operating system's request to place the handle on the clipboard failed.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

setText

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

text

      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.

Exception

  IInvalidRequest | No data of the requested format exists on the clipboard.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Clipboard Formats

Use these members to register and query the clipboard formats. Register all private clipboard formats before using them.

format

  Returns the requested clipboard format. Use the returned format to query or set data on the clipboard.

  Overload 1

      public:
      static IString format(const Cursor& cursor)

  Returns the format of the data at the cursor location.

  cursor
    A valid clipboard cursor.

Exception

  IInvalidParameter | The cursor is not valid.
  IInvalidRequest | No data of the format indicated by the cursor exists on the clipboard.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

  Overload 2

      public:
      static IString format(const FormatHandle& handle)

  Returns the clipboard format of the format handle.

  handle
    The handle of a valid clipboard format.

Exception

  IInvalidRequest | No data of the format handle exists on the clipboard. Ensure that the handle is valid.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

formatAsHandle

      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.

Exception

  IInvalidRequest | No data of the requested format exists on the clipboard.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

formatCount

      public:
      unsigned long formatCount() const

  Returns the number of clipboard formats in the clipboard.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

primaryFormat

      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.

Exception

  IInvalidRequest | No data is on the clipboard.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

registerFormat

      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).

Exception

  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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Clipboard Ownership

The 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.

owner

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### Clipboard Predefined Formats

IClipboard 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.

bitmapFormat

      public:
      static const char * const bitmapFormat

  Defines a bitmap format for data on the clipboard.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

AIX Considerations

  This format is implemented by the ICCCM format PIXMAP.

OS/2 Considerations

  This format is implemented by the OS/2 format SZFMT_BITMAP.

Windows Considerations

  This format is implemented by the Windows format CF_BITMAP.

displayBitmapFormat

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

OS/2 Considerations

  This format is implemented by the OS/2 format SZFMT_DSPBITMAP.

Windows Considerations

  This format is implemented by the Windows format CF_DSPBITMAP.

displayMetafileFormat

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

OS/2 Considerations

  This format is implemented by the OS/2 format SZFMT_DSPMETAFILE.

Windows Considerations

  This format is implemented by the Windows format CF_DSPENHMETAFILE.

displayTextFormat

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

OS/2 Considerations

  This format is implemented by the OS/2 format SZFMT_DSPTEXT.

Windows Considerations

  This format is implemented by the Windows format CF_DSPTEXT.

metafileFormat

      public:
      static const char * const metafileFormat

  Defines a metafile format for data on the clipboard.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

OS/2 Considerations

  This format is implemented by the OS/2 format SZFMT_METAFILE.

Windows Considerations

  This format is implemented by the Windows format CF_ENHMETAFILE.

paletteFormat

      public:
      static const char * const paletteFormat

  Defines a palette format for data on the clipboard.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | No

OS/2 Considerations

  This format is implemented by the OS/2 format SZFMT_PALETTE.

Windows Considerations

  This format is implemented by the Windows format CF_PALETTE.

textFormat

      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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

AIX Considerations

  This format is implemented by the ICCCM format STRING.

OS/2 Considerations

  This format is implemented by the OS/2 format SZFMT_TEXT.

Windows Considerations

  This format is implemented by the Windows CF_TEXT.

### Clipboard Setup

The clipboard setup members handle opening and closing the clipboard and clearing the initial contents of the clipboard.

close

      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.

Exception

  IAccessError | The operating system's request to close the clipboard failed. See the text of the exception for further information.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

empty

      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.

Exception

  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.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

isOpen

      public:
      virtual bool isOpen() const

  Returns true if this IClipboard object has opened the clipboard.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

open

      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.

Exception

  IAccessError | The operating system's request to open the clipboard failed. See the exception text for further information about the failure.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IClipboard - Enumerations

EElementSize

      enum EElementSize { k8Bit=8,
                          k16Bit=16,
                          k32Bit=32 }

  The EElementSize enum identifies the element size of data of a particular private format. It is only used on those platforms that support other than 8-bit oriented data. Currently, only the Motif-based platforms use this enum.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IClipboard - Type Definitions

FormatHandle

      typedef unsigned long FormatHandle

  A FormatHandle is a unique number (typically an atom) used by the operating system to identify a clipboard format.

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

### IClipboard - Inherited Member Functions and Data

#### Inherited Public Functions

  - None

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  - None

#### Inherited Protected Data

  - None