1.. include:: common.txt 2 3:mod:`pygame.cursors` 4===================== 5 6.. module:: pygame.cursors 7 :synopsis: pygame module for cursor resources 8 9| :sl:`pygame module for cursor resources` 10 11Pygame offers control over the system hardware cursor. Pygame supports 12black and white cursors (bitmap cursors), as well as system variant cursors and color cursors. 13You control the cursor with functions inside :mod:`pygame.mouse`. 14 15This cursors module contains functions for loading and decoding various 16cursor formats. These allow you to easily store your cursors in external files 17or directly as encoded python strings. 18 19The module includes several standard cursors. The :func:`pygame.mouse.set_cursor()` 20function takes several arguments. All those arguments have been stored in a 21single tuple you can call like this: 22 23:: 24 25 >>> pygame.mouse.set_cursor(*pygame.cursors.arrow) 26 27The following variables can be passed to ``pygame.mouse.set_cursor`` function: 28 29 * ``pygame.cursors.arrow`` 30 31 * ``pygame.cursors.diamond`` 32 33 * ``pygame.cursors.broken_x`` 34 35 * ``pygame.cursors.tri_left`` 36 37 * ``pygame.cursors.tri_right`` 38 39This module also contains a few cursors as formatted strings. You'll need to 40pass these to ``pygame.cursors.compile()`` function before you can use them. 41The example call would look like this: 42 43:: 44 45 >>> cursor = pygame.cursors.compile(pygame.cursors.textmarker_strings) 46 >>> pygame.mouse.set_cursor((8, 16), (0, 0), *cursor) 47 48The following strings can be converted into cursor bitmaps with 49``pygame.cursors.compile()`` : 50 51 * ``pygame.cursors.thickarrow_strings`` 52 53 * ``pygame.cursors.sizer_x_strings`` 54 55 * ``pygame.cursors.sizer_y_strings`` 56 57 * ``pygame.cursors.sizer_xy_strings`` 58 59 * ``pygame.cursor.textmarker_strings`` 60 61.. function:: compile 62 63 | :sl:`create binary cursor data from simple strings` 64 | :sg:`compile(strings, black='X', white='.', xor='o') -> data, mask` 65 66 A sequence of strings can be used to create binary cursor data for the 67 system cursor. This returns the binary data in the form of two tuples. 68 Those can be passed as the third and fourth arguments respectively of the 69 :func:`pygame.mouse.set_cursor()` function. 70 71 If you are creating your own cursor strings, you can use any value represent 72 the black and white pixels. Some system allow you to set a special toggle 73 color for the system color, this is also called the xor color. If the system 74 does not support xor cursors, that color will simply be black. 75 76 The height must be divisible by 8. The width of the strings must all be equal 77 and be divisible by 8. If these two conditions are not met, ``ValueError`` is 78 raised. 79 An example set of cursor strings looks like this 80 81 :: 82 83 thickarrow_strings = ( #sized 24x24 84 "XX ", 85 "XXX ", 86 "XXXX ", 87 "XX.XX ", 88 "XX..XX ", 89 "XX...XX ", 90 "XX....XX ", 91 "XX.....XX ", 92 "XX......XX ", 93 "XX.......XX ", 94 "XX........XX ", 95 "XX........XXX ", 96 "XX......XXXXX ", 97 "XX.XXX..XX ", 98 "XXXX XX..XX ", 99 "XX XX..XX ", 100 " XX..XX ", 101 " XX..XX ", 102 " XX..XX ", 103 " XXXX ", 104 " XX ", 105 " ", 106 " ", 107 " ") 108 109 .. ## pygame.cursors.compile ## 110 111.. function:: load_xbm 112 113 | :sl:`load cursor data from an XBM file` 114 | :sg:`load_xbm(cursorfile) -> cursor_args` 115 | :sg:`load_xbm(cursorfile, maskfile) -> cursor_args` 116 117 This loads cursors for a simple subset of ``XBM`` files. ``XBM`` files are 118 traditionally used to store cursors on UNIX systems, they are an ASCII 119 format used to represent simple images. 120 121 Sometimes the black and white color values will be split into two separate 122 ``XBM`` files. You can pass a second maskfile argument to load the two 123 images into a single cursor. 124 125 The cursorfile and maskfile arguments can either be filenames or file-like 126 object with the readlines method. 127 128 The return value cursor_args can be passed directly to the 129 ``pygame.mouse.set_cursor()`` function. 130 131 .. ## pygame.cursors.load_xbm ## 132 133 134 135.. class:: Cursor 136 137 | :sl:`pygame object representing a cursor` 138 | :sg:`Cursor(size, hotspot, xormasks, andmasks) -> Cursor` 139 | :sg:`Cursor(hotspot, surface) -> Cursor` 140 | :sg:`Cursor(constant) -> Cursor` 141 | :sg:`Cursor(Cursor) -> Cursor` 142 | :sg:`Cursor() -> Cursor` 143 144 In pygame 2, there are 3 types of cursors you can create to give your 145 game that little bit of extra polish. There's **bitmap** type cursors, 146 which existed in pygame 1.x, and are compiled from a string or load from an xbm file. 147 Then there are **system** type cursors, where you choose a preset that will 148 convey the same meaning but look native across different operating systems. 149 Finally you can create a **color** cursor, which displays a pygame surface as the cursor. 150 151 **Creating a system cursor** 152 153 Choose a constant from this list, pass it into ``pygame.cursors.Cursor(constant)``, 154 and you're good to go. 155 156 :: 157 158 Pygame Cursor Constant Description 159 -------------------------------------------- 160 pygame.SYSTEM_CURSOR_ARROW arrow 161 pygame.SYSTEM_CURSOR_IBEAM i-beam 162 pygame.SYSTEM_CURSOR_WAIT wait 163 pygame.SYSTEM_CURSOR_CROSSHAIR crosshair 164 pygame.SYSTEM_CURSOR_WAITARROW small wait cursor 165 (or wait if not available) 166 pygame.SYSTEM_CURSOR_SIZENWSE double arrow pointing 167 northwest and southeast 168 pygame.SYSTEM_CURSOR_SIZENESW double arrow pointing 169 northeast and southwest 170 pygame.SYSTEM_CURSOR_SIZEWE double arrow pointing 171 west and east 172 pygame.SYSTEM_CURSOR_SIZENS double arrow pointing 173 north and south 174 pygame.SYSTEM_CURSOR_SIZEALL four pointed arrow pointing 175 north, south, east, and west 176 pygame.SYSTEM_CURSOR_NO slashed circle or crossbones 177 pygame.SYSTEM_CURSOR_HAND hand 178 179 **Creating a cursor without passing arguments** 180 181 In addition to the cursor constants available and described above, 182 you can also call ``pygame.cursors.Cursor()``, and your cursor is ready (doing that is the same as 183 calling ``pygame.cursors.Cursor(pygame.SYSTEM_CURSOR_ARROW)``. 184 Doing one of those calls actually creates a system cursor using the default native image. 185 186 **Creating a color cursor** 187 188 To create a color cursor, create a ``Cursor`` from a ``hotspot`` and a ``surface``. 189 ``hotspot`` is an (x,y) coordinate that determines where in the cursor the exact point is. 190 The hotspot position must be within the bounds of the ``surface``. 191 192 **Creating a bitmap cursor** 193 194 When the mouse cursor is visible, it will be displayed as a black and white 195 bitmap using the given bitmask arrays. The ``size`` is a sequence containing 196 the cursor width and height. ``hotspot`` is a sequence containing the cursor 197 hotspot position. 198 199 A cursor has a width and height, but a mouse position is represented by a 200 set of point coordinates. So the value passed into the cursor ``hotspot`` 201 variable helps pygame to actually determine at what exact point the cursor 202 is at. 203 204 ``xormasks`` is a sequence of bytes containing the cursor xor data masks. 205 Lastly ``andmasks``, a sequence of bytes containing the cursor bitmask data. 206 To create these variables, we can make use of the 207 :func:`pygame.cursors.compile()` function. 208 209 Width and height must be a multiple of 8, and the mask arrays must be the 210 correct size for the given width and height. Otherwise an exception is raised. 211 212 .. method:: copy 213 | :sl:`copy the current cursor` 214 | :sg:`copy() -> Cursor` 215 216 Returns a new Cursor object with the same data and hotspot as the original. 217 .. ## pygame.cursors.Cursor.copy ## 218 219 220 .. attribute:: type 221 222 | :sl:`Gets the cursor type` 223 | :sg:`type -> string` 224 225 The type will be ``"system"``, ``"bitmap"``, or ``"color"``. 226 227 .. ## pygame.cursors.Cursor.type ## 228 229 .. attribute:: data 230 231 | :sl:`Gets the cursor data` 232 | :sg:`data -> tuple` 233 234 Returns the data that was used to create this cursor object, wrapped up in a tuple. 235 236 .. ## pygame.cursors.Cursor.data ## 237 238 .. versionadded:: 2.0.1 239 240 .. ## pygame.cursors.Cursor ## 241 242.. ## pygame.cursors ## 243 244Example code for creating and settings cursors. (Click the mouse to switch cursor) 245 246.. literalinclude:: code_examples/cursors_module_example.py 247