Commits

marcus  committed 51e534f

Improved pygame.scrap documentation.

  • Participants
  • Parent commits 74bc00d

Comments (0)

Files changed (2)

File src/scrap.doc

 
 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"