]> git.saurik.com Git - wxWidgets.git/blame - interface/cursor.h
no real changes, clarified the usage of WX_GL_DOUBLEBUFFER; documented it and other...
[wxWidgets.git] / interface / cursor.h
CommitLineData
23324ae1
FM
1/////////////////////////////////////////////////////////////////////////////
2// Name: cursor.h
e54c96f1 3// Purpose: interface of wxCursor
23324ae1
FM
4// Author: wxWidgets team
5// RCS-ID: $Id$
6// Licence: wxWindows license
7/////////////////////////////////////////////////////////////////////////////
8
9/**
10 @class wxCursor
11 @wxheader{cursor.h}
7c913512 12
23324ae1
FM
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
dc215c81
BP
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).
7c913512 20
23324ae1 21 A single cursor object may be used in many windows (any subwindow type).
dc215c81
BP
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
7c913512 72
23324ae1
FM
73 @library{wxcore}
74 @category{gdi}
7c913512 75
23324ae1 76 @stdobjects
dc215c81
BP
77 - ::wxNullCursor
78 - ::wxSTANDARD_CURSOR
79 - ::wxHOURGLASS_CURSOR
80 - ::wxCROSS_CURSOR
7c913512 81
dc215c81 82 @see wxBitmap, wxIcon, wxWindow::SetCursor(), wxSetCursor()
23324ae1
FM
83*/
84class wxCursor : public wxBitmap
85{
86public:
23324ae1 87 /**
dc215c81
BP
88 Default constructor.
89 */
90 wxCursor();
91 /**
92 Constructs a cursor by passing an array of bits (Motif and GTK+ only).
93 @a maskBits is used only under Motif and GTK+. The parameters @a fg and
94 @a bg are only present on GTK+, and force the cursor to use particular
95 background and foreground colours.
96
97 If either @a hotSpotX or @a hotSpotY is -1, the hotspot will be the
98 centre of the cursor image (Motif only).
3c4f71cc 99
7c913512 100 @param bits
4cc4bfaf 101 An array of bits.
7c913512 102 @param maskBits
4cc4bfaf 103 Bits for a mask bitmap.
7c913512 104 @param width
4cc4bfaf 105 Cursor width.
7c913512 106 @param height
4cc4bfaf 107 Cursor height.
7c913512 108 @param hotSpotX
4cc4bfaf 109 Hotspot x coordinate.
7c913512 110 @param hotSpotY
4cc4bfaf 111 Hotspot y coordinate.
dc215c81
BP
112 */
113 wxCursor(const char bits[], int width, int height,
114 int hotSpotX = -1, int hotSpotY = -1,
115 const char maskBits[] = NULL,
116 wxColour* fg = NULL, wxColour* bg = NULL);
117 /**
118 Constructs a cursor by passing a string resource name or filename.
3c4f71cc 119
dc215c81
BP
120 On MacOS when specifying a string resource name, first the color
121 cursors 'crsr' and then the black/white cursors 'CURS' in the resource
122 chain are scanned through.
3c4f71cc 123
dc215c81
BP
124 @a hotSpotX and @a hotSpotY are currently only used under Windows when
125 loading from an icon file, to specify the cursor hotspot relative to
126 the top left of the image.
3c4f71cc 127
dc215c81
BP
128 @param type
129 Icon type to load. Under Motif, type defaults to wxBITMAP_TYPE_XBM.
130 Under Windows, it defaults to wxBITMAP_TYPE_CUR_RESOURCE. Under
131 MacOS, it defaults to wxBITMAP_TYPE_MACCURSOR_RESOURCE.
132 Under X, the permitted cursor types are:
133 <ul>
134 <li>wxBITMAP_TYPE_XBM - Load an X bitmap file.</li>
135 </ul>
4cc4bfaf 136 Under Windows, the permitted types are:
dc215c81
BP
137 - wxBITMAP_TYPE_CUR - Load a cursor from a .cur cursor file (only
138 if USE_RESOURCE_LOADING_IN_MSW is enabled in
139 setup.h).
140 - wxBITMAP_TYPE_CUR_RESOURCE - Load a Windows resource (as
141 specified in the .rc file).
142 - wxBITMAP_TYPE_ICO - Load a cursor from a .ico icon file (only if
143 USE_RESOURCE_LOADING_IN_MSW is enabled in
144 setup.h). Specify @a hotSpotX and @a hotSpotY.
145 @param hotSpotX
146 Hotspot x coordinate.
147 @param hotSpotY
148 Hotspot y coordinate.
149 */
150 wxCursor(const wxString& cursorName, long type,
151 int hotSpotX = 0, int hotSpotY = 0);
152 /**
153 Constructs a cursor using a cursor identifier.
3c4f71cc 154
7c913512 155 @param cursorId
dc215c81
BP
156 A stock cursor identifier. May be one of the following (note that
157 not all cursors are available on all platforms):
158 - wxCURSOR_ARROW - A standard arrow cursor.
159 - wxCURSOR_RIGHT_ARROW - A standard arrow cursor pointing to the
160 right.
161 - wxCURSOR_BLANK - Transparent cursor.
162 - wxCURSOR_BULLSEYE - Bullseye cursor.
163 - wxCURSOR_CHAR - Rectangular character cursor.
164 - wxCURSOR_CROSS - A cross cursor.
165 - wxCURSOR_HAND - A hand cursor.
166 - wxCURSOR_IBEAM - An I-beam cursor (vertical line).
167 - wxCURSOR_LEFT_BUTTON - Represents a mouse with the left button
168 depressed.
169 - wxCURSOR_MAGNIFIER - A magnifier icon.
170 - wxCURSOR_MIDDLE_BUTTON - Represents a mouse with the middle
171 button depressed.
172 - wxCURSOR_NO_ENTRY - A no-entry sign cursor.
173 - wxCURSOR_PAINT_BRUSH - A paintbrush cursor.
174 - wxCURSOR_PENCIL - A pencil cursor.
175 - wxCURSOR_POINT_LEFT - A cursor that points left.
176 - wxCURSOR_POINT_RIGHT - A cursor that points right.
177 - wxCURSOR_QUESTION_ARROW - An arrow and question mark.
178 - wxCURSOR_RIGHT_BUTTON - Represents a mouse with the right
179 button depressed.
180 - wxCURSOR_SIZENESW - A sizing cursor pointing NE-SW.
181 - wxCURSOR_SIZENS - A sizing cursor pointing N-S.
182 - wxCURSOR_SIZENWSE - A sizing cursor pointing NW-SE.
183 - wxCURSOR_SIZEWE - A sizing cursor pointing W-E.
184 - wxCURSOR_SIZING - A general sizing cursor.
185 - wxCURSOR_SPRAYCAN - A spraycan cursor.
186 - wxCURSOR_WAIT - A wait cursor.
187 - wxCURSOR_WATCH - A watch cursor.
188 - wxCURSOR_ARROWWAIT - A cursor with both an arrow and an
189 hourglass, (windows.)
190 */
191 wxCursor(int cursorId);
192 /**
193 Constructs a cursor from a wxImage. If cursor are monochrome on the
194 current platform, colors with the RGB elements all greater than 127
195 will be foreground, colors less than this background. The mask (if any)
196 will be used to specify the transparent area.
3c4f71cc 197
dc215c81
BP
198 In wxMSW the foreground will be white and the background black. If the
199 cursor is larger than 32x32 it is resized.
3c4f71cc 200
dc215c81
BP
201 In wxGTK, colour cursors and alpha channel are supported (starting from
202 GTK+ 2.2). Otherwise the two most frequent colors will be used for
203 foreground and background. In any case, the cursor will be displayed at
204 the size of the image.
3c4f71cc 205
dc215c81
BP
206 In wxMac, if the cursor is larger than 16x16 it is resized and
207 currently only shown as black/white (mask respected).
208 */
209 wxCursor(const wxImage& image);
210 /**
211 Copy constructor, uses @ref overview_refcount "reference counting".
3c4f71cc 212
7c913512 213 @param cursor
4cc4bfaf 214 Pointer or reference to a cursor to copy.
23324ae1 215 */
7c913512 216 wxCursor(const wxCursor& cursor);
23324ae1
FM
217
218 /**
dc215c81
BP
219 Destroys the cursor. See
220 @ref overview_refcount_destruct "reference-counted object destruction"
221 for more info.
222
223 A cursor can be reused for more than one window, and does not get
224 destroyed when the window is destroyed. wxWidgets destroys all cursors
225 on application exit, although it is best to clean them up explicitly.
23324ae1
FM
226 */
227 ~wxCursor();
228
229 /**
230 Returns @true if cursor data is present.
231 */
328f5751 232 bool IsOk() const;
23324ae1
FM
233
234 /**
dc215c81 235 Assignment operator, using @ref overview_refcount "reference counting".
23324ae1
FM
236 */
237 wxCursor operator =(const wxCursor& cursor);
238};
e54c96f1 239
e54c96f1 240
dc215c81
BP
241/** @name Predefined cursors. */
242//@{
243wxCursor wxNullCursor;
244wxCursor* wxSTANDARD_CURSOR;
245wxCursor* wxHOURGLASS_CURSOR;
246wxCursor* wxCROSS_CURSOR;
247//@}
e54c96f1 248