1\section{\class{wxCursor}}\label{wxcursor} 2 3A cursor is a small bitmap usually used for denoting where the mouse 4pointer is, with a picture that might indicate the interpretation of a 5mouse click. As with icons, cursors in X and MS Windows are created 6in a different manner. Therefore, separate cursors will be created for the 7different environments. Platform-specific methods for creating a {\bf 8wxCursor} object are catered for, and this is an occasion where 9conditional compilation will probably be required (see \helpref{wxIcon}{wxicon} for 10an example). 11 12A single cursor object may be used in many windows (any subwindow type). 13The wxWidgets convention is to set the cursor for a window, as in X, 14rather than to set it globally as in MS Windows, although a 15global \helpref{::wxSetCursor}{wxsetcursor} is also available for MS Windows use. 16 17\wxheading{Derived from} 18 19\helpref{wxBitmap}{wxbitmap}\\ 20\helpref{wxGDIObject}{wxgdiobject}\\ 21\helpref{wxObject}{wxobject} 22 23\wxheading{Include files} 24 25<wx/cursor.h> 26 27\wxheading{Predefined objects} 28 29Objects: 30 31{\bf wxNullCursor} 32 33Pointers: 34 35{\bf wxSTANDARD\_CURSOR\\ 36wxHOURGLASS\_CURSOR\\ 37wxCROSS\_CURSOR} 38 39\wxheading{See also} 40 41\helpref{wxBitmap}{wxbitmap}, \helpref{wxIcon}{wxicon}, \helpref{wxWindow::SetCursor}{wxwindowsetcursor},\rtfsp 42\helpref{::wxSetCursor}{wxsetcursor} 43 44\latexignore{\rtfignore{\wxheading{Members}}} 45 46\membersection{wxCursor::wxCursor}\label{wxcursorctor} 47 48\func{}{wxCursor}{\void} 49 50Default constructor. 51 52\func{}{wxCursor}{\param{const char}{ bits[]}, \param{int }{width}, 53 \param{int }{ height}, \param{int }{hotSpotX=-1}, \param{int }{hotSpotY=-1}, \param{const char }{maskBits[]=NULL}, 54 \param{wxColour*}{ fg=NULL}, \param{wxColour*}{ bg=NULL}} 55 56Constructs a cursor by passing an array of bits (Motif and GTK+ only). {\it maskBits} is used only under 57Motif and GTK+. The parameters {\it fg} and {\it bg} are only present on GTK+, and force the 58cursor to use particular background and foreground colours. 59 60If either {\it hotSpotX} or {\it hotSpotY} is -1, the hotspot will be the centre of the cursor image (Motif only). 61 62\func{}{wxCursor}{\param{const wxString\& }{cursorName}, \param{long }{type}, \param{int }{hotSpotX=0}, \param{int }{hotSpotY=0}} 63 64Constructs a cursor by passing a string resource name or filename. 65 66On MacOS when specifying a string resource name, first the color cursors 'crsr' and then the black/white cursors 'CURS' in the resource chain are scanned through. 67 68{\it hotSpotX} and {\it hotSpotY} are currently only used under Windows when loading from an 69icon file, to specify the cursor hotspot relative to the top left of the image. 70 71\func{}{wxCursor}{\param{int}{ cursorId}} 72 73Constructs a cursor using a cursor identifier. 74 75\func{}{wxCursor}{\param{const wxImage\&}{ image}} 76 77Constructs a cursor from a wxImage. If the cursor is monochrome on the current 78platform, colors with the RGB elements all greater than 127 will be foreground, 79colors less than this will be background. The mask (if any) will be used to specify the 80transparent area. 81 82In wxMSW the foreground will be white and the background black. If the cursor 83is larger than 32x32 it is resized. 84 85In wxGTK, colour cursors and alpha channel are supported (starting from GTK+ 862.2). Otherwise the two most frequent colors will be used for foreground and 87background. In any case, the cursor will be displayed at the size of the image. 88 89In wxMac, if the cursor is larger than 16x16 it is resized and currently only 90shown as black/white (mask respected). 91 92\func{}{wxCursor}{\param{const wxCursor\&}{ cursor}} 93 94Copy constructor, uses \helpref{reference counting}{trefcount}. 95 96\wxheading{Parameters} 97 98\docparam{bits}{An array of bits.} 99 100\docparam{maskBits}{Bits for a mask bitmap.} 101 102\docparam{width}{Cursor width.} 103 104\docparam{height}{Cursor height.} 105 106\docparam{hotSpotX}{Hotspot x coordinate.} 107 108\docparam{hotSpotY}{Hotspot y coordinate.} 109 110\docparam{type}{Icon type to load. Under Motif, {\it type} defaults to {\bf wxBITMAP\_TYPE\_XBM}. Under Windows, 111it defaults to {\bf wxBITMAP\_TYPE\_CUR\_RESOURCE}. Under MacOS, it defaults to {\bf wxBITMAP\_TYPE\_MACCURSOR\_RESOURCE}. 112 113Under X, the permitted cursor types are: 114 115\twocolwidtha{6cm} 116\begin{twocollist}\itemsep=0pt 117\twocolitem{\windowstyle{wxBITMAP\_TYPE\_XBM}}{Load an X bitmap file.} 118\end{twocollist} 119 120Under Windows, the permitted types are: 121 122\twocolwidtha{6cm} 123\begin{twocollist}\itemsep=0pt 124\twocolitem{\windowstyle{wxBITMAP\_TYPE\_CUR}}{Load a cursor from a .cur cursor file (only if USE\_RESOURCE\_LOADING\_IN\_MSW 125is enabled in setup.h).} 126\twocolitem{\windowstyle{wxBITMAP\_TYPE\_CUR\_RESOURCE}}{Load a Windows resource (as specified in the .rc file).} 127\twocolitem{\windowstyle{wxBITMAP\_TYPE\_ICO}}{Load a cursor from a .ico icon file (only if USE\_RESOURCE\_LOADING\_IN\_MSW 128is enabled in setup.h). Specify {\it hotSpotX} and {\it hotSpotY}.} 129\end{twocollist}} 130 131\docparam{cursorId}{A stock cursor identifier. May be one of: 132 133\twocolwidtha{6cm} 134\begin{twocollist}\itemsep=0pt 135\twocolitem{{\bf wxCURSOR\_ARROW}}{A standard arrow cursor.} 136\twocolitem{{\bf wxCURSOR\_RIGHT\_ARROW}}{A standard arrow cursor 137pointing to the right.} 138\twocolitem{{\bf wxCURSOR\_BLANK}}{Transparent cursor.} 139\twocolitem{{\bf wxCURSOR\_BULLSEYE}}{Bullseye cursor.} 140\twocolitem{{\bf wxCURSOR\_CHAR}}{Rectangular character cursor.} 141\twocolitem{{\bf wxCURSOR\_CROSS}}{A cross cursor.} 142\twocolitem{{\bf wxCURSOR\_HAND}}{A hand cursor.} 143\twocolitem{{\bf wxCURSOR\_IBEAM}}{An I-beam cursor (vertical line).} 144\twocolitem{{\bf wxCURSOR\_LEFT\_BUTTON}}{Represents a mouse with the left button depressed.} 145\twocolitem{{\bf wxCURSOR\_MAGNIFIER}}{A magnifier icon.} 146\twocolitem{{\bf wxCURSOR\_MIDDLE\_BUTTON}}{Represents a mouse with the middle button depressed.} 147\twocolitem{{\bf wxCURSOR\_NO\_ENTRY}}{A no-entry sign cursor.} 148\twocolitem{{\bf wxCURSOR\_PAINT\_BRUSH}}{A paintbrush cursor.} 149\twocolitem{{\bf wxCURSOR\_PENCIL}}{A pencil cursor.} 150\twocolitem{{\bf wxCURSOR\_POINT\_LEFT}}{A cursor that points left.} 151\twocolitem{{\bf wxCURSOR\_POINT\_RIGHT}}{A cursor that points right.} 152\twocolitem{{\bf wxCURSOR\_QUESTION\_ARROW}}{An arrow and question mark.} 153\twocolitem{{\bf wxCURSOR\_RIGHT\_BUTTON}}{Represents a mouse with the right button depressed.} 154\twocolitem{{\bf wxCURSOR\_SIZENESW}}{A sizing cursor pointing NE-SW.} 155\twocolitem{{\bf wxCURSOR\_SIZENS}}{A sizing cursor pointing N-S.} 156\twocolitem{{\bf wxCURSOR\_SIZENWSE}}{A sizing cursor pointing NW-SE.} 157\twocolitem{{\bf wxCURSOR\_SIZEWE}}{A sizing cursor pointing W-E.} 158\twocolitem{{\bf wxCURSOR\_SIZING}}{A general sizing cursor.} 159\twocolitem{{\bf wxCURSOR\_SPRAYCAN}}{A spraycan cursor.} 160\twocolitem{{\bf wxCURSOR\_WAIT}}{A wait cursor.} 161\twocolitem{{\bf wxCURSOR\_WATCH}}{A watch cursor.} 162\twocolitem{{\bf wxCURSOR\_ARROWWAIT}}{A cursor with both an arrow and 163an hourglass, (windows.)} 164\end{twocollist}\twocolwidtha{5cm} 165 166Note that not all cursors are available on all platforms.} 167 168\docparam{cursor}{Pointer or reference to a cursor to copy.} 169 170\pythonnote{Constructors supported by wxPython are:\par 171\indented{2cm}{\begin{twocollist} 172\twocolitem{{\bf wxCursor(name, flags, hotSpotX=0, 173hotSpotY=0)}}{Constructs a cursor from a filename} 174\twocolitem{{\bf wxStockCursor(id)}}{Constructs a stock cursor } 175\end{twocollist}} 176} 177 178\perlnote{Constructors supported by wxPerl are:\par 179\begin{itemize} 180\item{Wx::Cursor->new( name, type, hotSpotX = 0, hotSpotY = 0 )} 181\item{Wx::Cursor->new( id )} 182\item{Wx::Cursor->new( image )} 183\item{Wx::Cursor->newData( bits, width, height, hotSpotX = -1, hotSpotY = -1, maskBits = 0 )} 184\end{itemize} 185} 186 187\wxheading{Example} 188 189The following is an example of creating a 190cursor from 32x32 bitmap data ({\tt down\_bits}) and a mask 191({\tt down\_mask}) where 1 is black and 0 is white for 192the bits, and 1 is opaque and 0 is transparent for 193the mask. It works on Windows and GTK+. 194 195\begin{verbatim} 196static char down_bits[] = { 255, 255, 255, 255, 31, 197 255, 255, 255, 31, 255, 255, 255, 31, 255, 255, 255, 198 31, 255, 255, 255, 31, 255, 255, 255, 31, 255, 255, 199 255, 31, 255, 255, 255, 31, 255, 255, 255, 25, 243, 200 255, 255, 19, 249, 255, 255, 7, 252, 255, 255, 15, 254, 201 255, 255, 31, 255, 255, 255, 191, 255, 255, 255, 255, 202 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 203 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 204 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 205 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 206 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 207 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 208 255 }; 209 210static char down_mask[] = { 240, 1, 0, 0, 240, 1, 211 0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 240, 1, 212 0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 255, 31, 0, 0, 255, 213 31, 0, 0, 254, 15, 0, 0, 252, 7, 0, 0, 248, 3, 0, 0, 214 240, 1, 0, 0, 224, 0, 0, 0, 64, 0, 0, 0, 0, 0, 0, 0, 0, 215 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 216 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 217 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 218 0, 0, 0, 0, 0 }; 219 220#ifdef __WXMSW__ 221wxBitmap down_bitmap(down_bits, 32, 32); 222wxBitmap down_mask_bitmap(down_mask, 32, 32); 223 224down_bitmap.SetMask(new wxMask(down_mask_bitmap)); 225wxImage down_image = down_bitmap.ConvertToImage(); 226down_image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, 6); 227down_image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, 14); 228wxCursor down_cursor = wxCursor(down_image); 229#else 230wxCursor down_cursor = wxCursor(down_bits, 32, 32, 231 6, 14, down_mask, wxWHITE, wxBLACK); 232#endif 233\end{verbatim} 234 235\membersection{wxCursor::\destruct{wxCursor}}\label{wxcursordtor} 236 237\func{}{\destruct{wxCursor}}{\void} 238 239Destroys the cursor. 240See \helpref{reference-counted object destruction}{refcountdestruct} for more info. 241 242A cursor can be reused for more 243than one window, and does not get destroyed when the window is 244destroyed. wxWidgets destroys all cursors on application exit, although 245it is best to clean them up explicitly. 246 247\membersection{wxCursor::IsOk}\label{wxcursorisok} 248 249\constfunc{bool}{IsOk}{\void} 250 251Returns true if cursor data is present. 252 253\membersection{wxCursor::operator $=$}\label{wxcursorassignment} 254 255\func{wxCursor\&}{operator $=$}{\param{const wxCursor\& }{cursor}} 256 257Assignment operator, using \helpref{reference counting}{trefcount}. 258 259