1 /* 2 pygame - Python Game Library 3 Copyright (C) 2006, 2007 Rene Dudfield, Marcus von Appen 4 5 Originally put in the public domain by Sam Lantinga. 6 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. 11 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. 16 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 20 */ 21 22 #ifndef SCRAP_H 23 #define SCRAP_H 24 25 /* This is unconditionally defined in Python.h */ 26 #if defined(_POSIX_C_SOURCE) 27 #undef _POSIX_C_SOURCE 28 #endif 29 30 #include <Python.h> 31 32 /* Handle clipboard text and data in arbitrary formats */ 33 34 /** 35 * Predefined supported pygame scrap types. 36 */ 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" 41 42 /** 43 * The supported scrap clipboard types. 44 * 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. 48 */ 49 typedef enum 50 { 51 SCRAP_CLIPBOARD, 52 SCRAP_SELECTION /* only supported in X11 environments. */ 53 } ScrapClipType; 54 55 /** 56 * Macro for initialization checks. 57 */ 58 #define PYGAME_SCRAP_INIT_CHECK() \ 59 if(!pygame_scrap_initialized()) \ 60 return (PyErr_SetString (pgExc_SDLError, \ 61 "scrap system not initialized."), NULL) 62 63 /** 64 * \brief Checks, whether the pygame scrap module was initialized. 65 * 66 * \return 1 if the modules was initialized, 0 otherwise. 67 */ 68 extern int 69 pygame_scrap_initialized (void); 70 71 /** 72 * \brief Initializes the pygame scrap module internals. Call this before any 73 * other method. 74 * 75 * \return 1 on successful initialization, 0 otherwise. 76 */ 77 extern int 78 pygame_scrap_init (void); 79 80 /** 81 * \brief Checks, whether the pygame window lost the clipboard focus or not. 82 * 83 * \return 1 if the window lost the focus, 0 otherwise. 84 */ 85 extern int 86 pygame_scrap_lost (void); 87 88 /** 89 * \brief Places content of a specific type into the clipboard. 90 * 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". 96 * 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). 100 * 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). 104 * 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, 109 * 0 otherwise. 110 */ 111 extern int 112 pygame_scrap_put (char *type, int srclen, char *src); 113 114 /** 115 * \brief Gets the current content from the clipboard. 116 * 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. 120 * 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. 125 */ 126 extern char* 127 pygame_scrap_get (char *type, unsigned long *count); 128 129 /** 130 * \brief Gets the currently available content types from the clipboard. 131 * 132 * \return The different available content types or NULL in case of an 133 * error or if no content type is available. 134 */ 135 extern char** 136 pygame_scrap_get_types (void); 137 138 /** 139 * \brief Checks whether content for the specified scrap type is currently 140 * available in the clipboard. 141 * 142 * \param type The type to check for. 143 * \return 1, if there is content and 0 otherwise. 144 */ 145 extern int 146 pygame_scrap_contains (char *type); 147 148 #endif /* SCRAP_H */ 149