Commits

Anonymous committed 51e534f

Improved pygame.scrap documentation.

Comments (0)

Files changed (2)

 
 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.
+types. It defines some basic own data types 
 
-New in pygame 1.8.  Only works for windows, X11, QNX, Mac OS X so far.
-EXPERIMENTAL: note, this module is experimental, and will be changing in 
- the next release of pygame.
+  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 pygame.scrap module
+functions.
+
+For Windows platforms, the additional types are supported automatically
+and resolve to its 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 its 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.
 <SECTION>
 
-
-
 init
 Initializes the scrap module.
 scrap.init () -> None
+
 Tries to initialize the scrap module and raises an exception, if it fails.
 <END>
 
-
 get
 Gets the data for the specified type from the clipboard.
 scrap.get (type) -> string
 scrap.put(type, data) -> None
 
 Places data for a specific clipboard type into the clipboard.
-The data must be a string buffer.
+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.
 <END>
 clipboard, False otherwise.
 <END>
 
-
 lost
-Checks whether the clipboard is currently owned by the application
+Checks whether the clipboard is currently owned by the application.
 scrap.lost() -> bool
 
-Returns true, if the clipboard is currently owned by the pygame
-application, false otherwise.
+Returns True, if the clipboard is currently owned by the pygame
+application, False otherwise.
 <END>
 
-
 set_mode
 Sets the clipboard access mode.
 scrap.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. The
-method does not have any influence on other environments.
+(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.
 
 /**
  * Predefined supported pygame scrap types.
- * 
- * PYGAME_SCRAP_TEXT should be used for text.
- * PYGAME_SCRAP_BMP should be used for arbitrary data in a string format.
- * 
- * PYGAME_SCRAP_BMP is only supported by pygame window instances. For
- * interchangeable data that should be used by other applications, use
- * PYGAME_SCRAP_TEXT.
  */
 #define PYGAME_SCRAP_TEXT "text/plain"
 #define PYGAME_SCRAP_BMP "image/bmp"