Okay, I haven’t produced any code based on my research (other than text-only copy/paste on Windows and OS X, which is used in a GPL-licensed project).
But here’s what I’ve found that really affects the API:
- Using the freedesktop.org (X11) clipboard method, copy/paste data is held in the CLIPBOARD selection and drag’n’drop data in the PRIMARY selection.
- Drag’n’drop on Windows and Cocoa (OS X) requires a defined area.
- This should already be known by Sam from his SDL_scrap work, but on X11 you request clipboard data and then receive an X11 event with the requested data.
- On all three systems, Images and Text are treated differently.
Based on this, here’s my suggestion on a Copy/Paste API:
/* structures and enums, self-explanatory I’d think /
typedef enum SDL_ClipType {
SDL_CLIPTYPE_TEXT,
SDL_CLIPTYPE_UTF8,
SDL_CLIPTYPE_IMAGE
} SDL_ClipType;
typedef struct SDL_ClipData {
SDL_ClipType type;
Uint32 length; / note: ignored in the case of an image /
union {
char text;
unsigned char* utf8;
SDL_Surface* image;
};
} SDL_ClipData;
/* functions /
/ returns non-zero if clipboard data was available. The actual data will appear in the SDL Event queue */
SDL_Bool SDL_RequestClipData(SDL_ClipType type);
/* same as above, but you wait for the event (X11) instead. This will seem more normal to an application developer, and maybe should be just done like this anyway /
SDL_Bool SDL_WaitClipData(SDL_ClupType type, void buffer, Uint32 buflen, Uint32* size); /* alt: SDL_Bool SDL_WaitClipData(SDL_ClipType type, SDL_ClipData* data); */
/* this function is pretty self-explanatory /
void SDL_AddClipData(SDL_ClipType type, void data, Uint32 length); /* alt: void SDL_AddClipData(SDL_ClipType type, SDL_ClipData* data); */
/* clears the clipboard of all contents */
void SDL_ClearClip();
and we add a new event for receiving data from the clipboard:
typedef struct SDL_ClipEvent {
Uint8 type;
SDL_ClipData data; /* alt: SDL_ClipType type; Uint32 length; union { char* text; unsigned char* utf8; SDL_Surface* image; }; */
} SDL_ClipEvent;
As for Drag’n’Drop:
/* creates a new drag’n’drop region. returns an identifier for the region /
Uint32 SDL_CreateDNDArea(SDL_Rect rect);
/* destroys the region */
void SDL_DestroyDNDArea(Uint32 areaId);
/* SDL application decided to start drag’n’drop-ing something /
void SDL_BeginDND(Uint32 areaId, SDL_ClipData data); / alt: void SDL_BeginDND{Text,Unicode,Image}(Uint32 areaId, SDL_ClipType type, Uint32 len, {char* text, unsigned char* utf8, SDL_Surface* image}); */
/* SDL application decides to clear DND data */
void SDL_ClearDND();
and again, new SDL events:
/* when an item is dragged over a DND area /
typedef struct SDL_DragOverEvent {
Uint32 areaId;
SDL_ClipData data; / alt… you know, same as paste event /
};
/ when the user finally releases the mouse over a DND area /
typedef struct SDL_DragDropEvent {
Uint32 areaId;
SDL_ClipData data; / alt… you know, same as paste event */
};
Well, that’s it. Hopefully whoever actually does this finds the information useful, and hopefully I don’t bore anyone or leave them confused.------------------------
EM3 Nathaniel Fries, U.S. Navy