Skip to content
New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Jump to bottom

Update scrap documentation #923

Merged
merged 3 commits into from
Mar 24, 2019
Merged

Update scrap documentation #923

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
3 commits
Select commit Hold shift + click to select a range
4278c86
Update scrap documentation
charlesej Mar 22, 2019
06c8ada
Fix scrap doc type fields
charlesej Mar 23, 2019
70fd463
Add link to scrap example code
charlesej Mar 23, 2019
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
232 changes: 129 additions & 103 deletions docs/reST/ref/scrap.rst
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -8,84 +8,80 @@

| :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.
**EXPERIMENTAL!**: This API may change or disappear in later pygame releases. If
you use this, your code may 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
The scrap module is for transferring data to/from the clipboard. This allows
for cutting and pasting data between pygame and other applications. Some basic
data (MIME) types are defined and registered:

::

SCRAP_PPM
SCRAP_PBM
SCRAP_BMP
SCRAP_TEXT
pygame string
constant value description
--------------------------------------------------
SCRAP_TEXT "text/plain" plain text
SCRAP_BMP "image/bmp" BMP encoded image data
SCRAP_PBM "image/pbm" PBM encoded image data
SCRAP_PPM "image/ppm" PPM encoded image data

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.
``pygame.SCRAP_PPM``, ``pygame.SCRAP_PBM`` and ``pygame.SCRAP_BMP`` are
suitable for surface buffers to be shared with other applications.
``pygame.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
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.
with other applications. The following listed types can be used as strings 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:
For **Windows** platforms, these 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
"text/plain;charset=utf-8" UTF-8 encoded text
"audio/wav" WAV encoded audio
"image/tiff" TIFF encoded image data

For ``X11`` platforms, the additional types are supported automatically and
For **X11** platforms, these 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
"text/plain;charset=utf-8" UTF-8 encoded text
"UTF8_STRING" UTF-8 encoded text
"COMPOUND_TEXT" 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
User defined types can be used, but the data might not be accessible by other
applications unless they know what data type to look for.
Example: Data placed into the clipboard by
``pygame.scrap.put("my_data_type", byte_data)`` can only be accessed by
applications which query the clipboard for the ``"my_data_type"`` data type.

::

pygame.scrap.put ("own_data", data)

can only be used by applications, which query the clipboard for the "own_data"
type.
For an example of how the scrap module works refer to the examples page
(:func:`pygame.examples.scrap_clipboard.main`) or the code directly in GitHub
(`pygame/examples/scrap_clipboard.py <https://github.com/pygame/pygame/blob/master/examples/scrap_clipboard.py>`_).

.. versionadded:: 1.8

.. note::
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.
The scrap module is currently only supported for Windows, X11 and Mac OS X.
On Mac OS X only text works at the moment - other types may be supported in
future releases.

.. function:: init

| :sl:`Initializes the scrap module.`
| :sg:`init () -> None`
| :sg:`init() -> None`

Initialize the scrap module.

:raises pygame.error: if unable to initialize scrap module

|

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()``.
.. note:: The scrap module requires :func:`pygame.display.set_mode()` be
called before being initialized.

.. ## pygame.scrap.init ##

Expand All @@ -94,7 +90,11 @@ type.
| :sl:`Returns True if the scrap module is currently initialized.`
| :sg:`get_init() -> bool`

Returns ``True`` if the ``pygame.scrap`` module is currently initialized.
Gets the scrap module's initialization state.

:returns: ``True`` if the :mod:`pygame.scrap` module is currently
initialized, ``False`` otherwise
:rtype: bool

.. versionadded:: 1.9.5

Expand All @@ -103,41 +103,48 @@ type.
.. function:: get

| :sl:`Gets the data for the specified type from the clipboard.`
| :sg:`get (type) -> bytes`
| :sg:`get(type) -> bytes or str or None`

Retrieves the data for the specified type from the clipboard. In python 3
the data is returned as a byte string and might need further processing
(such as decoding to Unicode).

:param string type: data type to retrieve from the clipboard

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.
:returns: data (byte string in python 3 or str in python 2) for the given
type identifier or ``None`` if no data for the given type is available
:rtype: bytes or str or None

::

text = pygame.scrap.get (SCRAP_TEXT)
text = pygame.scrap.get(pygame.SCRAP_TEXT)
if text:
# Do stuff with it.
print("There is text in the clipboard.")
else:
print "There does not seem to be text in the clipboard."
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`
| :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.
Gets a list of data type string identifiers for the data currently
available on the clipboard. Each identifier can be used in the
:func:`pygame.scrap.get()` method to get the clipboard content of the
specific type.

:returns: list of strings of the available clipboard data types, if there
is no data in the clipboard an empty list is returned
:rtype: list

::

types = pygame.scrap.get_types ()
for t in types:
for t in pygame.scrap.get_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)
# There is some content with the word "text" in its type string.
print(pygame.scrap.get(t))

.. ## pygame.scrap.get_types ##

Expand All @@ -146,56 +153,70 @@ type.
| :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.
Places data for a given clipboard type into the clipboard. The data must
be a string buffer. The type is a string identifying the type of data to be
placed into the clipboard. This can be one of the predefined
``pygame.SCRAP_PBM``, ``pygame.SCRAP_PPM``, ``pygame.SCRAP_BMP`` or
``pygame.SCRAP_TEXT`` values or a user defined string identifier.

The method raises an exception, if the content could not be placed into the
clipboard.
:param string type: type identifier of the data to be placed into the
clipboard
:param data: data to be place into the clipboard (in python 3 data is a
byte string and in python 2 data is a str)
:type data: bytes or str

:raises pygame.error: if unable to put the data 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")
with open("example.bmp", "rb") as fp:
pygame.scrap.put(pygame.SCRAP_BMP, fp.read())
# The image data is now on the clipboard for other applications to access
# it.
pygame.scrap.put(pygame.SCRAP_TEXT, b"A text to copy")
pygame.scrap.put("Plain text", b"Data for user defined type 'Plain text'")

.. ## pygame.scrap.put ##

.. function:: contains

| :sl:`Checks, whether a certain type is available in the clipboard.`
| :sg:`contains (type) -> bool`
| :sl:`Checks whether data for a given 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.
Checks whether data for the given type is currently available in the
clipboard.

