TSdlClipboard
SDL provides access to the system clipboard, both for reading information from other processes and publishing information of its own.
This is not just text! SDL apps can access and publish data by mimetype.
Basic use (text)
Obtaining and publishing simple text to the system clipboard is as easy as using the Text property. Data transmission and encoding conversion is completely managed by SDL.
Clipboard data provider (data other than text)
Things get more complicated when the clipboard contains something other than text. Not only can the system clipboard contain data of any type, in some cases it can contain the same data in different formats! For example, an image painting app might let the user copy a graphic to the clipboard, and offers it in .BMP, .JPG, or .PNG format for other apps to consume.
Obtaining clipboard data ("pasting") like this is a matter of calling GetData and telling it the mime type of the data you want. But how does one know if that format is available? HasData can report if a specific mimetype is offered, and MimeTypes can provide the entire list of mimetypes available, so the app can decide what to do with the data and what formats it can support.
Setting the clipboard ("copying") to arbitrary data is done with SetData. The app does not provide the data in this call, but rather the mime types it is willing to provide and a ISdlClipboardDataProvider interface that will be called when needed. During the ISdlClipboardDataProvider.Data callback, the app will generate the data. This allows massive data sets to be provided to the clipboard, without any data being copied before it is explicitly requested. More specifically, it allows an app to offer data in multiple formats without providing a copy of all of them upfront. If the app has an image that it could provide in PNG or JPG format, it doesn't have to encode it to either of those unless and until something tries to paste it.
Definition
Unit: Neslib.Sdl3.Additional
Properties
| Name | Description |
|---|---|
| HasText | Whether the clipboard exists and contains a non-empty text string. |
| MimeTypes | The list of mime types available in the clipboard. |
| Text | The text on the clipboard. |
Constructors
| Name | Description |
|---|---|
| Create | |
| Destroy |
Methods
| Name | Description |
|---|---|
| ClearData | Clear the clipboard data. |
| GetData | Get data from the clipboard for a given mime type. |
| HasData | Query whether there is data in the clipboard for the provided mime type. |
| SetData | Offer clipboard data to the OS. |
Property Descriptions
HasText
Whether the clipboard exists and contains a non-empty text string.
class property HasText: Boolean read GetHasText
Type: Boolean
See Also
Remarks
This property should only be used on the main thread.
MimeTypes
The list of mime types available in the clipboard.
class property MimeTypes: TArray<String> read GetMimeTypes
Type: TArray<String>
See Also
Remarks
This property should only be used on the main thread.
Text
The text on the clipboard.
class property Text: String read GetText write SetText
Type: String
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This property should only be used on the main thread.
Constructor Descriptions
Create
class constructor Create
Destroy
class destructor Destroy
Method Descriptions
ClearData
Clear the clipboard data.
class procedure ClearData; inline; static
Exceptions
ESdlError: Raised on failure.
See Also
Remarks
This method should only be called on the main thread.
GetData(String)
Get data from the clipboard for a given mime type.
class function GetData(const AMimeType: String): TBytes; static
Parameters
AMimeType: String
: The mime type to read from the clipboard.
Returns
TBytes: The retrieved data buffer or nil if there is none.
See Also
Remarks
This method should only be called on the main thread.
HasData(String)
Query whether there is data in the clipboard for the provided mime type.
class function HasData(const AMimeType: String): Boolean; inline; static
Parameters
AMimeType: String
: The mime type to check for data for.
Returns
Boolean: True if there exists data in clipboard for the provided mime type, False if it does not.
See Also
Remarks
This method should only be called on the main thread.
SetData(ISdlClipboardDataProvider, TArray<String>)
Offer clipboard data to the OS.
Tell the operating system that the application is offering clipboard data for each of the provided mime types. Once another application requests the data the ISdlClipboardDataProvider.Data callback method will be called, allowing it to generate and respond with the data for the requested mime type.
class procedure SetData(const AProvider: ISdlClipboardDataProvider; const AMimeTypes: TArray<String>); static
Exceptions
ESdlError: Raised on failure.
Parameters
AProvider: ISdlClipboardDataProvider
: A ISdlClipboardDataProvider interface that provides the clipboard data. Cannot be nil.
AMimeTypes: TArray<String>
: A list of mime-types that are being offered.
See Also
Remarks
This method should only be called on the main thread.