From c12a4ba07087ce679a19f11cf1d2f94637e1a5a8 Mon Sep 17 00:00:00 2001 From: fortwoone <74463377+fortwoone@users.noreply.github.com> Date: Thu, 9 Sep 2021 17:29:34 +0200 Subject: [PATCH 01/11] Added doc for Cursor object --- src_py/cursors.py | 14 ++++++++++++++ 1 file changed, 14 insertions(+) diff --git a/src_py/cursors.py b/src_py/cursors.py index ae815dfca9..46e8db1738 100644 --- a/src_py/cursors.py +++ b/src_py/cursors.py @@ -29,6 +29,8 @@ There is also a sample string cursor named 'thickarrow_strings'. The compile() function can convert these string cursors into cursor byte data. + +Alternately, you can also use Cursor objects to use colored images ingame. """ import pygame @@ -49,6 +51,17 @@ class Cursor(object): def __init__(self, *args): + """Cursor()->Cursor + Cursor(constant)->Cursor + Cursor(Cursor)->copies the Cursor object passed as an argument + Cursor(hotspot, Surface)->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 transform the cursor image into the Surface. + Said Surfaces may use other colors than black and white.""" if len(args) == 0: self.type = "system" self.data = (pygame.SYSTEM_CURSOR_ARROW,) @@ -222,6 +235,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 = ( From ec2fc72317dd6ce11980b240ca01ff720194696c Mon Sep 17 00:00:00 2001 From: fortwoone <74463377+fortwoone@users.noreply.github.com> Date: Fri, 10 Sep 2021 17:19:25 +0200 Subject: [PATCH 02/11] Tweaked the Cursor doc I also added a copy method in case someone wants to duplicate the cursor (even though I assume that would be very rare but still useful) --- src_py/cursors.py | 14 ++++++++++---- 1 file changed, 10 insertions(+), 4 deletions(-) diff --git a/src_py/cursors.py b/src_py/cursors.py index 46e8db1738..41bc7e9319 100644 --- a/src_py/cursors.py +++ b/src_py/cursors.py @@ -51,10 +51,11 @@ class Cursor(object): def __init__(self, *args): - """Cursor()->Cursor - Cursor(constant)->Cursor - Cursor(Cursor)->copies the Cursor object passed as an argument - Cursor(hotspot, Surface)->Cursor + """Cursor() -> Cursor + Cursor(constant) -> Cursor + Cursor(Cursor) -> copies the Cursor object passed as an argument + Cursor(hotspot, Surface) -> Cursor + Cursor(size, hotspot, xormasks, andmasks) -> Cursor pygame object for representing cursors @@ -93,6 +94,11 @@ def __eq__(self, other): def __ne__(self, other): return not self.__eq__(other) + + def __copy__(self): + return self.__class__(self) + + copy=__copy__ def __hash__(self): return hash(tuple([self.type] + list(self.data))) From 8ae7ae4bf687c72c73dff5cf686982cb08d51368 Mon Sep 17 00:00:00 2001 From: fortwoone <74463377+fortwoone@users.noreply.github.com> Date: Fri, 10 Sep 2021 17:26:24 +0200 Subject: [PATCH 03/11] Updated cursors.rst Matched the docstrings in cursors.py plus some extra info I noticed while reading the code --- docs/reST/ref/cursors.rst | 10 +++++++++- 1 file changed, 9 insertions(+), 1 deletion(-) diff --git a/docs/reST/ref/cursors.rst b/docs/reST/ref/cursors.rst index f7e92319e1..cc85ed306f 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) -> copies the Cursor object as a parameter` + | :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,12 @@ 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 this call 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``. @@ -226,4 +234,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 From 30098e030294b8888d6121496cc45e6717db828d Mon Sep 17 00:00:00 2001 From: fortwoone <74463377+fortwoone@users.noreply.github.com> Date: Fri, 17 Sep 2021 17:39:29 +0200 Subject: [PATCH 04/11] Finished changes requested by Starbucks5 --- src_py/cursors.py | 13 +++++++------ 1 file changed, 7 insertions(+), 6 deletions(-) diff --git a/src_py/cursors.py b/src_py/cursors.py index 41bc7e9319..b49e74b80a 100644 --- a/src_py/cursors.py +++ b/src_py/cursors.py @@ -28,9 +28,8 @@ 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. - -Alternately, you can also use Cursor objects to use colored images ingame. +The compile() function can convert these string cursors into cursor byte data that can be used to +create Cursor objects (which can also be instantiated from surfaces). """ import pygame @@ -51,11 +50,11 @@ class Cursor(object): def __init__(self, *args): - """Cursor() -> Cursor + """Cursor(size, hotspot, xormasks, andmasks) -> Cursor + Cursor(hotspot, Surface) -> Cursor Cursor(constant) -> Cursor Cursor(Cursor) -> copies the Cursor object passed as an argument - Cursor(hotspot, Surface) -> Cursor - Cursor(size, hotspot, xormasks, andmasks) -> Cursor + Cursor() -> Cursor pygame object for representing cursors @@ -96,6 +95,8 @@ 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__ From c2a9837c0cf3476e0416ea5ed7241966be683726 Mon Sep 17 00:00:00 2001 From: fortwoone <74463377+fortwoone@users.noreply.github.com> Date: Sat, 18 Sep 2021 12:45:21 +0200 Subject: [PATCH 05/11] Added Cursor.copy to the docs --- docs/reST/ref/cursors.rst | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) diff --git a/docs/reST/ref/cursors.rst b/docs/reST/ref/cursors.rst index cc85ed306f..c166f12660 100644 --- a/docs/reST/ref/cursors.rst +++ b/docs/reST/ref/cursors.rst @@ -138,7 +138,7 @@ 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) -> copies the Cursor object as a parameter` + | :sg:`Cursor(Cursor) -> Cursor` | :sg:`Cursor() -> Cursor` In pygame 2, there are 3 types of cursors you can create to give your @@ -207,6 +207,12 @@ 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. + + **Copying a Cursor** + + There are two ways of copying a Cursor object : + - you can use the Cursor constructor on the existing object ; + - oy you can also call Cursor.copy . .. attribute:: type From 48a6d55f0b0eb597add338cd14fa4f590aec3d36 Mon Sep 17 00:00:00 2001 From: fortwoone <74463377+fortwoone@users.noreply.github.com> Date: Sun, 19 Sep 2021 11:29:16 +0200 Subject: [PATCH 06/11] Display Cursor.copy in the doc as a method --- docs/reST/ref/cursors.rst | 10 ++++++---- 1 file changed, 6 insertions(+), 4 deletions(-) diff --git a/docs/reST/ref/cursors.rst b/docs/reST/ref/cursors.rst index c166f12660..9e583366fc 100644 --- a/docs/reST/ref/cursors.rst +++ b/docs/reST/ref/cursors.rst @@ -208,11 +208,13 @@ 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. - **Copying a Cursor** + .. 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 ## - There are two ways of copying a Cursor object : - - you can use the Cursor constructor on the existing object ; - - oy you can also call Cursor.copy . .. attribute:: type From 77199f0d65354da4fadc8c8e10e7acf92ab5b191 Mon Sep 17 00:00:00 2001 From: fortwoone <74463377+fortwoone@users.noreply.github.com> Date: Sun, 19 Sep 2021 11:29:39 +0200 Subject: [PATCH 07/11] Correction of cursors.py docstring --- src_py/cursors.py | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/src_py/cursors.py b/src_py/cursors.py index b49e74b80a..b641c69e6d 100644 --- a/src_py/cursors.py +++ b/src_py/cursors.py @@ -60,7 +60,7 @@ def __init__(self, *args): 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 transform the cursor image into the Surface. + 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" From 932cb00ed1759a691de755601a5aabaaac5016fd Mon Sep 17 00:00:00 2001 From: fortwoone <74463377+fortwoone@users.noreply.github.com> Date: Tue, 28 Sep 2021 19:11:15 +0200 Subject: [PATCH 08/11] Correction of cursors RST docs --- docs/reST/ref/cursors.rst | 7 ++++--- 1 file changed, 4 insertions(+), 3 deletions(-) diff --git a/docs/reST/ref/cursors.rst b/docs/reST/ref/cursors.rst index 9e583366fc..cf018e81f3 100644 --- a/docs/reST/ref/cursors.rst +++ b/docs/reST/ref/cursors.rst @@ -179,8 +179,9 @@ The following strings can be converted into cursor bitmaps with **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 this call actually creates a system cursor using the default native image. + 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 thoses calls actually creates a system cursor using the default native image. **Creating a color cursor** @@ -208,7 +209,7 @@ 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 + .. method:: copy | :sl:`copy the current cursor` | :sg:`copy() -> Cursor` From 27181f15906e6d6ca32ce7c8c1a446c70aa74b81 Mon Sep 17 00:00:00 2001 From: fortwoone <74463377+fortwoone@users.noreply.github.com> Date: Tue, 28 Sep 2021 19:15:14 +0200 Subject: [PATCH 09/11] Attempt to make the docs clearer --- src_py/cursors.py | 5 ++++- 1 file changed, 4 insertions(+), 1 deletion(-) diff --git a/src_py/cursors.py b/src_py/cursors.py index b641c69e6d..24268d9f99 100644 --- a/src_py/cursors.py +++ b/src_py/cursors.py @@ -29,7 +29,10 @@ There is also a sample string cursor named 'thickarrow_strings'. The compile() function can convert these string cursors into cursor byte data that can be used to -create Cursor objects (which can also be instantiated from surfaces). +create Cursor objects. + +Alternately, you can also create Cursor objects using surfaces or cursors constants, +such as pygame.SYSTEM_CURSOR_ARROW. """ import pygame From 21f08e55f81faaec80cdbb9d40afc97c5c292375 Mon Sep 17 00:00:00 2001 From: fortwoone <74463377+fortwoone@users.noreply.github.com> Date: Mon, 18 Oct 2021 18:50:31 +0200 Subject: [PATCH 10/11] Corrected "thoses" typo --- docs/reST/ref/cursors.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/docs/reST/ref/cursors.rst b/docs/reST/ref/cursors.rst index cf018e81f3..c1fcdb0b3b 100644 --- a/docs/reST/ref/cursors.rst +++ b/docs/reST/ref/cursors.rst @@ -181,7 +181,7 @@ The following strings can be converted into cursor bitmaps with 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 thoses calls actually creates a system cursor using the default native image. + Doing one of those calls actually creates a system cursor using the default native image. **Creating a color cursor** From 72d0956f66c87b298a9a27090d7e515b701e7177 Mon Sep 17 00:00:00 2001 From: =?UTF-8?q?Ren=C3=A9=20Dudfield?= Date: Sat, 23 Oct 2021 17:56:39 +0200 Subject: [PATCH 11/11] doc: Generate src_c/doc/cursors_doc.h --- src_c/doc/cursors_doc.h | 8 +++++++- 1 file changed, 7 insertions(+), 1 deletion(-) 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