[SDL] SDL Clipboard API: Recommendations based on research

[Bob Pendleton]

A couple of quick comments.

Using the word "clip" without a modifier is potentially confusing in a
graphics library. "Clip" has a strong connotation in the graphics
world. I would suggest using ClipBoard or even CB, but not just clip.

The functions used to wait for clip board data seem superfluous to me,
and just a little bit dangerous. You don't ever want to wait for a
specific event in an interactive program.

Do you really need a drop event and what I am guessing is a paste
event? Does it matter to me what the user is doing to get the data to
me? If I get an event that tells me that data is available and I have
a way to get that data why do I care if it is the result of a drag and
drop or a paste? The OS, may make a distinction. But that doesn't mean
that a programmer using SDL should have too.

Bob Pendleton



On Wed, Jul 14, 2010 at 1:22 AM, 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
>
>



-- 
+-----------------------------------------------------------
+ Bob Pendleton: writer and programmer
+ email: Bob at Pendleton.com
+ web: www.TheGrumpyProgrammer.com