[SDL] SDL Clipboard API: Recommendations based on research

[Sam Lantinga]

Interestingly enough, I just implemented simple text clipboard support
in SDL 1.3 last week:
http://hg.libsdl.org/SDL/file/f8c3870af5a2/include/SDL_clipboard.h

I started playing around with images but that got complicated fast.

There's also a cross-platform difference between X11 and Windows and
Mac OS X: On Windows and Mac OS X you can inexpensively generate an
event when the clipboard contents changes.  As far as I can tell on
X11 you have to do a fairly expensive poll to achieve the same result.

Anyway, FYI...

On Tue, Jul 13, 2010 at 11:22 PM, Nathaniel J Fries <nfries88 at yahoo.com> wrote:
> 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/
> _______________________________________________
> SDL mailing list
> SDL at lists.libsdl.org
> http://lists.libsdl.org/listinfo.cgi/sdl-libsdl.org
>
>



-- 
    -Sam Lantinga, Founder and President, Galaxy Gameworks LLC