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