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