.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc



.. _wx.Cursor:

==========================================================================================================================================
|phoenix_title|  **wx.Cursor**
==========================================================================================================================================

A cursor is a small bitmap used for denoting where the mouse pointer is, with a picture that indicates the point of a mouse click. 
         

A cursor may be associated either with the given window (and all its children, unless any of them defines its own cursor) using :meth:`wx.Window.SetCursor` , or set globally using `wx.SetCursor`     . It is also common to temporarily change the cursor to a "busy cursor" indicating that some lengthy operation is in progress and :ref:`wx.BusyCursor`  can be used for this. 

Because a custom cursor of a fixed size would look either inappropriately big in standard resolution or too small in high resolution, :ref:`wx.CursorBundle`  class allows to define a set of cursors of different sizes, letting wxWidgets to automatically select the most appropriate one for the current resolution and user's preferred cursor size. Using this class with :meth:`wx.Window.SetCursorBundle`   is the recommended way to use custom cursors. 



|phoenix_title| Creating a Custom Cursor
========================================

The following is an example of creating a cursor from 32x32 bitmap data (down_bits) and a mask (down_mask) where 1 is black and 0 is white for the bits, and 1 is opaque and 0 is transparent for the mask. It works on Windows and GTK+. ::

        down_bits = [255, 255, 255, 255, 31,
                     255, 255, 255, 31, 255, 255, 255, 31, 255, 255, 255,
                     31, 255, 255, 255, 31, 255, 255, 255, 31, 255, 255,
                     255, 31, 255, 255, 255, 31, 255, 255, 255, 25, 243,
                     255, 255, 19, 249, 255, 255, 7, 252, 255, 255, 15, 254,
                     255, 255, 31, 255, 255, 255, 191, 255, 255, 255, 255,
                     255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
                     255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
                     255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
                     255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
                     255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
                     255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
                     255]

        down_mask = [240, 1, 0, 0, 240, 1,
                     0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 240, 1,
                     0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 255, 31, 0, 0, 255,
                     31, 0, 0, 254, 15, 0, 0, 252, 7, 0, 0, 248, 3, 0, 0,
                     240, 1, 0, 0, 224, 0, 0, 0, 64, 0, 0, 0, 0, 0, 0, 0, 0,
                     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                     0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
                     0, 0, 0, 0, 0]

        if wx.Platform == '__WXMSW__':

            down_bitmap = wx.BitmapFromBits(down_bits, 32, 32)
            down_mask_bitmap = wx.BitmapFromBits(down_mask, 32, 32)

            down_bitmap.SetMask(wx.Mask(down_mask_bitmap))
            down_image = down_bitmap.ConvertToImage()
            down_image.SetOption(wx.IMAGE_OPTION_CUR_HOTSPOT_X, 6)
            down_image.SetOption(wx.IMAGE_OPTION_CUR_HOTSPOT_Y, 14)
            down_cursor = wx.Cursor(down_image)

        elif wx.Platform == '__WXGTK__':

            down_cursor = wx.Cursor(down_bits, 32, 32, 6, 14,
                                    down_mask, wx.WHITE, wx.BLACK)





.. seealso:: :ref:`wx.Bitmap`, :ref:`wx.Icon`, :meth:`wx.Window.SetCursor` , `wx.SetCursor`     , :ref:`wx.StockCursor`    







|

|class_hierarchy| Class Hierarchy
=================================

