SDL 3.0
SDL_clipboard.h
Go to the documentation of this file.
1/*
2 Simple DirectMedia Layer
3 Copyright (C) 1997-2023 Sam Lantinga <slouken@libsdl.org>
4
5 This software is provided 'as-is', without any express or implied
6 warranty. In no event will the authors be held liable for any damages
7 arising from the use of this software.
8
9 Permission is granted to anyone to use this software for any purpose,
10 including commercial applications, and to alter it and redistribute it
11 freely, subject to the following restrictions:
12
13 1. The origin of this software must not be misrepresented; you must not
14 claim that you wrote the original software. If you use this software
15 in a product, an acknowledgment in the product documentation would be
16 appreciated but is not required.
17 2. Altered source versions must be plainly marked as such, and must not be
18 misrepresented as being the original software.
19 3. This notice may not be removed or altered from any source distribution.
20*/
21
22/**
23 * \file SDL_clipboard.h
24 *
25 * \brief Include file for SDL clipboard handling
26 */
27
28#ifndef SDL_clipboard_h_
29#define SDL_clipboard_h_
30
31#include <SDL3/SDL_stdinc.h>
32
33#include <SDL3/SDL_begin_code.h>
34/* Set up for C function definitions, even when using C++ */
35#ifdef __cplusplus
36extern "C" {
37#endif
38
39/* Function prototypes */
40
41/**
42 * Put UTF-8 text into the clipboard.
43 *
44 * \param text the text to store in the clipboard
45 * \returns 0 on success or a negative error code on failure; call
46 * SDL_GetError() for more information.
47 *
48 * \since This function is available since SDL 3.0.0.
49 *
50 * \sa SDL_GetClipboardText
51 * \sa SDL_HasClipboardText
52 */
53extern DECLSPEC int SDLCALL SDL_SetClipboardText(const char *text);
54
55/**
56 * Get UTF-8 text from the clipboard, which must be freed with SDL_free().
57 *
58 * This functions returns empty string if there was not enough memory left for
59 * a copy of the clipboard's content.
60 *
61 * \returns the clipboard text on success or an empty string on failure; call
62 * SDL_GetError() for more information. Caller must call SDL_free()
63 * on the returned pointer when done with it (even if there was an
64 * error).
65 *
66 * \since This function is available since SDL 3.0.0.
67 *
68 * \sa SDL_HasClipboardText
69 * \sa SDL_SetClipboardText
70 */
71extern DECLSPEC char * SDLCALL SDL_GetClipboardText(void);
72
73/**
74 * Query whether the clipboard exists and contains a non-empty text string.
75 *
76 * \returns SDL_TRUE if the clipboard has text, or SDL_FALSE if it does not.
77 *
78 * \since This function is available since SDL 3.0.0.
79 *
80 * \sa SDL_GetClipboardText
81 * \sa SDL_SetClipboardText
82 */
83extern DECLSPEC SDL_bool SDLCALL SDL_HasClipboardText(void);
84
85/**
86 * Put UTF-8 text into the primary selection.
87 *
88 * \param text the text to store in the primary selection
89 * \returns 0 on success or a negative error code on failure; call
90 * SDL_GetError() for more information.
91 *
92 * \since This function is available since SDL 3.0.0.
93 *
94 * \sa SDL_GetPrimarySelectionText
95 * \sa SDL_HasPrimarySelectionText
96 */
97extern DECLSPEC int SDLCALL SDL_SetPrimarySelectionText(const char *text);
98
99/**
100 * Get UTF-8 text from the primary selection, which must be freed with
101 * SDL_free().
102 *
103 * This functions returns empty string if there was not enough memory left for
104 * a copy of the primary selection's content.
105 *
106 * \returns the primary selection text on success or an empty string on
107 * failure; call SDL_GetError() for more information. Caller must
108 * call SDL_free() on the returned pointer when done with it (even if
109 * there was an error).
110 *
111 * \since This function is available since SDL 3.0.0.
112 *
113 * \sa SDL_HasPrimarySelectionText
114 * \sa SDL_SetPrimarySelectionText
115 */
116extern DECLSPEC char * SDLCALL SDL_GetPrimarySelectionText(void);
117
118/**
119 * Query whether the primary selection exists and contains a non-empty text
120 * string.
121 *
122 * \returns SDL_TRUE if the primary selection has text, or SDL_FALSE if it
123 * does not.
124 *
125 * \since This function is available since SDL 3.0.0.
126 *
127 * \sa SDL_GetPrimarySelectionText
128 * \sa SDL_SetPrimarySelectionText
129 */
130extern DECLSPEC SDL_bool SDLCALL SDL_HasPrimarySelectionText(void);
131
132/**
133 * Callback function that will be called when data for the specified mime-type
134 * is requested by the OS.
135 *
136 * The callback function is called with NULL as the mime_type when the clipboard
137 * is cleared or new data is set. The clipboard is automatically cleared in SDL_Quit().
138 *
139 * \param userdata A pointer to provided user data
140 * \param mime_type The requested mime-type
141 * \param size A pointer filled in with the length of the returned data
142 * \returns a pointer to the data for the provided mime-type. Returning NULL or
143 * setting length to 0 will cause no data to be sent to the "receiver". It is
144 * up to the receiver to handle this. Essentially returning no data is more or
145 * less undefined behavior and may cause breakage in receiving applications.
146 * The returned data will not be freed so it needs to be retained and dealt
147 * with internally.
148 *
149 * \since This function is available since SDL 3.0.0.
150 *
151 * \sa SDL_SetClipboardData
152 */
153typedef const void *(SDLCALL *SDL_ClipboardDataCallback)(void *userdata, const char *mime_type, size_t *size);
154
155/**
156 * Callback function that will be called when the clipboard is cleared, or new data is set.
157 *
158 * \param userdata A pointer to provided user data
159 *
160 * \since This function is available since SDL 3.0.0.
161 *
162 * \sa SDL_SetClipboardData
163 */
164typedef void (SDLCALL *SDL_ClipboardCleanupCallback)(void *userdata);
165
166/**
167 * Offer clipboard data to the OS
168 *
169 * Tell the operating system that the application is offering clipboard data
170 * for each of the proivded mime-types. Once another application requests the
171 * data the callback function will be called allowing it to generate and
172 * respond with the data for the requested mime-type.
173 *
174 * The size of text data does not include any terminator, and the text does
175 * not need to be null terminated (e.g. you can directly copy a portion of a
176 * document)
177 *
178 * \param callback A function pointer to the function that provides the
179 * clipboard data
180 * \param cleanup A function pointer to the function that cleans up the
181 * clipboard data
182 * \param userdata An opaque pointer that will be forwarded to the callbacks
183 * \param mime_types A list of mime-types that are being offered
184 * \param num_mime_types The number of mime-types in the mime_types list
185 * \returns 0 on success or a negative error code on failure; call
186 * SDL_GetError() for more information.
187 *
188 * \since This function is available since SDL 3.0.0.
189 *
190 * \sa SDL_ClipboardDataCallback
191 * \sa SDL_SetClipboardData
192 * \sa SDL_GetClipboardData
193 * \sa SDL_HasClipboardData
194 */
195extern DECLSPEC int SDLCALL SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types);
196
197/**
198 * Clear the clipboard data
199 *
200 * \returns 0 on success or a negative error code on failure; call
201 * SDL_GetError() for more information.
202 *
203 * \since This function is available since SDL 3.0.0.
204 *
205 * \sa SDL_SetClipboardData
206 */
207extern DECLSPEC int SDLCALL SDL_ClearClipboardData(void);
208
209/**
210 * Get the data from clipboard for a given mime type
211 *
212 * The size of text data does not include the terminator, but the text is
213 * guaranteed to be null terminated.
214 *
215 * \param mime_type The mime type to read from the clipboard
216 * \param size A pointer filled in with the length of the returned data
217 * \returns the retrieved data buffer or NULL on failure; call SDL_GetError()
218 * for more information. Caller must call SDL_free() on the returned
219 * pointer when done with it.
220 *
221 * \since This function is available since SDL 3.0.0.
222 *
223 * \sa SDL_SetClipboardData
224 */
225extern DECLSPEC void *SDLCALL SDL_GetClipboardData(const char *mime_type, size_t *size);
226
227/**
228 * Query whether there is data in the clipboard for the provided mime type
229 *
230 * \param mime_type The mime type to check for data for
231 * \returns SDL_TRUE if there exists data in clipboard for the provided mime
232 * type, SDL_FALSE if it does not.
233 *
234 * \since This function is available since SDL 3.0.0.
235 *
236 * \sa SDL_SetClipboardData
237 * \sa SDL_GetClipboardData
238 */
239extern DECLSPEC SDL_bool SDLCALL SDL_HasClipboardData(const char *mime_type);
240
241/* Ends C function definitions when using C++ */
242#ifdef __cplusplus
243}
244#endif
245#include <SDL3/SDL_close_code.h>
246
247#endif /* SDL_clipboard_h_ */
char * SDL_GetPrimarySelectionText(void)
int SDL_SetPrimarySelectionText(const char *text)
SDL_bool SDL_HasClipboardData(const char *mime_type)
char * SDL_GetClipboardText(void)
const void *(* SDL_ClipboardDataCallback)(void *userdata, const char *mime_type, size_t *size)
SDL_bool SDL_HasClipboardText(void)
void(* SDL_ClipboardCleanupCallback)(void *userdata)
int SDL_SetClipboardText(const char *text)
int SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void *userdata, const char **mime_types, size_t num_mime_types)
SDL_bool SDL_HasPrimarySelectionText(void)
int SDL_ClearClipboardData(void)
void * SDL_GetClipboardData(const char *mime_type, size_t *size)
This is a general header that includes C language support.
SDL_MALLOC size_t size
Definition SDL_stdinc.h:391
SDL_bool
Definition SDL_stdinc.h:130