1. pygame
  2. pygame
  3. pygame


pygame / docs / ref / scrap.html

<title>scrap - Pygame Documentation</title>
<body bgcolor=#aaeebb text=#000000 link=#331111 vlink=#331111>

<table cellpadding=0 cellspacing=0 border=0 style='border: 3px solid black;' width='100%'>
<td bgcolor='#c2fc20' style='padding: 6px;' align=center valign=center><a href='http://www.pygame.org/'><img src='../pygame_tiny.gif' border=0 width=200 height=60></a><br><b>pygame documentation</b></td>
<td bgcolor='#6aee28' style='border-left: 3px solid black; padding: 6px;' align=center valign=center>
	<a href=http://www.pygame.org>Pygame Home</a> &nbsp;||&nbsp;
	<a href=../index.html>Help Contents</a> &nbsp;||
	<a href=index.html>Reference Index</a> &nbsp;||
<a href="camera.html">Camera</a>&nbsp;||&nbsp;
<a href="cdrom.html">Cdrom</a>&nbsp;||&nbsp;
<a href="color.html">Color</a>&nbsp;||&nbsp;
<a href="cursors.html">Cursors</a>&nbsp;||&nbsp;
<a href="display.html">Display</a>&nbsp;||&nbsp;
<a href="draw.html">Draw</a>&nbsp;||&nbsp;
<a href="event.html">Event</a>&nbsp;||&nbsp;
<a href="examples.html">Examples</a>&nbsp;||&nbsp;
<a href="font.html">Font</a>&nbsp;||&nbsp;
<a href="gfxdraw.html">Gfxdraw</a>&nbsp;||&nbsp;
<a href="image.html">Image</a>&nbsp;||&nbsp;
<a href="joystick.html">Joystick</a>&nbsp;||&nbsp;
<a href="key.html">Key</a>&nbsp;||&nbsp;
<a href="locals.html">Locals</a>&nbsp;||&nbsp;
<a href="mask.html">Mask</a>&nbsp;||&nbsp;
<a href="midi.html">Midi</a>&nbsp;||&nbsp;
<a href="mixer.html">Mixer</a>&nbsp;||&nbsp;
<a href="mouse.html">Mouse</a>&nbsp;||&nbsp;
<a href="movie.html">Movie</a>&nbsp;||&nbsp;
<a href="music.html">Music</a>&nbsp;||&nbsp;
<a href="overlay.html">Overlay</a>&nbsp;||&nbsp;
<a href="pixelarray.html">Pixelarray</a>&nbsp;||&nbsp;
<a href="pygame.html">Pygame</a>&nbsp;||&nbsp;
<a href="rect.html">Rect</a>&nbsp;||&nbsp;
<a href="scrap.html">Scrap</a>&nbsp;||&nbsp;
<a href="sndarray.html">Sndarray</a>&nbsp;||&nbsp;
<a href="sprite.html">Sprite</a>&nbsp;||&nbsp;
<a href="surface.html">Surface</a>&nbsp;||&nbsp;
<a href="surfarray.html">Surfarray</a>&nbsp;||&nbsp;
<a href="tests.html">Tests</a>&nbsp;||&nbsp;
<a href="time.html">Time</a>&nbsp;||&nbsp;
<a href="transform.html">Transform</a>

<a name="pygame.scrap">
  <i>pygame module for clipboard support.</i><br>
  <tr><td><a href="scrap.html#pygame.scrap.init">pygame.scrap.init</a> - <font size=-1>Initializes the scrap module.</font></td><td>Initializes the scrap module.</td></tr>
  <tr><td><a href="scrap.html#pygame.scrap.get">pygame.scrap.get</a> - <font size=-1>Gets the data for the specified type from the clipboard.</font></td><td>Gets the data for the specified type from the clipboard.</td></tr>
  <tr><td><a href="scrap.html#pygame.scrap.get_types">pygame.scrap.get_types</a> - <font size=-1>Gets a list of the available clipboard types.</font></td><td>Gets a list of the available clipboard types.</td></tr>
  <tr><td><a href="scrap.html#pygame.scrap.put">pygame.scrap.put</a> - <font size=-1>Places data into the clipboard.</font></td><td>Places data into the clipboard.</td></tr>
  <tr><td><a href="scrap.html#pygame.scrap.contains">pygame.scrap.contains</a> - <font size=-1>Checks, whether a certain type is available in the clipboard.</font></td><td>Checks, whether a certain type is available in the clipboard.</td></tr>
  <tr><td><a href="scrap.html#pygame.scrap.lost">pygame.scrap.lost</a> - <font size=-1>Checks whether the clipboard is currently owned by the application.</font></td><td>Checks whether the clipboard is currently owned by the application.</td></tr>
  <tr><td><a href="scrap.html#pygame.scrap.set_mode">pygame.scrap.set_mode</a> - <font size=-1>Sets the clipboard access mode.</font></td><td>Sets the clipboard access mode.</td></tr>
