1 /* 2 DSDL 3 Copyright (C) 2025 Inochi2D Project <luna@foxgirls.gay> 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 Simple DirectMedia Layer 24 Copyright (C) 1997-2025 Sam Lantinga <slouken@libsdl.org> 25 26 This software is provided 'as-is', without any express or implied 27 warranty. In no event will the authors be held liable for any damages 28 arising from the use of this software. 29 30 Permission is granted to anyone to use this software for any purpose, 31 including commercial applications, and to alter it and redistribute it 32 freely, subject to the following restrictions: 33 34 1. The origin of this software must not be misrepresented; you must not 35 claim that you wrote the original software. If you use this software 36 in a product, an acknowledgment in the product documentation would be 37 appreciated but is not required. 38 2. Altered source versions must be plainly marked as such, and must not be 39 misrepresented as being the original software. 40 3. This notice may not be removed or altered from any source distribution. 41 */ 42 43 /** 44 SDL Clipboard 45 46 See_Also: 47 $(LINK2 https://wiki.libsdl.org/SDL3/CategoryClipboard, SDL3 Clipboard Documentation) 48 49 Copyright: © 2025 Inochi2D Project, © 1997-2025 Sam Lantinga 50 License: Subject to the terms of the Zlib License, as written in the LICENSE file. 51 Authors: 52 Luna Nielsen 53 */ 54 module sdl.clipboard; 55 import sdl.stdc; 56 57 extern(C) nothrow @nogc: 58 59 /** 60 Put UTF-8 text into the clipboard. 61 62 Params: 63 text = the text to store in the clipboard. 64 65 Returns: 66 true on success or false on failure; call SDL_GetError() for more 67 information. 68 69 Threadsafety: 70 This function should only be called on the main thread. 71 72 See_Also 73 $(D SDL_GetClipboardText) 74 $(D SDL_HasClipboardText) 75 */ 76 extern bool SDL_SetClipboardText(const(char)* text); 77 78 /** 79 Get UTF-8 text from the clipboard. 80 81 This functions returns an empty string if there was not enough memory left 82 for a copy of the clipboard's content. 83 84 Returns: 85 the clipboard text on success or an empty string on failure; call 86 SDL_GetError() for more information. This should be freed with 87 SDL_free() when it is no longer needed. 88 89 Threadsafety: 90 This function should only be called on the main thread. 91 92 See_Also: 93 $(D SDL_HasClipboardText) 94 $(D SDL_SetClipboardText) 95 */ 96 extern char* SDL_GetClipboardText(); 97 98 /** 99 Query whether the clipboard exists and contains a non-empty text string. 100 101 Returns: 102 true if the clipboard has text, or false if it does not. 103 104 Threadsafety: 105 This function should only be called on the main thread. 106 107 See_Also: 108 $(D SDL_GetClipboardText) 109 $(D SDL_SetClipboardText) 110 */ 111 extern bool SDL_HasClipboardText(); 112 113 /** 114 Put UTF-8 text into the primary selection. 115 116 Params: 117 text = the text to store in the primary selection. 118 119 Returns: 120 true on success or false on failure; call SDL_GetError() for more 121 information. 122 123 Threadsafety: 124 This function should only be called on the main thread. 125 126 See_Also: 127 $(D SDL_GetPrimarySelectionText) 128 $(D SDL_HasPrimarySelectionText) 129 */ 130 extern bool SDL_SetPrimarySelectionText(const(char)* text); 131 132 /** 133 Get UTF-8 text from the primary selection. 134 135 This functions returns an empty string if there was not enough memory left 136 for a copy of the primary selection's content. 137 138 Returns: 139 the primary selection text on success or an empty string on 140 failure; call SDL_GetError() for more information. This should be 141 freed with SDL_free() when it is no longer needed. 142 143 Threadsafety: 144 This function should only be called on the main thread. 145 146 See_Also: 147 $(D SDL_HasPrimarySelectionText) 148 $(D SDL_SetPrimarySelectionText) 149 */ 150 extern char* SDL_GetPrimarySelectionText(); 151 152 /** 153 Query whether the primary selection exists and contains a non-empty text 154 string. 155 156 Returns: 157 true if the primary selection has text, or false if it does not. 158 159 Threadsafety: 160 This function should only be called on the main thread. 161 162 See_Also: 163 $(D SDL_GetPrimarySelectionText) 164 $(D SDL_SetPrimarySelectionText) 165 */ 166 extern bool SDL_HasPrimarySelectionText(); 167 168 /** 169 Callback function that will be called when data for the specified mime-type 170 is requested by the OS. 171 172 The callback function is called with NULL as the mime_type when the 173 clipboard is cleared or new data is set. The clipboard is automatically 174 cleared in SDL_Quit(). 175 176 Params: 177 userdata = a pointer to provided user data. 178 mime_type = the requested mime-type. 179 size = a pointer filled in with the length of the returned data. 180 181 Returns: 182 a pointer to the data for the provided mime-type. Returning NULL 183 or setting length to 0 will cause no data to be sent to the 184 "receiver". It is up to the receiver to handle this. Essentially 185 returning no data is more or less undefined behavior and may cause 186 breakage in receiving applications. The returned data will not be 187 freed so it needs to be retained and dealt with internally. 188 189 See_Also: 190 $(D SDL_SetClipboardData) 191 */ 192 alias SDL_ClipboardDataCallback = const(void)* function(void* userdata, const(char)* mime_type, size_t* size); 193 194 /** 195 Callback function that will be called when the clipboard is cleared, or new 196 data is set. 197 198 Params: 199 userdata a pointer to provided user data. 200 201 See_Also: 202 $(D SDL_SetClipboardData) 203 */ 204 alias SDL_ClipboardCleanupCallback = void function(void* userdata); 205 206 /** 207 Offer clipboard data to the OS. 208 209 Tell the operating system that the application is offering clipboard data 210 for each of the provided mime-types. Once another application requests the 211 data the callback function will be called, allowing it to generate and 212 respond with the data for the requested mime-type. 213 214 The size of text data does not include any terminator, and the text does 215 not need to be null terminated (e.g. you can directly copy a portion of a 216 document). 217 218 Params: 219 callback = a function pointer to the function that provides the 220 clipboard data. 221 cleanup = a function pointer to the function that cleans up the 222 clipboard data. 223 userdata = an opaque pointer that will be forwarded to the callbacks. 224 mime_types = a list of mime-types that are being offered. 225 num_mime_types = the number of mime-types in the mime_types list. 226 227 Returns: 228 true on success or false on failure; call SDL_GetError() for more 229 information. 230 231 Threadsafety: 232 This function should only be called on the main thread. 233 234 See_Also: 235 $(D SDL_ClearClipboardData) 236 $(D SDL_GetClipboardData) 237 $(D SDL_HasClipboardData) 238 */ 239 extern bool SDL_SetClipboardData(SDL_ClipboardDataCallback callback, SDL_ClipboardCleanupCallback cleanup, void* userdata, const(char)** mime_types, size_t num_mime_types); 240 241 /** 242 Clear the clipboard data. 243 244 Returns: 245 true on success or false on failure; call SDL_GetError() for more 246 information. 247 248 Threadsafety: 249 This function should only be called on the main thread. 250 251 See_Also: 252 $(D SDL_SetClipboardData) 253 */ 254 extern bool SDL_ClearClipboardData(); 255 256 /** 257 Get the data from clipboard for a given mime type. 258 259 The size of text data does not include the terminator, but the text is 260 guaranteed to be null terminated. 261 262 Params: 263 mime_type = the mime type to read from the clipboard. 264 size = a pointer filled in with the length of the returned data. 265 266 Returns: 267 the retrieved data buffer or NULL on failure; call SDL_GetError() 268 for more information. This should be freed with SDL_free() when it 269 is no longer needed. 270 271 Threadsafety: 272 This function should only be called on the main thread. 273 274 See_Also: 275 $(D SDL_HasClipboardData) 276 $(D SDL_SetClipboardData) 277 */ 278 extern void* SDL_GetClipboardData(const(char)* mime_type, size_t* size); 279 280 /** 281 Query whether there is data in the clipboard for the provided mime type. 282 283 Params: 284 mime_type = the mime type to check for data for. 285 286 Returns: 287 true if there exists data in clipboard for the provided mime type, 288 false if it does not. 289 290 Threadsafety: 291 This function should only be called on the main thread. 292 293 See_Also: 294 $(D SDL_SetClipboardData) 295 $(D SDL_GetClipboardData) 296 */ 297 extern bool SDL_HasClipboardData(const(char)* mime_type); 298 299 /** 300 Retrieve the list of mime types available in the clipboard. 301 302 Params: 303 num_mime_types = a pointer filled with the number of mime types, may 304 be NULL. 305 306 Returns: 307 a null terminated array of strings with mime types, or NULL on 308 failure; call SDL_GetError() for more information. This should be 309 freed with SDL_free() when it is no longer needed. 310 311 Threadsafety: 312 This function should only be called on the main thread. 313 314 See_Also: 315 $(D SDL_SetClipboardData) 316 */ 317 extern char** SDL_GetClipboardMimeTypes(size_t* num_mime_types);