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