[Author Prev][Author Next][Thread Prev][Thread Next][Author Index][Thread Index]

Re: [pygame] Revising Scrap API?



On, Sat Feb 28, 2009, Brian Fisher wrote:

> So I'm doing the scrap implementation for mac without pyobjc now, and it's
> passing unit tests and working fine as far as I can tell, but I am having
> trouble seeing how the scrap API for images would be useful to me in
> practice, and I'm wondering if I "get it" at all... meaning the whole
> SCRAP_PBM/SCRAP_PPM/SCRAP_BMP/tiff stuff. Also, having the small list of
> additional types that windows & X11 specific things feels very not
> cross-platform of pygame, so I want to make mac support them, but I can't
> see how to make that support useful either. To summarize, some parts of the
> api for scrap are feeling rather hacky, very not pythonic, and not like
> something I'd even try to utilize. So can the list help me understand how
> it's not, or help me make it useful?

What exactly feels wrong to you? The scrap system needs some cleanups
anyways. I made some minor changes within the pgreloaded branch already,
but it will require some more work. So let's put the heads together :-).
 
> ...So I think the purpose of this scrap stuff is to communicate stuff
> between pygame and other apps, right?

Right.

> like say copying a screenshot from pygame so it can be pasted into
> photoshop, right? or making it so you can copy/paste strings from your
> python windowing toolkits to other apps, right?

Strings, pixel buffers in certain formats (e.g. dib, bmp, raw buffers,
etc.) and whatever else the user wants.
 
> Well my big confusion is that as the API user, is that I'd be specifying
> what I want with mime-types, and I don't know what that is supposed to mean.

If you are working with a copy'n'paste API, you usually know about
mime-types and all that stuff - or you are willing to learn about them
and what the application(s) to communicate with require.

> If I'm trying to get stuff from the scrap module, then I want to work with
> python/pygame objects, right? When I say "image/bmp", am I saying give me
> the image as an image/bmp, or am I saying only give me images if they are
> image/bmp? 

If you ask the clipboard for "image/bmp", you try to receive the
currently available data in a BMP format. If no such data is available,
you will not receive anything. The scrap module does not automatically
convert the data as clipboards can send broken or messed up data,
depending on the application they got the data from. Thus the scrap
module does not do any automatic or implicit object conversion.

> Also, why would it be an advantage to me as a pygame user to say
> I want SCRAP_PBM vs. SCRAP_BMP? do I really care at all? Isn't it true that

SCRAP_BPM/SCRAP_BMP are targeting on portable shortcuts that put the
data to the clipboard in a platform-dependent way. So if I e.g. use
SCRAP_TEXT, on X11 not only a "text" slot within the clipboard will be
registered, but also all the other related clip types that deal with
text. The same should be done on other platforms and has the benefit for
the user that several application-compatible types are registered with a
single command.

> I really just want a surface, and any PBM/tiff/BMP string intermediate step
> is just extra work I have to do? Likewise for putting stuff into the scrap -
> I would think that as a pygame user I just want to put my surface on the
> clipboard in whatever way is best for the platform, right? meaning paste it
> so it can go into ms paint/photoshop on windows, and paste it so it can go
> into gimp/icon composer/photoshop on the mac, and it can go into gimp on
> linux, right?

That is exactly what the pre-defined SCRAP_* types aim to and also do
for X11 and Win32 platforms. The only step for the user would be to
provide the necessary string representing the surface data.

I would not want to change that behaviour as a user might get the
impression, that once a Surface object is put on the clipboard, changing
it withing pygame would change it within the clipboard as well, which is
not a task that can be (easily) performed.

