Clipboard
PBClipboardReader
Opaque object handle: An object capturing the state of a clipboard at the point in time when it was created. Further modifications to the clipboard will not be detected by the reader object.
This object maintains an internal reference count. When the reference count reaches zero, the object will be automatically deallocated. To increment the reference count, call PBClipboardReaderRetain; to decrement the reference count, call PBClipboardReaderRelease. These functions are thread-safe.
See Also
PBClipboardWriter
Opaque object handle: The object used to modify the clipboard. Create with PBClipboardBeginWriting and submit with PBClipboardEndWriting.
This object maintains an internal reference count. When the reference count reaches zero, the object will be automatically deallocated. To increment the reference count, call PBClipboardWriterRetain; to decrement the reference count, call PBClipboardWriterRelease. These functions are thread-safe.
See Also
PBClipboardID
Enumeration/bitset of type uint64_t: A identifier representing a clipboard. Values not listed in this enumeration can be returned by PBClipboardAllocate. Identifiers are not reused while the workspace is running.
Constants
PBClipboardID_INVALID
PBClipboardID_INVALID = 0
Do not use.
PBClipboardID_PRIMARY
PBClipboardID_PRIMARY = 1
The clipboard that the user interacts with using the "Copy" and "Paste" commands.
See Also
PBClipboardDataCallback
Callback:
Syntax (C/C++)
void PBClipboardDataCallback(PBStreamRef writeStream);
You can create a callback of this type from a function pointer with the above signature using PBClipboardDataCallback_Make
.
Syntax (Python)
ClipboardDataCallback(writeStream)
Parameters and Return Values
[in] writeStream (referenced PBStream):
PBClipboardHasString
Function: Test if the clipboard contains a text string.
Syntax (C/C++)
bool PBClipboardHasString();
Syntax (Python)
ClipboardHasString() -> (hasString)
Parameters and Return Values
[out] hasString (bool
): True if the primary clipboard contains a format compatible with "text/plain".
PBClipboardReadString
Function: Read a text string from the clipboard.
Syntax (C/C++)
bool PBClipboardReadString(/* output */ MutStr * __restrict text);
Syntax (Python)
ClipboardReadString() -> (success, text)
Parameters and Return Values
[out] success (bool
): True if the clipboard contained a text string and it was read successfully.
[out] text (owned string): The text string. Free with PBHeapFree.
Discussion
Only clipboard items that can have a format compatible with "text/plain" will be returned.
If there are multiple such items, then they will be concatenated, separated by the newline character.
Example (C/C++)
PBStr string;
if (PBClipboardReadString(&string)) {
PBAlertAddSimpleError(window, PB_STR(string), PB_STR(""));
PBHeapFree(string.ptr);
}
PBClipboardWriteString
Function: Write a single UTF-8 string onto the clipboard.
Syntax (C/C++)
bool PBClipboardWriteString(ConstStr text);
Syntax (Python)
ClipboardWriteString(text) -> (success)
Parameters and Return Values
[in] text (referenced string): The UTF-8 string to write.
[out] success (bool
): True if the function succeeded. The function may fail if the system is low on memory.
Discussion
This is a convenience function that calls PBClipboardBeginWriting, PBClipboardAdd and PBClipboardEndWriting.
Example (C/C++)
PBClipboardWriteString(PB_STR("copied text"));
PBClipboardBeginWriting
Function: Start modifying the clipboard.
Syntax (C/C++)
PBClipboardWriterPtr _Nullable PBClipboardBeginWriting();
Syntax (Python)
ClipboardBeginWriting() -> (writer)
Parameters and Return Values
[out] writer (nullable owned PBClipboardWriter): The object used to write to the clipboard. When finished, call PBClipboardEndWriting to submit the new values.
Discussion
See PBClipboardEndWriting for example usage and further discussion about modifying the clipboard.
See Also
PBClipboardEndWriting
Function: Finish modifying the clipboard.
Syntax (C/C++)
bool PBClipboardEndWriting(PBClipboardWriterPtr writer,
PBClipboardID clipboardID);
Syntax (Python)
ClipboardEndWriting(writer, clipboardID) -> (success)
Parameters and Return Values
[in] writer (owned PBClipboardWriter): The clipboard writer object. It is consumed by this function; you do not need call PBClipboardWriterRelease afterwards.
[in] clipboardID (PBClipboardID): The ID of the clipboard to modify.
[out] success (bool
): Indicates whether the clipboard was successfully updated. Reasons for failure include: the system is low on memory; the clipboard ID is invalid.
Discussion
This overwrites all the existing data on the clipboard.
Any existing PBClipboardReader objects reading from this clipboard will continue to read the previous values. If a new PBClipboardReader object is opened with PBClipboardRead, then it will immediately see the new values.
If any value contains a non-null PBClipboardDataCallback, then the calling process will be kept alive until the clipboard is deallocated or the values are overwritten. At this point, the data callbacks will be freed. Note that if the event the clipboard cannot be modified, the data callbacks may be immediately freed inside this function.
Example (C/C++)
PBClipboardWriter *clipboard = PBClipboardBeginWriting();
PBClipboardAdd(clipboard, 0, PB_STR("text/plain"), PB_STR("first item"));
PBClipboardAdd(clipboard, 0, PB_STR("text/html"), PB_STR("<b>first item</b>"));
PBClipboardAdd(clipboard, 1, PB_STR("text/plain"), PB_STR("second item"));
PBClipboardAdd(clipboard, 1, PB_STR("text/html"), PB_STR("<i>second item</i>"));
PBClipboardEndWriting(clipboard, PBClipboardID_PRIMARY);
See Also
PBClipboardAdd
Function: Add data to a clipboard writer.
Syntax (C/C++)
void PBClipboardAdd(PBClipboardWriterRef writer, uint32_t itemIndex,
ConstStr mimeType, ConstStr data);
Syntax (Python)
ClipboardAdd(writer, itemIndex, mimeType, data)
Parameters and Return Values
[in] writer (referenced PBClipboardWriter): The clipboard writer object.
[in] itemIndex (uint32_t
): The index of the logical item this value represents. Multiple pieces of data can be added to a given item, as long as they have different formats.
[in] mimeType (referenced string): A MIME type string giving the format of this value. For example, "text/plain" is used for plain text.
[in] data (referenced string): The item's data, in the format given by the MIME type.
See Also
PBClipboardAddWithCallback
Function: Add data to a clipboard writer with a callback that will provide it on-demand.
Syntax (C/C++)
void PBClipboardAddWithCallback(PBClipboardWriterRef writer, uint32_t itemIndex,
ConstStr mimeType, PBClipboardDataCallback callback);
Syntax (Python)
ClipboardAddWithCallback(writer, itemIndex, mimeType, callback)
Parameters and Return Values
[in] writer (referenced PBClipboardWriter): The clipboard writer object.
[in] itemIndex (uint32_t
): The index of the logical item this value represents. Multiple pieces of data can be added to a given item, as long as they have different formats.
[in] mimeType (referenced string): A MIME type string giving the format of this value. For example, "text/plain" is used for plain text.
[in] callback (PBClipboardDataCallback): A callback to provide the value's data on demand. This is run on a special thread. Do not access the clipboard while in this callback, and do not run events with PBRunAsEvent. Make sure that this thread will not lock any resources that could cause deadlock with anywhere in the application that can read from the clipboard. This callback is freed once the data in the clipboard is overwritten and no readers point to it.
See Also
PBClipboardRead
Function: Begin reading a clipboard.
Syntax (C/C++)
PBClipboardReaderPtr _Nullable PBClipboardRead(PBClipboardID clipboard);
Syntax (Python)
ClipboardRead(clipboard) -> (reader)
Parameters and Return Values
[in] clipboard (PBClipboardID): The ID of the clipboard from which to read.
[out] reader (nullable owned PBClipboardReader): The clipboard reader object, or null should the clipboard be inaccessible.
Discussion
If the function returns a non-null PBClipboardReader, then it must be released with PBClipboardReaderRelease.
The reader captures the current state of the clipboard. If the clipboard is modified or deallocated some time after calling this function, then the reader will still contain the same values as when it was opened.
Example (C/C++)
PBClipboardReader *reader = PBClipboardRead(PBClipboardID_PRIMARY);
if (reader) {
// ...
PBClipboardReaderRelease(reader);
}
See Also
- PBClipboardGetItemCount
- PBClipboardGetItemData
- PBClipboardRemoveFromClipboard
- PBClipboardBeginWriting
PBClipboardGetItemCount
Function: Get the number of available items from a clipboard reader.
Syntax (C/C++)
uint32_t PBClipboardGetItemCount(PBClipboardReaderRef reader);
Syntax (Python)
ClipboardGetItemCount(reader) -> (itemCount)
Parameters and Return Values
[in] reader (referenced PBClipboardReader): The clipboard reader, from PBClipboardRead.
[out] itemCount (uint32_t
): The number of items on the clipboard. This may be different from the number of values; each item may be available in multiple formats, each of which has an associated value.
Example (C/C++)
uint32_t itemCount = PBClipboardGetItemCount(reader);
PBStr data;
for (uint32_t i = 0; i < itemCount; i++) {
if (PBClipboardGetItemData(reader, i, PB_STR("text/plain"), &data)) {
...
PBHeapFree(data.ptr);
}
}
See Also
PBClipboardGetItemFormat
Function: Get the MIME type string for a format of an item on the clipboard.
Syntax (C/C++)
bool PBClipboardGetItemFormat(PBClipboardReaderRef reader, uint32_t itemIndex,
uint32_t formatIndex, /* in-out */ IOStr * __restrict mimeType);
Syntax (Python)
ClipboardGetItemFormat(reader, itemIndex, formatIndex, mimeType) -> (success)
Parameters and Return Values
[in] reader (referenced PBClipboardReader): The clipboard reader, from PBClipboardRead.
[in] itemIndex (uint32_t
): The index of the item. This should be less than the result of PBClipboardGetItemCount.
[in] formatIndex (uint32_t
): The index of the format within the item.
[in-out] mimeType (string buffer): A buffer in which the MIME type string is placed. This should be able to store at least 100 bytes.
[out] success (bool
): Indicates whether the item had a format with this index.
Discussion
Each item can have multiple formats. The first format index is 0, and then additional formats are assigned indices sequentially ascending.
If the item does not have a format with the given index, then the MIME type string buffer is set to an empty string.
Example (C/C++)
char _mimeType[100];
PBBuf mimeType = { .ptr = &_mimeType[0], .cap = sizeof(_mimeType) };
for (uint32_t formatIndex = 0; PBClipboardGetItemFormat(reader, itemIndex, formatIndex, &mimeType); formatIndex++) {
printf("%d: %.*s", formatIndex, (int) mimeType.len, mimeType.ptr);
...
}
See Also
PBClipboardItemHasFormat
Function: Tests whether an item on a clipboard is available in a specified format.
Syntax (C/C++)
bool PBClipboardItemHasFormat(PBClipboardReaderRef reader, uint32_t itemIndex,
ConstStr mimeType);
Syntax (Python)
ClipboardItemHasFormat(reader, itemIndex, mimeType) -> (hasFormat)
Parameters and Return Values
[in] reader (referenced PBClipboardReader): The clipboard reader, from PBClipboardRead.
[in] itemIndex (uint32_t
): The index of the item. If this is greater than or equal to PBClipboardGetItemCount, then false is returned.
[in] mimeType (referenced string): The MIME type of the format to test for this item.
[out] hasFormat (bool
): True if the format is available; otherwise, false.
Discussion
If an item does not have the "text/plain" format but it does have another "text/" format, then a "text/plain" format will be synthesized from the latter. More formats may be synthesized automatically in later implementations.
Example (C/C++)
bool hasText = PBClipboardItemHasFormat(reader, itemIndex, PB_STR("text/plain"));
See Also
PBClipboardGetItemData
Function: Get the data of an item on the clipboard.
Syntax (C/C++)
bool PBClipboardGetItemData(PBClipboardReaderRef reader, uint32_t itemIndex,
ConstStr formatMimeType, /* output */ MutStr * __restrict data);
Syntax (Python)
ClipboardGetItemData(reader, itemIndex, formatMimeType) -> (success, data)
Parameters and Return Values
[in] reader (referenced PBClipboardReader): The clipboard reader, from PBClipboardRead.
[in] itemIndex (uint32_t
): The index of the item. This should be less than the result of PBClipboardGetItemCount.
[in] formatMimeType (referenced string): The MIME type of the format of this item to retrieve. You can determine what formats an items is available with PBClipboardGetItemFormat and PBClipboardItemHasFormat.
[out] success (bool
): Indicates whether the operation completed successfully. Reasons for failure include: the item is not available in the requested format; the system is low on memory.
[out] data (owned string): The formatted item data. Free the returned pointer with PBHeapFree. On failure, an empty string is returned.
Discussion
If an item does not have the "text/plain" format but it does have another "text/" format, then a "text/plain" format will be synthesized from the latter. More formats may be synthesized automatically in later implementations.
This call will block until all the data is read. Notably, if the application that placed the data on the clipboard used a PBClipboardDataCallback, then the calling process will block until that process has provided all the requested data. If you expect a large amount of data to be transferred, then it is recommended that you use PBClipboardOpenItemStream instead, and read the data asynchronously.
This function cannot be used with formats starting with "function/"; for these, use PBClipboardCallItemFunction instead.
Example (C/C++)
PBStr data;
if (PBClipboardGetItemData(reader, itemIndex, PB_STR("text/plain"), &data)) {
printf("data: %.*s", (int) data.len, data.ptr);
PBHeapFree(data.ptr);
}
See Also
- PBClipboardOpenItemStream
- PBClipboardGetItemCount
- PBClipboardGetItemFormat
- PBClipboardItemHasFormat
- PBClipboardCallItemFunction
PBClipboardOpenItemStream
Function: Get the data of an item on the clipboard asynchronously.
Syntax (C/C++)
PBStreamPtr _Nullable PBClipboardOpenItemStream(PBClipboardReaderRef reader,
uint32_t itemIndex, ConstStr formatMimeType);
Syntax (Python)
ClipboardOpenItemStream(reader, itemIndex, formatMimeType) -> (stream)
Parameters and Return Values
[in] reader (referenced PBClipboardReader): The clipboard reader, from PBClipboardRead.
[in] itemIndex (uint32_t
): The index of the item. This should be less than the result of PBClipboardGetItemCount.
[in] formatMimeType (referenced string): The MIME type of the format of this item to retrieve. You can determine what formats an items is available with PBClipboardGetItemFormat and PBClipboardItemHasFormat.
[out] stream (nullable owned PBStream): The stream from which the formatted item data can be read, or null if the call failed. If non-null, this must be released using PBStreamRelease.
Discussion
If an item does not have the "text/plain" format but it does have another "text/" format, then a "text/plain" format will be synthesized from the latter. More formats may be synthesized automatically in later implementations.
This function cannot be used with formats starting with "function/"; for these, use PBClipboardCallItemFunction instead.
Example (C/C++)
PBStream *stream = PBClipboardGetItemData(reader, itemIndex, PB_STR("text/plain"));
size_t countRead = 0;
char buffer[64];
if (stream) {
PBStreamRead(stream, &buffer[0], sizeof(buffer), &countRead);
PBStreamRelease(stream);
}
See Also
PBClipboardCallItemFunction
Function: Call a function placed on a clipboard.
Syntax (C/C++)
void PBClipboardCallItemFunction(PBClipboardReaderRef reader, uint32_t itemIndex,
ConstStr formatMimeType);
Syntax (Python)
ClipboardCallItemFunction(reader, itemIndex, formatMimeType)
Parameters and Return Values
[in] reader (referenced PBClipboardReader): The clipboard reader, from PBClipboardRead.
[in] itemIndex (uint32_t
): The index of the item. This should be less than the result of PBClipboardGetItemCount.
[in] formatMimeType (referenced string): The MIME type of the function. This must start with "function/".
Discussion
This function calls the corresponding data callback of value and ignores the returned data. This is separate from the other clipboard reading functions to ensure that values whose evaluations cause side-effects are not accidentally accessed by applications trying to enumerate all clipboard formats.
This is asynchronous: it does not wait for the called function to complete.
Example (C/C++)
PBClipboardCallItemFunction(message->dndInfo.clipboard, itemIndex, PB_STR("function/playbit.dnd-did-move"));
See Also
PBClipboardRemoveFromClipboard
Function: Removes data placed on a clipboard.
Syntax (C/C++)
void PBClipboardRemoveFromClipboard(PBClipboardReaderRef reader);
Syntax (Python)
ClipboardRemoveFromClipboard(reader)
Parameters and Return Values
[in] reader (referenced PBClipboardReader): The clipboard reader, from PBClipboardRead.
Discussion
If the clipboard has not been modified since this clipboard reader was opened, then clear the contents of the clipboard. If it has been modified, then this does nothing.
Example (C/C++)
PBClipboardRemoveFromClipboard(reader);
See Also
PBClipboardAllocate
Function: Allocate a private clipboard for data transfer.
Syntax (C/C++)
PBClipboardID PBClipboardAllocate();
Syntax (Python)
ClipboardAllocate() -> (clipboard)
Parameters and Return Values
[out] clipboard (PBClipboardID): The ID of the newly allocated clipboard, or PBClipboardID_INVALID if the operation fails.
Discussion
The allocated clipboard is attached to your process. When your process exits, the clipboard will be automatically deallocated, if it hasn't already been deallocated with PBClipboardDeallocate.
Clipboard IDs are not reused while the workspace is running.
Example (C/C++)
PBClipboardID id = PBClipboardAllocate();
if (id != PBClipboardID_INVALID) {
PBClipboardBeginWriting(...);
...
PBClipboardEndWriting(..., id);
/* send id to another process so it can read the data */
}
See Also
PBClipboardDeallocate
Function: Deallocate a private clipboard ID.
Syntax (C/C++)
void PBClipboardDeallocate(PBClipboardID clipboard);
Syntax (Python)
ClipboardDeallocate(clipboard)
Parameters and Return Values
[in] clipboard (PBClipboardID): The ID of the private clipboard.
Discussion
This cannot be used with system-provided clipboards.
If the specified clipboard has already been deallocated, this does nothing.
Example (C/C++)
PBClipboardReader *reader = PBClipboardRead(id);
PBClipboardDeallocate(id);
if (reader) {
/* read the data */
PBClipboardReaderRelease(reader);
}