Merge pull request #2788 from pygame/fortwoone-docs

Continue on Cursor docs

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
+.. literalinclude:: code_examples/cursors_module_example.py

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

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 = (