.. raw:: html

   <div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
   <img id="toggleBlock-trigger" src="_static/images/closed.png"/>
   Inheritance diagram for class <strong>Cursor</strong>:
   </div>
   <div id="toggleBlock-summary" style="display:block;"></div>
   <div id="toggleBlock-content" style="display:none;">
   <p class="graphviz">
   <center><img src="_static/images/inheritance/wx.Cursor_inheritance.svg" alt="Inheritance diagram of Cursor" usemap="#dummy" class="inheritance"/></center>
   <script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
   <map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.Cursor.html" title="A cursor is a small bitmap used for denoting where the mouse pointer is, with a picture that indicates the point of a mouse click." alt="" coords="18,159,119,188"/> <area shape="rect" id="node2" href="wx.GDIObject.html" title="This class allows platforms to implement functionality to optimise GDI objects, such as wx.Pen, wx.Brush  and wx.Font." alt="" coords="5,82,132,111"/> <area shape="rect" id="node3" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="19,5,118,34"/> </map> 
   </p>
   </div>

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.Cursor.__init__`                                                      Default constructor.
:meth:`~wx.Cursor.GetHandle`                                                     Get the handle for the Cursor.  Windows only.
:meth:`~wx.Cursor.GetHotSpot`                                                    Returns the coordinates of the cursor hot spot.
:meth:`~wx.Cursor.IsOk`                                                          Returns ``True`` if cursor data is present.
:meth:`~wx.Cursor.SetHandle`                                                     Set the handle to use for this Cursor.  Windows only.
:meth:`~wx.Cursor.__bool__`                                                      
:meth:`~wx.Cursor.__nonzero__`                                                   
:meth:`~wx.Cursor._copyFrom`                                                     For internal use only.
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.Cursor.Handle`                                                        See :meth:`~wx.Cursor.GetHandle` and :meth:`~wx.Cursor.SetHandle`
:attr:`~wx.Cursor.HotSpot`                                                       See :meth:`~wx.Cursor.GetHotSpot`
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: wx.Cursor(GDIObject)

   **Possible constructors**::

       Cursor() -> None
       
       Cursor(bitmap, hotSpotX=0, hotSpotY=0) -> None
       
       Cursor(bitmap, hotSpot) -> None
       
       Cursor(cursorName, type=BITMAP_TYPE_ANY, hotSpotX=0, hotSpotY=0) -> None
       
       Cursor(name, type, hotSpot) -> None
       
       Cursor(cursorId) -> None
       
       Cursor(image) -> None
       
       Cursor(cursor) -> None
       
   
   A cursor is a small bitmap used for denoting where the mouse pointer
   is, with a picture that indicates the point of a mouse click.



   .. method:: __init__(self, *args, **kw)



      |overload| **Overloaded Implementations:**

      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self)`
      
      Default constructor. 
                       
      
      :rtype: `None`     
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, bitmap, hotSpotX=0, hotSpotY=0)`
      
      Constructs a cursor from the provided bitmap and hotspot position. 
                       
      
      
      
      
      :param `bitmap`: The bitmap to use for the cursor, should be valid.   
      :type `bitmap`: wx.Bitmap
      :param `hotSpotX`: Hotspot x coordinate (relative to the top left of the image).   
      :type `hotSpotX`: int
      :param `hotSpotY`: Hotspot y coordinate (relative to the top left of the image).  
      :type `hotSpotY`: int
      
      
      
      
      
      
      
      
      
      
      :rtype: `None`     
      
      
      
      
                        
      
      
      
      .. versionadded:: 4.3/wxWidgets-3.3.0  
           
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, bitmap, hotSpot)`
      
      This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. 
                       
      
      
                      
      
      
      :param `bitmap`: 
      :type `bitmap`: wx.Bitmap
      :param `hotSpot`: 
      :type `hotSpot`: wx.Point
      
      
      
      
      :rtype: `None`     
      
      
      
      
      
      
      
      .. versionadded:: 4.3/wxWidgets-3.3.0  
           
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, cursorName, type=BITMAP_TYPE_ANY, hotSpotX=0, hotSpotY=0)`
      
      Constructs a cursor by passing a string resource name or filename. 
                       
      
      The arguments `hotSpotX`  and `hotSpotY`  are only used when there's no hotspot info in the resource/image-file to load (e.g. when using  ``BITMAP_TYPE_ICO``   under wxMSW or   ``BITMAP_TYPE_XPM``   under wxGTK). 
      
      
      
      
      :param `cursorName`: The name of the resource or the image file to load.   
      :type `cursorName`: string
      :param `type`: Icon type to load. It defaults to  ``CURSOR_DEFAULT_TYPE`` , which is a #define associated to different values on different platforms:
      
       - under Windows, it defaults to  ``BITMAP_TYPE_CUR_RESOURCE`` . Other permitted types under Windows are   ``BITMAP_TYPE_CUR``   (to load a cursor from a .cur cursor file),   ``BITMAP_TYPE_ICO``   (to load a cursor from a .ico icon file) and   ``BITMAP_TYPE_ANI``   (to load a cursor from a .ani icon file). 
       - under MacOS, it defaults to  ``BITMAP_TYPE_MACCURSOR_RESOURCE`` ; when specifying a string resource name, first a ``PNG`` and then a ``CUR`` image is searched in resources. 
       - under GTK, it defaults to  ``BITMAP_TYPE_XPM`` . See the  :ref:`wx.Cursor`  constructor for more info. 
       - under X11, it defaults to  ``BITMAP_TYPE_XPM`` .   
      
       
      
      :type `type`: wx.BitmapType
      :param `hotSpotX`: Hotspot x coordinate (relative to the top left of the image).   
      :type `hotSpotX`: int
      :param `hotSpotY`: Hotspot y coordinate (relative to the top left of the image).   
      :type `hotSpotY`: int
      
      
      
      
      
      
      
      
      
      
      
      
      :rtype: `None`     
      
      
      
      
                        
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, name, type, hotSpot)`
      
      This is an overloaded member function, provided for convenience. It differs from the above function only in what argument(s) it accepts. 
                       
      
      
                      
      
      
      :param `name`: 
      :type `name`: string
      :param `type`: 
      :type `type`: wx.BitmapType
      :param `hotSpot`: 
      :type `hotSpot`: wx.Point
      
      
      
      
      :rtype: `None`     
      
      
      
      
      
      
      
      .. versionadded:: 4.3/wxWidgets-3.3.0  
           
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, cursorId)`
      
      Constructs a cursor using a cursor identifier. 
                       
      
      
      
      
      :param `cursorId`: A stock cursor identifier. See :ref:`wx.StockCursor`.   
      :type `cursorId`: wx.StockCursor
      
      
      
      
      
      
      :rtype: `None`     
      
      
      
      
                        
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, image)`
      
      Constructs a cursor from a :ref:`wx.Image`. 
                       
      
      If cursor are monochrome on the current platform, colors with the ``RGB`` elements all greater than 127 will be foreground, colors less than this background. The mask (if any) will be used to specify the transparent area. 
      
      In wxMSW the foreground will be white and the background black. If the cursor is larger than 32x32 it is resized. 
      
      In wxGTK, colour cursors and alpha channel are supported (starting from GTK+ 2.2). Otherwise the two most frequent colors will be used for foreground and background. In any case, the cursor will be displayed at the size of the image. 
      
      Under Mac (Cocoa), large cursors are supported. 
      
      Notice that the `image`  can define the cursor hot spot. To set it you need to use :meth:`wx.Image.SetOption`   with  ``IMAGE_OPTION_CUR_HOTSPOT_X``   or   ``IMAGE_OPTION_CUR_HOTSPOT_Y`` , e.g.  ::
      
                      image.SetOption(wx.IMAGE_OPTION_CUR_HOTSPOT_X, hotSpotX)
                      image.SetOption(wx.IMAGE_OPTION_CUR_HOTSPOT_X, hotSpotY)
      
      
                       
      
      
      :param `image`: 
      :type `image`: wx.Image
      
      
      
      
      :rtype: `None`     
      
      
      
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, cursor)`
      
      Copy constructor, uses :ref:`reference counting <reference counting>`. 
                       
      
      
      
      
      :param `cursor`: Pointer or reference to a cursor to copy.   
      :type `cursor`: wx.Cursor
      
      
      
      
      
      
      :rtype: `None`     
      
      
      
      
                        
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: GetHandle(self)

      Get the handle for the Cursor.  Windows only. 

      :rtype: `int`








   .. method:: GetHotSpot(self)

      Returns the coordinates of the cursor hot spot. 
                 

      The hot spot is the point at which the mouse is actually considered to be when this cursor is used. 

      This method is currently implemented in wxMSW, wxGTK and wxOSX (since wxWidgets 3.3.0) and returns `wx.DefaultPosition`       in the other ports. 


                

      :rtype: :ref:`wx.Point`







      .. versionadded:: 4.1/wxWidgets-3.1.0  
     








   .. method:: IsOk(self)

      Returns ``True`` if cursor data is present. 
                 

      :rtype: `bool`








   .. method:: SetHandle(self, handle)

      Set the handle to use for this Cursor.  Windows only. 

      :rtype: `None`     








   .. method:: __bool__(self)



      :rtype: `bool`








   .. method:: __nonzero__(self)



      :rtype: `bool`








   .. method:: _copyFrom(self, other)

      For internal use only. 

      :rtype: `None`     








   .. attribute:: Handle

      See :meth:`~wx.Cursor.GetHandle` and :meth:`~wx.Cursor.SetHandle`


   .. attribute:: HotSpot

      See :meth:`~wx.Cursor.GetHotSpot`

