interface/cursor.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        cursor.h
   3 // Purpose:     interface of wxCursor
   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 in a
  16     different manner. Therefore, separate cursors will be created for the
  17     different environments.  Platform-specific methods for creating a wxCursor
  18     object are catered for, and this is an occasion where conditional
  19     compilation will probably be required (see wxIcon for an example).
  20
  21     A single cursor object may be used in many windows (any subwindow type).
  22     The wxWidgets convention is to set the cursor for a window, as in X, rather
  23     than to set it globally as in MS Windows, although a global wxSetCursor()
  24     function is also available for MS Windows use.
  25
  26     @section cursor_custom Creating a Custom Cursor
  27
  28     The following is an example of creating a cursor from 32x32 bitmap data
  29     (down_bits) and a mask (down_mask) where 1 is black and 0 is white for the
  30     bits, and 1 is opaque and 0 is transparent for the mask. It works on
  31     Windows and GTK+.
  32
  33     @code
  34     static char down_bits[] = { 255, 255, 255, 255, 31,
  35         255, 255, 255, 31, 255, 255, 255, 31, 255, 255, 255,
  36         31, 255, 255, 255, 31, 255, 255, 255, 31, 255, 255,
  37         255, 31, 255, 255, 255, 31, 255, 255, 255, 25, 243,
  38         255, 255, 19, 249, 255, 255, 7, 252, 255, 255, 15, 254,
  39         255, 255, 31, 255, 255, 255, 191, 255, 255, 255, 255,
  40         255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
  41         255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
  42         255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
  43         255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
  44         255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
  45         255, 255, 255, 255, 255, 255, 255, 255, 255, 255, 255,
  46         255 };
  47
  48     static char down_mask[] = { 240, 1, 0, 0, 240, 1,
  49         0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 240, 1,
  50         0, 0, 240, 1, 0, 0, 240, 1, 0, 0, 255, 31, 0, 0, 255,
  51         31, 0, 0, 254, 15, 0, 0, 252, 7, 0, 0, 248, 3, 0, 0,
  52         240, 1, 0, 0, 224, 0, 0, 0, 64, 0, 0, 0, 0, 0, 0, 0, 0,
  53         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
  54         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
  55         0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0, 0,
  56         0, 0, 0, 0, 0 };
  57
  58     #ifdef __WXMSW__
  59         wxBitmap down_bitmap(down_bits, 32, 32);
  60         wxBitmap down_mask_bitmap(down_mask, 32, 32);
  61
  62         down_bitmap.SetMask(new wxMask(down_mask_bitmap));
  63         wxImage down_image = down_bitmap.ConvertToImage();
  64         down_image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_X, 6);
  65         down_image.SetOption(wxIMAGE_OPTION_CUR_HOTSPOT_Y, 14);
  66         wxCursor down_cursor = wxCursor(down_image);
  67     #else
  68         wxCursor down_cursor = wxCursor(down_bits, 32, 32, 6, 14,
  69                                         down_mask, wxWHITE, wxBLACK);
  70     #endif
  71     @endcode
  72
  73     @library{wxcore}
  74     @category{gdi}
  75
  76     @stdobjects
  77     - ::wxNullCursor
  78     - ::wxSTANDARD_CURSOR
  79     - ::wxHOURGLASS_CURSOR
  80     - ::wxCROSS_CURSOR
  81
  82     @see wxBitmap, wxIcon, wxWindow::SetCursor(), wxSetCursor(),
  83          ::wxStockCursor
  84 */
  85 class wxCursor : public wxBitmap
  86 {
  87 public:
  88     /**
  89         Default constructor.
  90     */
  91     wxCursor();
  92     /**
  93         Constructs a cursor by passing an array of bits (Motif and GTK+ only).
  94         @a maskBits is used only under Motif and GTK+. The parameters @a fg and
  95         @a bg are only present on GTK+, and force the cursor to use particular
  96         background and foreground colours.
  97
  98         If either @a hotSpotX or @a hotSpotY is -1, the hotspot will be the
  99         centre of the cursor image (Motif only).
 100
 101         @param bits
 102             An array of bits.
 103         @param maskBits
 104             Bits for a mask bitmap.
 105         @param width
 106             Cursor width.
 107         @param height
 108             Cursor height.
 109         @param hotSpotX
 110             Hotspot x coordinate.
 111         @param hotSpotY
 112             Hotspot y coordinate.
 113     */
 114     wxCursor(const char bits[], int width, int height,
 115              int hotSpotX = -1, int hotSpotY = -1,
 116              const char maskBits[] = NULL,
 117              wxColour* fg = NULL, wxColour* bg = NULL);
 118     /**
 119         Constructs a cursor by passing a string resource name or filename.
 120
 121         On MacOS when specifying a string resource name, first the color
 122         cursors 'crsr' and then the black/white cursors 'CURS' in the resource
 123         chain are scanned through.
 124
 125         @a hotSpotX and @a hotSpotY are currently only used under Windows when
 126         loading from an icon file, to specify the cursor hotspot relative to
 127         the top left of the image.
 128
 129         @param type
 130             Icon type to load. Under Motif, type defaults to wxBITMAP_TYPE_XBM.
 131             Under Windows, it defaults to wxBITMAP_TYPE_CUR_RESOURCE. Under
 132             MacOS, it defaults to wxBITMAP_TYPE_MACCURSOR_RESOURCE.
 133             Under X, the permitted cursor types are:
 134             <ul>
 135             <li>wxBITMAP_TYPE_XBM - Load an X bitmap file.</li>
 136             </ul>
 137             Under Windows, the permitted types are:
 138             - wxBITMAP_TYPE_CUR - Load a cursor from a .cur cursor file (only
 139                                   if USE_RESOURCE_LOADING_IN_MSW is enabled in
 140                                   setup.h).
 141             - wxBITMAP_TYPE_CUR_RESOURCE - Load a Windows resource (as
 142                                            specified in the .rc file).
 143             - wxBITMAP_TYPE_ICO - Load a cursor from a .ico icon file (only if
 144                                   USE_RESOURCE_LOADING_IN_MSW is enabled in
 145                                   setup.h). Specify @a hotSpotX and @a hotSpotY.
 146         @param hotSpotX
 147             Hotspot x coordinate.
 148         @param hotSpotY
 149             Hotspot y coordinate.
 150     */
 151     wxCursor(const wxString& cursorName, long type,
 152              int hotSpotX = 0, int hotSpotY = 0);
 153     /**
 154         Constructs a cursor using a cursor identifier.
 155
 156         @param cursorId
 157             A stock cursor identifier. See ::wxStockCursor.
 158     */
 159     wxCursor(wxStockCursor cursorId);
 160     /**
 161         Constructs a cursor from a wxImage. If cursor are monochrome on the
 162         current platform, colors with the RGB elements all greater than 127
 163         will be foreground, colors less than this background. The mask (if any)
 164         will be used to specify the transparent area.
 165
 166         In wxMSW the foreground will be white and the background black. If the
 167         cursor is larger than 32x32 it is resized.
 168
 169         In wxGTK, colour cursors and alpha channel are supported (starting from
 170         GTK+ 2.2). Otherwise the two most frequent colors will be used for
 171         foreground and background. In any case, the cursor will be displayed at
 172         the size of the image.
 173
 174         In wxMac, if the cursor is larger than 16x16 it is resized and
 175         currently only shown as black/white (mask respected).
 176     */
 177     wxCursor(const wxImage& image);
 178     /**
 179         Copy constructor, uses @ref overview_refcount "reference counting".
 180
 181         @param cursor
 182             Pointer or reference to a cursor to copy.
 183     */
 184     wxCursor(const wxCursor& cursor);
 185
 186     /**
 187         Destroys the cursor. See
 188         @ref overview_refcount_destruct "reference-counted object destruction"
 189         for more info.
 190
 191         A cursor can be reused for more than one window, and does not get
 192         destroyed when the window is destroyed. wxWidgets destroys all cursors
 193         on application exit, although it is best to clean them up explicitly.
 194     */
 195     ~wxCursor();
 196
 197     /**
 198         Returns @true if cursor data is present.
 199     */
 200     bool IsOk() const;
 201
 202     /**
 203         Assignment operator, using @ref overview_refcount "reference counting".
 204     */
 205     wxCursor operator =(const wxCursor& cursor);
 206 };
 207
 208
 209 /**
 210     @name Predefined cursors.
 211
 212     @see wxStockCursor
 213 */
 214 //@{
 215 wxCursor wxNullCursor;
 216 wxCursor* wxSTANDARD_CURSOR;
 217 wxCursor* wxHOURGLASS_CURSOR;
 218 wxCursor* wxCROSS_CURSOR;
 219 //@}
 220