251 lines
9.2 KiB
ReStructuredText
251 lines
9.2 KiB
ReStructuredText
.. include:: common.txt
|
|
|
|
:mod:`pygame.cursors`
|
|
=====================
|
|
|
|
.. module:: pygame.cursors
|
|
:synopsis: pygame module for cursor resources
|
|
|
|
| :sl:`pygame module for cursor resources`
|
|
|
|
Pygame offers control over the system hardware cursor. Pygame supports
|
|
black and white cursors (bitmap cursors), as well as system variant cursors and color cursors.
|
|
You control the cursor with functions inside :mod:`pygame.mouse`.
|
|
|
|
This cursors module contains functions for loading and decoding various
|
|
cursor formats. These allow you to easily store your cursors in external files
|
|
or directly as encoded python strings.
|
|
|
|
The module includes several standard cursors. The :func:`pygame.mouse.set_cursor()`
|
|
function takes several arguments. All those arguments have been stored in a
|
|
single tuple you can call like this:
|
|
|
|
::
|
|
|
|
>>> pygame.mouse.set_cursor(*pygame.cursors.arrow)
|
|
|
|
The following variables can be passed to ``pygame.mouse.set_cursor`` function:
|
|
|
|
* ``pygame.cursors.arrow``
|
|
|
|
* ``pygame.cursors.diamond``
|
|
|
|
* ``pygame.cursors.broken_x``
|
|
|
|
* ``pygame.cursors.tri_left``
|
|
|
|
* ``pygame.cursors.tri_right``
|
|
|
|
This module also contains a few cursors as formatted strings. You'll need to
|
|
pass these to ``pygame.cursors.compile()`` function before you can use them.
|
|
The example call would look like this:
|
|
|
|
::
|
|
|
|
>>> cursor = pygame.cursors.compile(pygame.cursors.textmarker_strings)
|
|
>>> pygame.mouse.set_cursor((8, 16), (0, 0), *cursor)
|
|
|
|
The following strings can be converted into cursor bitmaps with
|
|
``pygame.cursors.compile()`` :
|
|
|
|
* ``pygame.cursors.thickarrow_strings``
|
|
|
|
* ``pygame.cursors.sizer_x_strings``
|
|
|
|
* ``pygame.cursors.sizer_y_strings``
|
|
|
|
* ``pygame.cursors.sizer_xy_strings``
|
|
|
|
* ``pygame.cursor.textmarker_strings``
|
|
|
|
.. function:: compile
|
|
|
|
| :sl:`create binary cursor data from simple strings`
|
|
| :sg:`compile(strings, black='X', white='.', xor='o') -> data, mask`
|
|
|
|
A sequence of strings can be used to create binary cursor data for the
|
|
system cursor. This returns the binary data in the form of two tuples.
|
|
Those can be passed as the third and fourth arguments respectively of the
|
|
:func:`pygame.mouse.set_cursor()` function.
|
|
|
|
If you are creating your own cursor strings, you can use any value represent
|
|
the black and white pixels. Some system allow you to set a special toggle
|
|
color for the system color, this is also called the xor color. If the system
|
|
does not support xor cursors, that color will simply be black.
|
|
|
|
The height must be divisible by 8. The width of the strings must all be equal
|
|
and be divisible by 8. If these two conditions are not met, ``ValueError`` is
|
|
raised.
|
|
An example set of cursor strings looks like this
|
|
|
|
::
|
|
|
|
thickarrow_strings = ( #sized 24x24
|
|
"XX ",
|
|
"XXX ",
|
|
"XXXX ",
|
|
"XX.XX ",
|
|
"XX..XX ",
|
|
"XX...XX ",
|
|
"XX....XX ",
|
|
"XX.....XX ",
|
|
"XX......XX ",
|
|
"XX.......XX ",
|
|
"XX........XX ",
|
|
"XX........XXX ",
|
|
"XX......XXXXX ",
|
|
"XX.XXX..XX ",
|
|
"XXXX XX..XX ",
|
|
"XX XX..XX ",
|
|
" XX..XX ",
|
|
" XX..XX ",
|
|
" XX..XX ",
|
|
" XXXX ",
|
|
" XX ",
|
|
" ",
|
|
" ",
|
|
" ")
|
|
|
|
.. ## pygame.cursors.compile ##
|
|
|
|
.. function:: load_xbm
|
|
|
|
| :sl:`load cursor data from an XBM file`
|
|
| :sg:`load_xbm(cursorfile) -> cursor_args`
|
|
| :sg:`load_xbm(cursorfile, maskfile) -> cursor_args`
|
|
|
|
This loads cursors for a simple subset of ``XBM`` files. ``XBM`` files are
|
|
traditionally used to store cursors on UNIX systems, they are an ASCII
|
|
format used to represent simple images.
|
|
|
|
Sometimes the black and white color values will be split into two separate
|
|
``XBM`` files. You can pass a second maskfile argument to load the two
|
|
images into a single cursor.
|
|
|
|
The cursorfile and maskfile arguments can either be filenames or file-like
|
|
object with the readlines method.
|
|
|
|
The return value cursor_args can be passed directly to the
|
|
``pygame.mouse.set_cursor()`` function.
|
|
|
|
.. ## pygame.cursors.load_xbm ##
|
|
|
|
|
|
|
|
.. class:: Cursor
|
|
|
|
| :sl:`pygame object representing a cursor`
|
|
| :sg:`Cursor(size, hotspot, xormasks, andmasks) -> Cursor`
|
|
| :sg:`Cursor(hotspot, surface) -> Cursor`
|
|
| :sg:`Cursor(constant) -> Cursor`
|
|
| :sg:`Cursor(Cursor) -> Cursor`
|
|
| :sg:`Cursor() -> Cursor`
|
|
|
|
In pygame 2, there are 3 types of cursors you can create to give your
|
|
game that little bit of extra polish. There's **bitmap** type cursors,
|
|
which existed in pygame 1.x, and are compiled from a string or load from an xbm file.
|
|
Then there are **system** type cursors, where you choose a preset that will
|
|
convey the same meaning but look native across different operating systems.
|
|
Finally you can create a **color** cursor, which displays a pygame surface as the cursor.
|
|
|
|
**Creating a system cursor**
|
|
|
|
Choose a constant from this list, pass it into ``pygame.cursors.Cursor(constant)``,
|
|
and you're good to go. Be advised that not all systems support every system
|
|
cursor, and you may get a substitution instead. For example, on MacOS,
|
|
WAIT/WAITARROW should show up as an arrow, and SIZENWSE/SIZENESW/SIZEALL
|
|
should show up as a closed hand. And on Wayland, every SIZE cursor should
|
|
show up as a hand.
|
|
|
|
::
|
|
|
|
Pygame Cursor Constant Description
|
|
--------------------------------------------
|
|
pygame.SYSTEM_CURSOR_ARROW arrow
|
|
pygame.SYSTEM_CURSOR_IBEAM i-beam
|
|
pygame.SYSTEM_CURSOR_WAIT wait
|
|
pygame.SYSTEM_CURSOR_CROSSHAIR crosshair
|
|
pygame.SYSTEM_CURSOR_WAITARROW small wait cursor
|
|
(or wait if not available)
|
|
pygame.SYSTEM_CURSOR_SIZENWSE double arrow pointing
|
|
northwest and southeast
|
|
pygame.SYSTEM_CURSOR_SIZENESW double arrow pointing
|
|
northeast and southwest
|
|
pygame.SYSTEM_CURSOR_SIZEWE double arrow pointing
|
|
west and east
|
|
pygame.SYSTEM_CURSOR_SIZENS double arrow pointing
|
|
north and south
|
|
pygame.SYSTEM_CURSOR_SIZEALL four pointed arrow pointing
|
|
north, south, east, and west
|
|
pygame.SYSTEM_CURSOR_NO slashed circle or crossbones
|
|
pygame.SYSTEM_CURSOR_HAND hand
|
|
|
|
**Creating a cursor without passing arguments**
|
|
|
|
In addition to the cursor constants available and described above,
|
|
you can also call ``pygame.cursors.Cursor()``, and your cursor is ready (doing that is the same as
|
|
calling ``pygame.cursors.Cursor(pygame.SYSTEM_CURSOR_ARROW)``.
|
|
Doing one of those calls actually creates a system cursor using the default native image.
|
|
|
|
**Creating a color cursor**
|
|
|
|
To create a color cursor, create a ``Cursor`` from a ``hotspot`` and a ``surface``.
|
|
``hotspot`` is an (x,y) coordinate that determines where in the cursor the exact point is.
|
|
The hotspot position must be within the bounds of the ``surface``.
|
|
|
|
**Creating a bitmap cursor**
|
|
|
|
When the mouse cursor is visible, it will be displayed as a black and white
|
|
bitmap using the given bitmask arrays. The ``size`` is a sequence containing
|
|
the cursor width and height. ``hotspot`` is a sequence containing the cursor
|
|
hotspot position.
|
|
|
|
A cursor has a width and height, but a mouse position is represented by a
|
|
set of point coordinates. So the value passed into the cursor ``hotspot``
|
|
variable helps pygame to actually determine at what exact point the cursor
|
|
is at.
|
|
|
|
``xormasks`` is a sequence of bytes containing the cursor xor data masks.
|
|
Lastly ``andmasks``, a sequence of bytes containing the cursor bitmask data.
|
|
To create these variables, we can make use of the
|
|
:func:`pygame.cursors.compile()` function.
|
|
|
|
Width and height must be a multiple of 8, and the mask arrays must be the
|
|
correct size for the given width and height. Otherwise an exception is raised.
|
|
|
|
.. method:: copy
|
|
| :sl:`copy the current cursor`
|
|
| :sg:`copy() -> Cursor`
|
|
|
|
Returns a new Cursor object with the same data and hotspot as the original.
|
|
.. ## pygame.cursors.Cursor.copy ##
|
|
|
|
|
|
.. attribute:: type
|
|
|
|
| :sl:`Gets the cursor type`
|
|
| :sg:`type -> string`
|
|
|
|
The type will be ``"system"``, ``"bitmap"``, or ``"color"``.
|
|
|
|
.. ## pygame.cursors.Cursor.type ##
|
|
|
|
.. attribute:: data
|
|
|
|
| :sl:`Gets the cursor data`
|
|
| :sg:`data -> tuple`
|
|
|
|
Returns the data that was used to create this cursor object, wrapped up in a tuple.
|
|
|
|
.. ## pygame.cursors.Cursor.data ##
|
|
|
|
.. versionadded:: 2.0.1
|
|
|
|
.. ## pygame.cursors.Cursor ##
|
|
|
|
.. ## pygame.cursors ##
|
|
|
|
Example code for creating and settings cursors. (Click the mouse to switch cursor)
|
|
|
|
.. literalinclude:: code_examples/cursors_module_example.py
|