2 pygame - Python Game Library
3 Copyright (C) 2006, 2007 Rene Dudfield, Marcus von Appen
5 Originally put in the public domain by Sam Lantinga.
7 This library is free software; you can redistribute it and/or
8 modify it under the terms of the GNU Library General Public
9 License as published by the Free Software Foundation; either
10 version 2 of the License, or (at your option) any later version.
12 This library is distributed in the hope that it will be useful,
13 but WITHOUT ANY WARRANTY; without even the implied warranty of
14 MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU
15 Library General Public License for more details.
17 You should have received a copy of the GNU Library General Public
18 License along with this library; if not, write to the Free
19 Foundation, Inc., 59 Temple Place, Suite 330, Boston, MA 02111-1307 USA
25 /* This is unconditionally defined in Python.h */
26 #if defined(_POSIX_C_SOURCE)
27 #undef _POSIX_C_SOURCE
32 /* Handle clipboard text and data in arbitrary formats */
35 * Predefined supported pygame scrap types.
37 #define PYGAME_SCRAP_TEXT "text/plain"
38 #define PYGAME_SCRAP_BMP "image/bmp"
39 #define PYGAME_SCRAP_PPM "image/ppm"
40 #define PYGAME_SCRAP_PBM "image/pbm"
43 * The supported scrap clipboard types.
45 * This is only relevant in a X11 environment, which supports mouse
46 * selections as well. For Win32 and MacOS environments the default
47 * clipboard is used, no matter what value is passed.
52 SCRAP_SELECTION /* only supported in X11 environments. */
56 * Macro for initialization checks.
58 #define PYGAME_SCRAP_INIT_CHECK() \
59 if(!pygame_scrap_initialized()) \
60 return (PyErr_SetString (pgExc_SDLError, \
61 "scrap system not initialized."), NULL)
64 * \brief Checks, whether the pygame scrap module was initialized.
66 * \return 1 if the modules was initialized, 0 otherwise.
69 pygame_scrap_initialized (void);
72 * \brief Initializes the pygame scrap module internals. Call this before any
75 * \return 1 on successful initialization, 0 otherwise.
78 pygame_scrap_init (void);
81 * \brief Checks, whether the pygame window lost the clipboard focus or not.
83 * \return 1 if the window lost the focus, 0 otherwise.
86 pygame_scrap_lost (void);
89 * \brief Places content of a specific type into the clipboard.
91 * \note For X11 the following notes are important: The following types
92 * are reserved for internal usage and thus will throw an error on
93 * setting them: "TIMESTAMP", "TARGETS", "SDL_SELECTION".
94 * Setting PYGAME_SCRAP_TEXT ("text/plain") will also automatically
95 * set the X11 types "STRING" (XA_STRING), "TEXT" and "UTF8_STRING".
97 * For Win32 the following notes are important: Setting
98 * PYGAME_SCRAP_TEXT ("text/plain") will also automatically set
99 * the Win32 type "TEXT" (CF_TEXT).
101 * For QNX the following notes are important: Setting
102 * PYGAME_SCRAP_TEXT ("text/plain") will also automatically set
103 * the QNX type "TEXT" (Ph_CL_TEXT).
105 * \param type The type of the content.
106 * \param srclen The length of the content.
107 * \param src The NULL terminated content.
108 * \return 1, if the content could be successfully pasted into the clipboard,
112 pygame_scrap_put (char *type, int srclen, char *src);
115 * \brief Gets the current content from the clipboard.
117 * \note The received content does not need to be the content previously
118 * placed in the clipboard using pygame_put_scrap(). See the
119 * pygame_put_scrap() notes for more details.
121 * \param type The type of the content to receive.
122 * \param count The size of the returned content.
123 * \return The content or NULL in case of an error or if no content of the
124 * specified type was available.
127 pygame_scrap_get (char *type, unsigned long *count);
130 * \brief Gets the currently available content types from the clipboard.
132 * \return The different available content types or NULL in case of an
133 * error or if no content type is available.
136 pygame_scrap_get_types (void);
139 * \brief Checks whether content for the specified scrap type is currently
140 * available in the clipboard.
142 * \param type The type to check for.
143 * \return 1, if there is content and 0 otherwise.
146 pygame_scrap_contains (char *type);