interface/cursor.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        cursor.h
   3 // Purpose:     documentation for wxCursor class
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxCursor
  11     @wxheader{cursor.h}
  12
  13     A cursor is a small bitmap usually used for denoting where the mouse
  14     pointer is, with a picture that might indicate the interpretation of a
  15     mouse click. As with icons, cursors in X and MS Windows are created
  16     in a different manner. Therefore, separate cursors will be created for the
  17     different environments.  Platform-specific methods for creating a @b wxCursor
  18     object are catered for, and this is an occasion where
  19     conditional compilation will probably be required (see wxIcon for
  20     an example).
  21
  22     A single cursor object may be used in many windows (any subwindow type).
  23     The wxWidgets convention is to set the cursor for a window, as in X,
  24     rather than to set it globally as in MS Windows, although a
  25     global ::wxSetCursor is also available for MS Windows use.
  26
  27     @library{wxcore}
  28     @category{gdi}
  29
  30     @stdobjects
  31     Objects:
  32     wxNullCursor
  33     Pointers:
  34     wxSTANDARD_CURSOR
  35
  36     wxHOURGLASS_CURSOR
  37
  38     wxCROSS_CURSOR
  39
  40     @seealso
  41     wxBitmap, wxIcon, wxWindow::SetCursor, ::wxSetCursor
  42 */
  43 class wxCursor : public wxBitmap
  44 {
  45 public:
  46     //@{
  47     /**
  48         Copy constructor, uses @ref overview_trefcount "reference counting".
  49
  50         @param bits
  51         An array of bits.
  52
  53         @param maskBits
  54         Bits for a mask bitmap.
  55
  56         @param width
  57         Cursor width.
  58
  59         @param height
  60         Cursor height.
  61
  62         @param hotSpotX
  63         Hotspot x coordinate.
  64
  65         @param hotSpotY
  66         Hotspot y coordinate.
  67
  68         @param type
  69         Icon type to load. Under Motif, type defaults to wxBITMAP_TYPE_XBM. Under
  70         Windows,
  71         it defaults to wxBITMAP_TYPE_CUR_RESOURCE. Under MacOS, it defaults to
  72         wxBITMAP_TYPE_MACCURSOR_RESOURCE.
  73
  74         Under X, the permitted cursor types are:
  75
  76
  77         wxBITMAP_TYPE_XBM
  78
  79
  80         Load an X bitmap file.
  81
  82         Under Windows, the permitted types are:
  83
  84
  85         wxBITMAP_TYPE_CUR
  86
  87
  88         Load a cursor from a .cur cursor file (only if USE_RESOURCE_LOADING_IN_MSW
  89         is enabled in setup.h).
  90
  91         wxBITMAP_TYPE_CUR_RESOURCE
  92
  93
  94         Load a Windows resource (as specified in the .rc file).
  95
  96         wxBITMAP_TYPE_ICO
  97
  98
  99         Load a cursor from a .ico icon file (only if USE_RESOURCE_LOADING_IN_MSW
 100         is enabled in setup.h). Specify hotSpotX and hotSpotY.
 101
 102         @param cursorId
 103         A stock cursor identifier. May be one of:
 104
 105
 106         wxCURSOR_ARROW
 107
 108
 109         A standard arrow cursor.
 110
 111         wxCURSOR_RIGHT_ARROW
 112
 113
 114         A standard arrow cursor
 115         pointing to the right.
 116
 117         wxCURSOR_BLANK
 118
 119
 120         Transparent cursor.
 121
 122         wxCURSOR_BULLSEYE
 123
 124
 125         Bullseye cursor.
 126
 127         wxCURSOR_CHAR
 128
 129
 130         Rectangular character cursor.
 131
 132         wxCURSOR_CROSS
 133
 134
 135         A cross cursor.
 136
 137         wxCURSOR_HAND
 138
 139
 140         A hand cursor.
 141
 142         wxCURSOR_IBEAM
 143
 144
 145         An I-beam cursor (vertical line).
 146
 147         wxCURSOR_LEFT_BUTTON
 148
 149
 150         Represents a mouse with the left button depressed.
 151
 152         wxCURSOR_MAGNIFIER
 153
 154
 155         A magnifier icon.
 156
 157         wxCURSOR_MIDDLE_BUTTON
 158
 159
 160         Represents a mouse with the middle button depressed.
 161
 162         wxCURSOR_NO_ENTRY
 163
 164
 165         A no-entry sign cursor.
 166
 167         wxCURSOR_PAINT_BRUSH
 168
 169
 170         A paintbrush cursor.
 171
 172         wxCURSOR_PENCIL
 173
 174
 175         A pencil cursor.
 176
 177         wxCURSOR_POINT_LEFT
 178
 179
 180         A cursor that points left.
 181
 182         wxCURSOR_POINT_RIGHT
 183
 184
 185         A cursor that points right.
 186
 187         wxCURSOR_QUESTION_ARROW
 188
 189
 190         An arrow and question mark.
 191
 192         wxCURSOR_RIGHT_BUTTON
 193
 194
 195         Represents a mouse with the right button depressed.
 196
 197         wxCURSOR_SIZENESW
 198
 199
 200         A sizing cursor pointing NE-SW.
 201
 202         wxCURSOR_SIZENS
 203
 204
 205         A sizing cursor pointing N-S.
 206
 207         wxCURSOR_SIZENWSE
 208
 209
 210         A sizing cursor pointing NW-SE.
 211
 212         wxCURSOR_SIZEWE
 213
 214
 215         A sizing cursor pointing W-E.
 216
 217         wxCURSOR_SIZING
 218
 219
 220         A general sizing cursor.
 221
 222         wxCURSOR_SPRAYCAN
 223
 224
 225         A spraycan cursor.
 226
 227         wxCURSOR_WAIT
 228
 229
 230         A wait cursor.
 231
 232         wxCURSOR_WATCH
 233
 234
 235         A watch cursor.
 236
 237         wxCURSOR_ARROWWAIT
 238
 239
 240         A cursor with both an arrow and
 241         an hourglass, (windows.)
 242
 243         Note that not all cursors are available on all platforms.
 244
 245         @param cursor
 246         Pointer or reference to a cursor to copy.
 247     */
 248     wxCursor();
 249         wxCursor(const char bits[], int width, int height,
 250                  int hotSpotX=-1, int hotSpotY=-1,
 251                  const char maskBits[]=@NULL,
 252                  wxColour* fg=@NULL,
 253                  wxColour* bg=@NULL);
 254         wxCursor(const wxString& cursorName, long type,
 255                  int hotSpotX=0, int hotSpotY=0);
 256         wxCursor(int cursorId);
 257         wxCursor(const wxImage& image);
 258         wxCursor(const wxCursor& cursor);
 259     //@}
 260
 261     /**
 262         Destroys the cursor.
 263         See @ref overview_refcountdestruct "reference-counted object destruction" for
 264         more info.
 265
 266         A cursor can be reused for more
 267         than one window, and does not get destroyed when the window is
 268         destroyed. wxWidgets destroys all cursors on application exit, although
 269         it is best to clean them up explicitly.
 270     */
 271     ~wxCursor();
 272
 273     /**
 274         Returns @true if cursor data is present.
 275     */
 276 #define bool IsOk()     /* implementation is private */
 277
 278     /**
 279         Assignment operator, using @ref overview_trefcount "reference counting".
 280     */
 281     wxCursor operator =(const wxCursor& cursor);
 282 };