This chapter provides reference material for the clipboard API defined in Clipboard.h
. It covers:
Clipboard Structures and Types
Clipboard Constants
Clipboard Functions and Macros
Clipboard Structures and Types
ClipboardItem Struct
Purpose
Private structure that defines an item on the clipboard.
Declared In
Clipboard.h
Prototype
typedef struct ClipboardItemTag ClipboardItem
Fields
Clipboard Constants
ClipboardFormatType Typedef
Purpose
Specifies the type of data to add to the clipboard or retrieve from the clipboard.
Declared In
Clipboard.h
Prototype
typedef Enum8 ClipboardFormatType
Constants
-
clipboardText
- Textual data. This is the most commonly used clipboard.
-
clipboardInk
- Reserved.
-
clipboardBitmap
- Bitmap data.
Comments
Clipboards for each type of data are separately maintained. That is, if you add a string of text to the clipboard, then add a bitmap, then ask to retrieve a clipboardText
item from the clipboard, you will receive the string you added before the bitmap; the bitmap does not overwrite textual data and vice versa.
Miscellaneous Constants
Purpose
Other constants declared in Clipboard.h
.
Declared In
Clipboard.h
Constants
-
#define numClipboardFormats 3
- The number of possible clipboard formats. See
ClipboardFormatType
.
Clipboard Functions and Macros
ClipboardAddItem Function
Purpose
Adds the item passed to the specified clipboard. Replaces the current item (if any) of that type.
Declared In
Clipboard.h
Prototype
void ClipboardAddItem ( const ClipboardFormatTypeformat
, const void*ptr
, size_tlength
)
Parameters
-
→ format
- Text, ink, bitmap, and so on. See
ClipboardFormatType
. -
→
ptr
- Pointer to the item to place on the clipboard.
-
→ length
- Size in bytes of the item to place on the clipboard.
Returns
Comments
The clipboard makes a copy of the data that you pass to this function. Thus, you may free any data that you've passed to the clipboard without destroying the contents of the clipboard. You may also add constant data or stack-based data to the clipboard.
See Also
ClipboardAppendItem Function
Purpose
Appends data to the item on the clipboard.
Declared In
Clipboard.h
Prototype
status_t ClipboardAppendItem ( const ClipboardFormatTypeformat
, const void*ptr
, size_tlength
)
Parameters
-
→ format
- Text, ink, bitmap, and so on. See
ClipboardFormatType
. This function is intended to be used only for theclipboardText
format. -
→
ptr
- Pointer to the data to append to the item on the clipboard.
-
→ length
- Size in bytes of the data to append to the clipboard.
Returns
0 upon success or memErrNotEnoughSpace
if there is not enough space to append the data to the clipboard.
Comments
This function differs from ClipboardAddItem()
in that it does not overwrite data already on the clipboard. It allows you to create a large text item on the clipboard from several small disjointed pieces. When other applications retrieve the text from the clipboard, it's retrieved as a single unit.
This function simply appends the specified item to the item already on the clipboard without attempting to parse the format. It's assumed that you'll call it several times over a relatively short interval and that no other application will attempt to retrieve text from the clipboard before your application is finished appending.
ClipboardGetItem Function
Purpose
Returns the handle of the contents of the clipboard of a specified type and the length of a clipboard item.
Declared In
Clipboard.h
Prototype
MemHandle ClipboardGetItem ( const ClipboardFormatTypeformat
, size_t*length
)
Parameters
-
→ format
- Text, ink, bitmap, and so on. See
ClipboardFormatType
. -
←
length
- The length in bytes of the clipboard item is returned here.
Returns
Comments
The handle returned is a handle to the actual clipboard memory. It is not suitable for passing to any API that modifies memory (such as FldSetTextHandle()
). Consider this to be read-only access to the data. Copy the contents of the clipboard to your application's own storage as soon as possible and use that reference instead of the handle returned by this function.
Don't free the handle returned by this function; it is freed when a new item is added to the clipboard.
Text retrieved from the clipboard does not have a null terminator. You must use the length
parameter to determine the length in bytes of the string you've retrieved.