<p><tt>EXPERIMENTAL!:</tt> meaning this api may change, or dissapear in later pygame releases. If you use this, your code will break with the next pygame release. </p>
<p>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 </p>
<pre>  SCRAP_PPM
</pre><p>to be placed into the clipboard and allows to use define own clipboard types. <tt>SCRAP_PPM</tt>, <tt>SCRAP_PBM</tt> and <tt>SCRAP_BMP</tt> are suitable for surface buffers to be shared with other applications, while <tt>SCRAP_TEXT</tt> is an alias for the plain text clipboard type. </p>
<p>The <tt>SCRAP_*</tt> types refer to the following <tt>MIME</tt> types and register those as well as the default operating system type for this type of data: </p>
<pre>  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
</pre><p>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 <tt>pygame.scrap</tt> module functions. </p>
<p>For Windows platforms, the additional types are supported automatically and resolve to their internal definitions: </p>
<pre>  text/plain;charset=utf-8 for UTF-8 encoded text
  audio/wav                for WAV encoded audio
  image/tiff               for TIFF encoded image data
</pre><p>For <tt>X11</tt> platforms, the additional types are supported automatically and resolve to their internal definitions: </p>
<pre>  UTF8_STRING               for UTF-8 encoded text
  text/plain;charset=utf-8  for UTF-8 encoded text
  COMPOUND_TEXT             for COMPOUND text
</pre><p>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 </p>
<pre>  pygame.scrap.put ("own_data", data)
</pre><p>can only be used by applications, which query the clipboard for the "own_data" type. </p>
<p>New in pygame <tt>1.8</tt>. Only works for Windows, <tt>X11</tt> and Mac <tt>OS</tt> <tt>X</tt> so far. On Mac <tt>OSX</tt> only text works at the moment - other types will be supported in the next release. </p>
<!--COMMENTS:pygame.scrap--> &nbsp;<br> 

<a name="pygame.scrap.init">
  <i>Initializes the scrap module.</i><br>
  <tt>scrap.init () -> None</tt><br>
<p>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 <tt><a href="display.html#pygame.display.set_mode">pygame.display.set_mode</a> - <font size=-1>initialize a window or screen for display</font></tt>. </p>
<!--COMMENTS:pygame.scrap.init--> &nbsp;<br> 

<a name="pygame.scrap.get">
  <i>Gets the data for the specified type from the clipboard.</i><br>
  <tt>scrap.get (type) -> string</tt><br>
<p>Returns the data for the specified type from the clipboard. The data is returned as string and might need further processing. If no data for the passed type is available, None is returned. </p>
<pre>  text = pygame.scrap.get (SCRAP_TEXT)
  if text:
      # Do stuff with it.
      print "There does not seem to be text in the clipboard."
<!--COMMENTS:pygame.scrap.get--> &nbsp;<br> 

<a name="pygame.scrap.get_types">
  <i>Gets a list of the available clipboard types.</i><br>
  <tt>scrap.get_types () -> list</tt><br>
<p>Gets a list of strings with the identifiers for the available clipboard types. Each identifier can be used in the <tt>scrap.get()</tt> method to get the clipboard content of the specific type. If there is no data in the clipboard, an empty list is returned. </p>
<pre>  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)
<!--COMMENTS:pygame.scrap.get_types--> &nbsp;<br> 

<a name="pygame.scrap.put">
  <i>Places data into the clipboard.</i><br>
  <tt>scrap.put(type, data) -> None</tt><br>
<p>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 <tt>SCRAP_PBM</tt>, <tt>SCRAP_PPM</tt>, <tt>SCRAP_BMP</tt> or <tt>SCRAP_TEXT</tt> values or an own string identifier. </p>
<p>The method raises an exception, if the content could not be placed into the clipboard. </p>
<pre>  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")
<!--COMMENTS:pygame.scrap.put--> &nbsp;<br> 

<a name="pygame.scrap.contains">
  <i>Checks, whether a certain type is available in the clipboard.</i><br>
  <tt>scrap.contains (type) -> bool</tt><br>
<p>Returns True, if data for the passed type is available in the clipboard, False otherwise. </p>
<pre>  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."
<!--COMMENTS:pygame.scrap.contains--> &nbsp;<br> 

<a name="pygame.scrap.lost">
  <i>Checks whether the clipboard is currently owned by the application.</i><br>
  <tt>scrap.lost() -> bool</tt><br>
<p>Returns True, if the clipboard is currently owned by the pygame application, False otherwise. </p>
<pre>  if pygame.scrap.lost ():
     print "No content from me anymore. The clipboard is used by someone else."
<!--COMMENTS:pygame.scrap.lost--> &nbsp;<br> 

<a name="pygame.scrap.set_mode">
  <i>Sets the clipboard access mode.</i><br>
  <tt>scrap.set_mode(mode) -> None</tt><br>
<p>Sets the access mode for the clipboard. This is only of interest for <tt>X11</tt> environments, where clipboard modes for mouse selections <tt>(SRAP_SELECTION)</tt> and the clipboard <tt>(SCRAP_CLIPBOARD)</tt> are available. Setting the mode to <tt>SCRAP_SELECTION</tt> in other environments will not cause any difference. </p>
<p>If a value different from <tt>SCRAP_CLIPBOARD</tt> or <tt>SCRAP_SELECTION</tt> is passed, a ValueError will be raised. </p>
<!--COMMENTS:pygame.scrap.set_mode--> &nbsp;<br>