.local/include/python3.9/pygame/scrap.h

   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 */