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

• PBClipboardRead
• PBClipboardGetItemCount

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

• PBClipboardBeginWriting
• PBClipboardEndWriting

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

• PBClipboardAllocate
• PBClipboardDeallocate
• PBClipboardBeginWriting
• PBClipboardRead

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

• PBClipboardAdd
• PBClipboardEndWriting
• PBClipboardRead
• PBClipboardAllocate

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

• PBClipboardBeginWriting

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

• PBClipboardBeginWriting
• PBClipboardEndWriting
• PBClipboardAddWithCallback

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

• PBClipboardAdd

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

• PBClipboardRead
• PBClipboardItemHasFormat
• PBClipboardGetItemData

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
• PBClipboardGetItemData

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

• PBClipboardGetItemFormat
• PBClipboardGetItemData

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

• PBStreamRead
• PBClipboardGetItemData
• PBClipboardGetItemCount
• PBClipboardCallItemFunction

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

• PBClipboardGetItemData
• PBClipboardGetItemCount
• PBClipboardGetItemFormat
• PBClipboardItemHasFormat

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

• PBClipboardBeginWriting
• PBClipboardRead

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
• PBClipboardRead
• PBClipboardBeginWriting

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);
}