:param string type: data type to check availability of

:returns: ``True`` if data for the passed type is available in the
clipboard, ``False`` otherwise
:rtype: bool

::

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."
if pygame.scrap.contains(pygame.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.`
| :sl:`Indicates if the clipboard ownership has been lost by the pygame application.`
| :sg:`lost() -> bool`

Returns True, if the clipboard is currently owned by the pygame application,
False otherwise.
Indicates if the clipboard ownership has been lost by the pygame
application.

:returns: ``True``, if the clipboard ownership has been lost by the pygame
application, ``False`` if the pygame application still owns the clipboard
:rtype: bool

::

if pygame.scrap.lost ():
print "No content from me anymore. The clipboard is used by someone else."
if pygame.scrap.lost():
print("The clipboard is in use by another application.")

.. ## pygame.scrap.lost ##

Expand All @@ -204,13 +225,18 @@ type.
| :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.
Sets the access mode for the clipboard. This is only of interest for X11
environments where clipboard modes ``pygame.SCRAP_SELECTION`` (for mouse
selections) and ``pygame.SCRAP_CLIPBOARD`` (for the clipboard) are
available. Setting the mode to ``pygame.SCRAP_SELECTION`` in other
environments will not change the mode from ``pygame.SCRAP_CLIPBOARD``.

:param mode: access mode, supported values are ``pygame.SCRAP_CLIPBOARD``
and ``pygame.SCRAP_SELECTION`` (``pygame.SCRAP_SELECTION`` only has an
effect when used on X11 platforms)

If a value different from ``SCRAP_CLIPBOARD`` or ``SCRAP_SELECTION`` is
passed, a ValueError will be raised.
:raises ValueError: if the ``mode`` parameter is not
``pygame.SCRAP_CLIPBOARD`` or ``pygame.SCRAP_SELECTION``

.. ## pygame.scrap.set_mode ##

Expand Down
22 changes: 11 additions & 11 deletions src_c/doc/scrap_doc.h
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,12 +1,12 @@
/* Auto generated file: with makeref.py . Docs go in docs/reST/ref/ . */
#define DOC_PYGAMESCRAP "pygame module for clipboard support."
#define DOC_PYGAMESCRAPINIT "init () -> None\nInitializes the scrap module."
#define DOC_PYGAMESCRAPINIT "init() -> None\nInitializes the scrap module."
#define DOC_PYGAMESCRAPGETINIT "get_init() -> bool\nReturns True if the scrap module is currently initialized."
#define DOC_PYGAMESCRAPGET "get (type) -> bytes\nGets the data for the specified type from the clipboard."
#define DOC_PYGAMESCRAPGETTYPES "get_types () -> list\nGets a list of the available clipboard types."
#define DOC_PYGAMESCRAPGET "get(type) -> bytes or str or None\nGets the data for the specified type from the clipboard."
#define DOC_PYGAMESCRAPGETTYPES "get_types() -> list\nGets a list of the available clipboard types."
#define DOC_PYGAMESCRAPPUT "put(type, data) -> None\nPlaces data into the clipboard."
#define DOC_PYGAMESCRAPCONTAINS "contains (type) -> bool\nChecks, whether a certain type is available in the clipboard."
#define DOC_PYGAMESCRAPLOST "lost() -> bool\nChecks whether the clipboard is currently owned by the application."
#define DOC_PYGAMESCRAPCONTAINS "contains(type) -> bool\nChecks whether data for a given type is available in the clipboard."
#define DOC_PYGAMESCRAPLOST "lost() -> bool\nIndicates if the clipboard ownership has been lost by the pygame application."
#define DOC_PYGAMESCRAPSETMODE "set_mode(mode) -> None\nSets the clipboard access mode."


Expand All @@ -18,32 +18,32 @@ pygame.scrap
pygame module for clipboard support.

pygame.scrap.init
init () -> None
init() -> None
Initializes the scrap module.

pygame.scrap.get_init
get_init() -> bool
Returns True if the scrap module is currently initialized.

pygame.scrap.get
get (type) -> bytes
get(type) -> bytes or str or None
Gets the data for the specified type from the clipboard.

pygame.scrap.get_types
get_types () -> list
get_types() -> list
Gets a list of the available clipboard types.

pygame.scrap.put
put(type, data) -> None
Places data into the clipboard.

pygame.scrap.contains
contains (type) -> bool
Checks, whether a certain type is available in the clipboard.
contains(type) -> bool
Checks whether data for a given type is available in the clipboard.

pygame.scrap.lost
lost() -> bool
Checks whether the clipboard is currently owned by the application.
Indicates if the clipboard ownership has been lost by the pygame application.

pygame.scrap.set_mode
set_mode(mode) -> None
Expand Down