[SDL] SDL Clipboard API: Recommendations based on research

Nathaniel J Fries nfries88 at yahoo.com
Tue Jul 13 23:22:15 PDT 2010


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:
1) 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.
2) Drag'n'drop on Windows and Cocoa (OS X) requires a defined area.
3) 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.
4) 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

http://natefries.net/




-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.libsdl.org/pipermail/sdl-libsdl.org/attachments/20100713/27f6aa73/attachment-0007.htm>


More information about the SDL mailing list