1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
129
130
131
132
133
134
135
136
137
138
139
140
141
142
143
144
145
146
147
148
149
150
151
152
153
154
155
156
157
158
159
160
161
162
163
164
165
166
167
168
169
170
171
172
173
174
175
176
177
178
179
180
181
182
183
184
185
186
187
188
189
190
191
192
193
194
195
196
197
198
199
200
201
202
203
|
.. include:: common.txt
:mod:`pygame.scrap`
===================
.. module:: pygame.scrap
:synopsis: pygame module for clipboard support.
| :sl:`pygame module for clipboard support.`
EXPERIMENTAL!: meaning this API may change, or disappear in later pygame
releases. If you use this, your code will break with the next pygame release.
The scrap module is for getting and putting stuff from the clipboard. So you
can copy and paste things between pygame, and other application types. It
defines some basic own data types
::
SCRAP_PPM
SCRAP_PBM
SCRAP_BMP
SCRAP_TEXT
to be placed into the clipboard and allows to use define own clipboard types.
``SCRAP_PPM``, ``SCRAP_PBM`` and ``SCRAP_BMP`` are suitable for surface buffers
to be shared with other applications, while ``SCRAP_TEXT`` is an alias for the
plain text clipboard type.
The SCRAP_* types refer to the following ``MIME`` types and register those as
well as the default operating system type for this type of data:
::
SCRAP_TEXT text/plain for plain text
SCRAP_PBM image/pbm for PBM encoded image data
SCRAP_PPM image/ppm for PPM encoded image data
SCRAP_BMP image/bmp for BMP encoded image data
Depending on the platform additional types are automatically registered when
data is placed into the clipboard to guarantee a consistent sharing behaviour
with other applications. The following listed types can be used as string to be
passed to the respective :mod:`pygame.scrap` module functions.
For Windows platforms, the additional types are supported automatically and
resolve to their internal definitions:
::
text/plain;charset=utf-8 for UTF-8 encoded text
audio/wav for WAV encoded audio
image/tiff for TIFF encoded image data
For ``X11`` platforms, the additional types are supported automatically and
resolve to their internal definitions:
::
UTF8_STRING for UTF-8 encoded text
text/plain;charset=utf-8 for UTF-8 encoded text
COMPOUND_TEXT for COMPOUND text
As stated before you can define own types for the clipboard, those however
might not be usable by other applications. Thus data pasted into the clipboard
using
::
pygame.scrap.put ("own_data", data)
can only be used by applications, which query the clipboard for the "own_data"
type.
New in pygame 1.8. Only works for Windows, ``X11`` and Mac ``OS`` ``X`` so far.
On Mac ``OSX`` only text works at the moment - other types will be supported in
the next release.
.. function:: init
| :sl:`Initializes the scrap module.`
| :sg:`init () -> None`
Tries to initialize the scrap module and raises an exception, if it fails.
Note that this module requires a set display surface, so you have to make
sure, you acquired one earlier using ``pygame.display.set_mode()``.
.. ## pygame.scrap.init ##
.. function:: get
| :sl:`Gets the data for the specified type from the clipboard.`
| :sg:`get (type) -> bytes`
Returns the data for the specified type from the clipboard. The data is
returned as a byte string and might need further processing,
such as decoding to Unicode.
If no data for the passed type is available, None is returned.
::
text = pygame.scrap.get (SCRAP_TEXT)
if text:
# Do stuff with it.
else:
print "There does not seem to be text in the clipboard."
.. ## pygame.scrap.get ##
.. function:: get_types
| :sl:`Gets a list of the available clipboard types.`
| :sg:`get_types () -> list`
Gets a list of strings with the identifiers for the available clipboard
types. Each identifier can be used in the ``scrap.get()`` method to get the
clipboard content of the specific type. If there is no data in the
clipboard, an empty list is returned.
::
types = pygame.scrap.get_types ()
for t in types:
if "text" in t:
# There is some content with the word "text" in it. It's
# possibly text, so print it.
print pygame.scrap.get (t)
.. ## pygame.scrap.get_types ##
.. function:: put
| :sl:`Places data into the clipboard.`
| :sg:`put(type, data) -> None`
Places data for a specific clipboard type into the clipboard. The data must
be a string buffer. The type is a string identifying the type of data placed
into the clipboard. This can be one of the native ``SCRAP_PBM``,
``SCRAP_PPM``, ``SCRAP_BMP`` or ``SCRAP_TEXT`` values or an own string
identifier.
The method raises an exception, if the content could not be placed into the
clipboard.
::
fp = open ("example.bmp", "rb")
pygame.scrap.put (SCRAP_BMP, fp.read ())
fp.close ()
# Now you can acquire the image data from the clipboard in other
# applications.
pygame.scrap.put (SCRAP_TEXT, "A text to copy")
pygame.scrap.put ("Plain text", "A text to copy")
.. ## pygame.scrap.put ##
.. function:: contains
| :sl:`Checks, whether a certain type is available in the clipboard.`
| :sg:`contains (type) -> bool`
Returns True, if data for the passed type is available in the clipboard,
False otherwise.
::
if pygame.scrap.contains (SCRAP_TEXT):
print "There is text in the clipboard."
if pygame.scrap.contains ("own_data_type"):
print "There is stuff in the clipboard."
.. ## pygame.scrap.contains ##
.. function:: lost
| :sl:`Checks whether the clipboard is currently owned by the application.`
| :sg:`lost() -> bool`
Returns True, if the clipboard is currently owned by the pygame application,
False otherwise.
::
if pygame.scrap.lost ():
print "No content from me anymore. The clipboard is used by someone else."
.. ## pygame.scrap.lost ##
.. function:: set_mode
| :sl:`Sets the clipboard access mode.`
| :sg:`set_mode(mode) -> None`
Sets the access mode for the clipboard. This is only of interest for ``X11``
environments, where clipboard modes for mouse selections (SRAP_SELECTION)
and the clipboard (SCRAP_CLIPBOARD) are available. Setting the mode to
``SCRAP_SELECTION`` in other environments will not cause any difference.
If a value different from ``SCRAP_CLIPBOARD`` or ``SCRAP_SELECTION`` is
passed, a ValueError will be raised.
.. ## pygame.scrap.set_mode ##
.. ## pygame.scrap ##
|