> Does a pygame user really want to specify the precise
> clipboard type, here? Isn't this just an opportunity to get the clipboard
> format "wrong" (meaning it can't be pasted into common apps) for a
> particular platform?

Sure, that's - again - what the SCRAP_* types are for. If I as a
clipboard API user require some certain format to exchange data with a
specialised application, I also have the freedom to define my own format
and in that case I usually know what to do.

> For strings/text, I have minor but similar confusions -  I'm a bit confused
> by some minor string stuff as well - what is it supposed to mean in I
> specify "text/plain" vs. "text/plain;charset=utf-8"? Am I specifying the
> format that I'd like things returned or am I saying I only want this text if
> it adheres to utf-8? Also, what encoding is text/plain supposed to mean? Why
> not instead just have pygame have a defined encoding for text copy/pasted
> and make it the pygame lib's responsibility to adhere to it? (for instance,
> why not just say it's always utf-8 in and out, until python 3.0 where we say
> it's always unicode?)

"text/plain" is a raw ASCII text sequence. "text/plain;charset=utf-8" is
a multibyte UTF-8 encoded text sequence. Using unicode in all cases
won't allow other applications that support text/plain to receive text
data from the clipboard, even if it's pure ASCII.

If I request "text/plain", I want pure ASCII text and nothing else. If I
request "text/plain;charset=utf-8", I want UTF-8 encoded text. If I
request SCRAP_TEXT, I usually want some text and will take whatever will
be provided to me.

Pygame can't be responsible for en- or decoding the data on request - at
least not in a platform-neutral manner. Once the data is within the
clipboard buffer (on Win32 for example), pygame cannot do anything about
it anymore, so it is up to the user to either provide the correct
mime-type or use one of the SCRAP_* constants.

> some other little questions:
> * the selection thing - what's it actually used for? what does it mean to
> copy and paste a selection? is there anybody anywhere who copies and pastes
> "selections" in/out of a pygame app? does it make sense for "selections" to
> be portable between pygame apps and other apps? If this is not something
> useful to pygame apps, but instead is an idiosyncrosy of X11 that just has
> to be handled, can we just make it handled automatically instead of being
> part of the API?

Yes and no. This is the typical X11 specification hell. If you select
text within a terminal under X11 it goes into the selection buffer, not
the clipboard buffer. So you can paste text e.g. via the middle mouse
button, if it is set in a selection buffer and can paste something else
e.g. via Ctrl+Y, which is available in the clipboard buffer. Handling it
automatically will disallow certain applications to communicate with
pygame applications in all its glory for X11.

This is only for X11 though, Win32 and MacOS do not have a selection
buffer (MacOS X <= 10.4 at least), so in the most cases users will use
SCRAP_CLIPBOARD anyways, I think.

> * so what does pygame.scrap.lost mean?
>   in what cases will the scrap be lost?

lost means that the pygame application does not own the contents of the
clipboard anymore. This is the case on all platforms, if you e.g. switch
to your favourite editor and copy text from it to the clipboard. X11
supports (due to its client/server design) some different behaviour here
with time-frame based requests, but that would go beyond your question
and I do not want to bore you with the gory details of the X11
misdesigns.

> when it is lost, what is the action a pygame script would take
> to fix it? 

That the pygame application code causes a scrap.put once the user issues
the defined action. Pygame itself should under _no_ circumstances
automatically reaquire the clipboard buffer. Otherwise you will mess up
the whole clipboard system under all three operating systems.

> why not just have each specific platform check for
> "lostness" if the platform requires it, and automatically fix the
> problem if it occurs?

This is not a problem, but absolutely correct behaviour. A more
appropriate translation for "pygame.scrap.lost" might be "does the
clipboard still own contents of the pygame application or is it
currently holding contents from another application?".

> When and why would I care if it's "lost" in a  pygame app?

Never. It's the developer's responsibility to implement a correct copy
and paste system for his application and out of our scope.

> * the unit test for scrap puts image.tostring into the scrap as a SCRAP_BMP
> and gets it out as the same - however the windows code for scrap put appears
> to strip off a BMP image header for SCRAP_BMP, and adds a BMP header back in
> when getting things. So in that case, the unit test and windows source
> appear to be rather at odds - so which is right?

This is an oddity on Win32 platforms, which require bitmap data to
contain a full header. On X11 applications usually add that header
automatically. I am unsure about that, but maybe we should always add a
full BMP header, if the type is SCRAP_BMP (or image/bmp) and no header
information are within the buffer to be placed in the clipboard.

Regards
Marcus

Attachment: pgpJ_mQnbyxMh.pgp
Description: PGP signature