Skip to content

Commit 9258b19

Browse files
zoldalma999zoldalma999
committed
Move cursors docs to python source
1 parent bbedc0a commit 9258b19

File tree

3 files changed

+203
-293
lines changed

3 files changed

+203
-293
lines changed

‎docs/reST/ref/cursors.rst‎

Lines changed: 4 additions & 240 deletions
Original file line numberDiff line numberDiff line change
@@ -3,248 +3,12 @@
33
:mod:`pygame.cursors`
44
=====================
55

6-
.. module:: pygame.cursors
7-
:synopsis: pygame module for cursor resources
6+
.. autopgmodule:: pygame.cursors
7+
:members: compile, load_xbm
88

9-
| :sl:`pygame module for cursor resources`
109

11-
Pygame offers control over the system hardware cursor. Pygame supports
12-
black and white cursors (bitmap cursors), as well as system variant cursors and color cursors.
13-
You control the cursor with functions inside :mod:`pygame.mouse`.
14-
15-
This cursors module contains functions for loading and decoding various
16-
cursor formats. These allow you to easily store your cursors in external files
17-
or directly as encoded python strings.
18-
19-
The module includes several standard cursors. The :func:`pygame.mouse.set_cursor()`
20-
function takes several arguments. All those arguments have been stored in a
21-
single tuple you can call like this:
22-
23-
::
24-
25-
>>> pygame.mouse.set_cursor(*pygame.cursors.arrow)
26-
27-
The 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-
39-
This module also contains a few cursors as formatted strings. You'll need to
40-
pass these to ``pygame.cursors.compile()`` function before you can use them.
41-
The 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-
48-
The 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. Be advised that not all systems support every system
155-
cursor, and you may get a substitution instead. For example, on macOS,
156-
WAIT/WAITARROW should show up as an arrow, and SIZENWSE/SIZENESW/SIZEALL
157-
should show up as a closed hand. And on Wayland, every SIZE cursor should
158-
show up as a hand.
159-
160-
::
161-
162-
Pygame Cursor Constant Description
163-
--------------------------------------------
164-
pygame.SYSTEM_CURSOR_ARROW arrow
165-
pygame.SYSTEM_CURSOR_IBEAM i-beam
166-
pygame.SYSTEM_CURSOR_WAIT wait
167-
pygame.SYSTEM_CURSOR_CROSSHAIR crosshair
168-
pygame.SYSTEM_CURSOR_WAITARROW small wait cursor
169-
(or wait if not available)
170-
pygame.SYSTEM_CURSOR_SIZENWSE double arrow pointing
171-
northwest and southeast
172-
pygame.SYSTEM_CURSOR_SIZENESW double arrow pointing
173-
northeast and southwest
174-
pygame.SYSTEM_CURSOR_SIZEWE double arrow pointing
175-
west and east
176-
pygame.SYSTEM_CURSOR_SIZENS double arrow pointing
177-
north and south
178-
pygame.SYSTEM_CURSOR_SIZEALL four pointed arrow pointing
179-
north, south, east, and west
180-
pygame.SYSTEM_CURSOR_NO slashed circle or crossbones
181-
pygame.SYSTEM_CURSOR_HAND hand
182-
183-
**Creating a cursor without passing arguments**
184-
185-
In addition to the cursor constants available and described above,
186-
you can also call ``pygame.cursors.Cursor()``, and your cursor is ready (doing that is the same as
187-
calling ``pygame.cursors.Cursor(pygame.SYSTEM_CURSOR_ARROW)``.
188-
Doing one of those calls actually creates a system cursor using the default native image.
189-
190-
**Creating a color cursor**
191-
192-
To create a color cursor, create a ``Cursor`` from a ``hotspot`` and a ``surface``.
193-
``hotspot`` are (x,y) coordinates that determine where in the cursor the exact point is.
194-
The hotspot position must be within the bounds of the ``surface``.
195-
196-
**Creating a bitmap cursor**
197-
198-
When the mouse cursor is visible, it will be displayed as a black and white
199-
bitmap using the given bitmask arrays. The ``size`` is a sequence containing
200-
the cursor width and height. ``hotspot`` is a sequence containing the cursor
201-
hotspot position.
202-
203-
A cursor has a width and height, but a mouse position is represented by a
204-
set of point coordinates. So the value passed into the cursor ``hotspot``
205-
variable helps pygame to actually determine at what exact point the cursor
206-
is at.
207-
208-
``xormasks`` is a sequence of bytes containing the cursor xor data masks.
209-
Lastly ``andmasks``, a sequence of bytes containing the cursor bitmask data.
210-
To create these variables, we can make use of the
211-
:func:`pygame.cursors.compile()` function.
212-
213-
Width and height must be a multiple of 8, and the mask arrays must be the
214-
correct size for the given width and height. Otherwise an exception is raised.
215-
216-
.. method:: copy
217-
218-
| :sl:`copy the current cursor`
219-
| :sg:`copy() -> Cursor`
220-
221-
Returns a new Cursor object with the same data and hotspot as the original.
222-
.. ## pygame.cursors.Cursor.copy ##
223-
224-
225-
.. attribute:: type
226-
227-
| :sl:`get the cursor type`
228-
| :sg:`type -> string`
229-
230-
The type will be ``"system"``, ``"bitmap"``, or ``"color"``.
231-
232-
.. ## pygame.cursors.Cursor.type ##
233-
234-
.. attribute:: data
235-
236-
| :sl:`get the cursor data`
237-
| :sg:`data -> tuple`
238-
239-
Returns the data that was used to create this cursor object, wrapped up in a tuple.
240-
241-
.. ## pygame.cursors.Cursor.data ##
242-
243-
.. versionaddedold:: 2.0.1
244-
245-
.. ## pygame.cursors.Cursor ##
246-
247-
.. ## pygame.cursors ##
10+
.. autopgclass:: Cursor
11+
:members: copy, type, data
24812

24913
Example code for creating and settings cursors. (Click the mouse to switch cursor)
25014

‎src_c/doc/cursors_doc.h‎

Lines changed: 7 additions & 7 deletions
Original file line numberDiff line numberDiff line change
@@ -1,8 +1,8 @@
11
/* Auto generated file: with make_docs.py . Docs go in docs/reST/ref/ . */
2-
#define DOC_CURSORS "pygame module for cursor resources"
3-
#define DOC_CURSORS_COMPILE "compile(strings, black='X', white='.', xor='o') -> data, mask\ncreate binary cursor data from simple strings"
4-
#define DOC_CURSORS_LOADXBM "load_xbm(cursorfile) -> cursor_args\nload_xbm(cursorfile, maskfile) -> cursor_args\nload cursor data from an XBM file"
5-
#define DOC_CURSORS_CURSOR "Cursor(size, hotspot, xormasks, andmasks) -> Cursor\nCursor(hotspot, surface) -> Cursor\nCursor(constant) -> Cursor\nCursor(Cursor) -> Cursor\nCursor() -> Cursor\npygame object representing a cursor"
6-
#define DOC_CURSORS_CURSOR_COPY "copy() -> Cursor\ncopy the current cursor"
7-
#define DOC_CURSORS_CURSOR_TYPE "type -> string\nget the cursor type"
8-
#define DOC_CURSORS_CURSOR_DATA "data -> tuple\nget the cursor data"
2+
#define DOC_CURSORS "Pygame module for cursor resources."
3+
#define DOC_CURSORS_COMPILE "compile(strings, black='X', white='.', xor='o') -> ...\nCreate binary cursor data from simple strings."
4+
#define DOC_CURSORS_LOADXBM "load_xbm(curs, mask) -> ...\nLoad cursor data from an XBM file."
5+
#define DOC_CURSORS_CURSOR "Cursor(constant=...) -> Cursor\nCursor(cursor) -> Cursor\nCursor(size, hotspot, xormasks, andmasks) -> Cursor\nCursor(hotspot, surface) -> Cursor\nPygame object representing a cursor."
6+
#define DOC_CURSORS_CURSOR_COPY "copy() -> Cursor\nCopy the current cursor."
7+
#define DOC_CURSORS_CURSOR_TYPE "type -> Literal['system', 'color', 'bitmap']\nGet the cursor type."
8+
#define DOC_CURSORS_CURSOR_DATA "data -> ...\nGet the cursor data."

0 commit comments

Comments
 (0)