diff --git a/docs/reST/ref/cursors.rst b/docs/reST/ref/cursors.rst index f7e92319e1..c1fcdb0b3b 100644 --- a/docs/reST/ref/cursors.rst +++ b/docs/reST/ref/cursors.rst @@ -138,6 +138,8 @@ The following strings can be converted into cursor bitmaps with | :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, @@ -174,6 +176,13 @@ The following strings can be converted into cursor bitmaps with 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``. @@ -199,6 +208,14 @@ The following strings can be converted into cursor bitmaps with 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 @@ -226,4 +243,4 @@ The following strings can be converted into cursor bitmaps with Example code for creating and settings cursors. (Click the mouse to switch cursor) -.. literalinclude:: code_examples/cursors_module_example.py \ No newline at end of file +.. literalinclude:: code_examples/cursors_module_example.py diff --git a/src_c/doc/cursors_doc.h b/src_c/doc/cursors_doc.h index 6934c4653f..b9cb0c1e55 100644 --- a/src_c/doc/cursors_doc.h +++ b/src_c/doc/cursors_doc.h @@ -2,7 +2,8 @@ #define DOC_PYGAMECURSORS "pygame module for cursor resources" #define DOC_PYGAMECURSORSCOMPILE "compile(strings, black='X', white='.', xor='o') -> data, mask\ncreate binary cursor data from simple strings" #define DOC_PYGAMECURSORSLOADXBM "load_xbm(cursorfile) -> cursor_args\nload_xbm(cursorfile, maskfile) -> cursor_args\nload cursor data from an XBM file" -#define DOC_PYGAMECURSORSCURSOR "Cursor(size, hotspot, xormasks, andmasks) -> Cursor\nCursor(hotspot, surface) -> Cursor\nCursor(constant) -> Cursor\npygame object representing a cursor" +#define DOC_PYGAMECURSORSCURSOR "Cursor(size, hotspot, xormasks, andmasks) -> Cursor\nCursor(hotspot, surface) -> Cursor\nCursor(constant) -> Cursor\nCursor(Cursor) -> Cursor\nCursor() -> Cursor\npygame object representing a cursor" +#define DOC_CURSORCOPY "" #define DOC_CURSORTYPE "type -> string\nGets the cursor type" #define DOC_CURSORDATA "data -> tuple\nGets the cursor data" @@ -27,8 +28,13 @@ pygame.cursors.Cursor Cursor(size, hotspot, xormasks, andmasks) -> Cursor Cursor(hotspot, surface) -> Cursor Cursor(constant) -> Cursor + Cursor(Cursor) -> Cursor + Cursor() -> Cursor pygame object representing a cursor +pygame.cursors.Cursor.copy + + pygame.cursors.Cursor.type type -> string Gets the cursor type diff --git a/src_py/cursors.py b/src_py/cursors.py index ae815dfca9..24268d9f99 100644 --- a/src_py/cursors.py +++ b/src_py/cursors.py @@ -28,7 +28,11 @@ arrow, diamond, ball, broken_x, tri_left, tri_right There is also a sample string cursor named 'thickarrow_strings'. -The compile() function can convert these string cursors into cursor byte data. +The compile() function can convert these string cursors into cursor byte data that can be used to +create Cursor objects. + +Alternately, you can also create Cursor objects using surfaces or cursors constants, +such as pygame.SYSTEM_CURSOR_ARROW. """ import pygame @@ -49,6 +53,18 @@ class Cursor(object): def __init__(self, *args): + """Cursor(size, hotspot, xormasks, andmasks) -> Cursor + Cursor(hotspot, Surface) -> Cursor + Cursor(constant) -> Cursor + Cursor(Cursor) -> copies the Cursor object passed as an argument + Cursor() -> Cursor + + pygame object for representing cursors + + You can initialize a cursor from a system cursor or use the constructor on an existing Cursor object, + which will copy it. + Providing a Surface instance will render the cursor displayed as that Surface when used. + Said Surfaces may use other colors than black and white.""" if len(args) == 0: self.type = "system" self.data = (pygame.SYSTEM_CURSOR_ARROW,) @@ -80,6 +96,13 @@ def __eq__(self, other): def __ne__(self, other): return not self.__eq__(other) + + def __copy__(self): + '''Clone the current Cursor object. + You can do the same thing by doing Cursor(Cursor).''' + return self.__class__(self) + + copy=__copy__ def __hash__(self): return hash(tuple([self.type] + list(self.data))) @@ -222,6 +245,7 @@ def get_cursor(): # Here is an example string resource cursor. To use this: # curs, mask = pygame.cursors.compile_cursor(pygame.cursors.thickarrow_strings, 'X', '.') # pygame.mouse.set_cursor((24, 24), (0, 0), curs, mask) +# Be warned, though, that cursors created from compiled strings do not support colors. # sized 24x24 thickarrow_strings = (