]> git.saurik.com Git - wxWidgets.git/blob - interface/wx/menuitem.h
run tests on the wxMSW port again
[wxWidgets.git] / interface / wx / menuitem.h
1 /////////////////////////////////////////////////////////////////////////////
2 // Name: menuitem.h
3 // Purpose: interface of wxMenu, wxMenuItem
4 // Author: wxWidgets team
5 // RCS-ID: $Id$
6 // Licence: wxWindows license
7 /////////////////////////////////////////////////////////////////////////////
8
9 /**
10 @class wxMenuItem
11
12 A menu item represents an item in a menu.
13
14 Note that you usually don't have to deal with it directly as wxMenu methods
15 usually construct an object of this class for you.
16
17 Also please note that the methods related to fonts and bitmaps are currently
18 only implemented for Windows, Mac and GTK+.
19
20 @beginEventEmissionTable{wxCommandEvent,wxMenuEvent}
21 @event{EVT_MENU(id, func)}
22 Process a @c wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item.
23 This type of event is sent as wxCommandEvent.
24 @event{EVT_MENU_RANGE(id1, id2, func)}
25 Process a @c wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items.
26 This type of event is sent as wxCommandEvent.
27 @event{EVT_MENU_OPEN(func)}
28 A menu is about to be opened. On Windows, this is only sent once for each
29 navigation of the menubar (up until all menus have closed).
30 This type of event is sent as wxMenuEvent.
31 @event{EVT_MENU_CLOSE(func)}
32 A menu has been just closed.
33 This type of event is sent as wxMenuEvent.
34 @event{EVT_MENU_HIGHLIGHT(id, func)}
35 The menu item with the specified id has been highlighted: used to show
36 help prompts in the status bar by wxFrame
37 This type of event is sent as wxMenuEvent.
38 @event{EVT_MENU_HIGHLIGHT_ALL(func)}
39 A menu item has been highlighted, i.e. the currently selected menu item has changed.
40 This type of event is sent as wxMenuEvent.
41 @endEventTable
42
43 @library{wxcore}
44 @category{menus}
45
46 @see wxMenuBar, wxMenu
47 */
48 class wxMenuItem : public wxObject
49 {
50 public:
51 /**
52 Constructs a wxMenuItem object.
53
54 Menu items can be standard, or "stock menu items", or custom.
55 For the standard menu items (such as commands to open a file, exit the
56 program and so on, see @ref page_stockitems for the full list) it is enough
57 to specify just the stock ID and leave @a text and @a helpString empty.
58
59 In fact, leaving at least @a text empty for the stock menu items is strongly
60 recommended as they will have appearance and keyboard interface (including
61 standard accelerators) familiar to the user.
62
63 For the custom (non-stock) menu items, @a text must be specified and while
64 @a helpString may be left empty, it's recommended to pass the item
65 description (which is automatically shown by the library in the status bar
66 when the menu item is selected) in this parameter.
67
68 Finally note that you can e.g. use a stock menu label without using its stock
69 help string:
70
71 @code
72 // use all stock properties:
73 helpMenu->Append(wxID_ABOUT);
74
75 // use the stock label and the stock accelerator but not the stock help string:
76 helpMenu->Append(wxID_ABOUT, wxEmptyString, "My custom help string");
77
78 // use all stock properties except for the bitmap:
79 wxMenuItem *mymenu = new wxMenuItem(helpMenu, wxID_ABOUT);
80 mymenu->SetBitmap(wxArtProvider::GetBitmap(wxART_WARNING));
81 helpMenu->Append(mymenu);
82 @endcode
83
84 that is, stock properties are set independently one from the other.
85
86 @param parentMenu
87 Menu that the menu item belongs to. Can be @NULL if the item is
88 going to be added to the menu later.
89 @param id
90 Identifier for this menu item. May be @c wxID_SEPARATOR, in which
91 case the given kind is ignored and taken to be @c wxITEM_SEPARATOR
92 instead.
93 @param text
94 Text for the menu item, as shown on the menu. An accelerator key can
95 be specified using the ampersand @c & character. In order to embed an
96 ampersand character in the menu item text, the ampersand must be doubled.
97 @param helpString
98 Optional help string that will be shown on the status bar.
99 @param kind
100 May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or
101 @c wxITEM_RADIO.
102 @param subMenu
103 If non-@NULL, indicates that the menu item is a submenu.
104 */
105 wxMenuItem(wxMenu* parentMenu = NULL, int id = wxID_SEPARATOR,
106 const wxString& text = wxEmptyString,
107 const wxString& helpString = wxEmptyString,
108 wxItemKind kind = wxITEM_NORMAL,
109 wxMenu* subMenu = NULL);
110
111 /**
112 Destructor.
113 */
114 virtual ~wxMenuItem();
115
116 /**
117 Checks or unchecks the menu item.
118 Note that this only works when the item is already appended to a menu.
119 */
120 virtual void Check(bool check = true);
121
122 /**
123 Enables or disables the menu item.
124 */
125 virtual void Enable(bool enable = true);
126
127 /**
128 Returns the background colour associated with the menu item (Windows only).
129 */
130 wxColour GetBackgroundColour() const;
131
132 /**
133 Returns the checked or unchecked bitmap (Windows only).
134 */
135 virtual const wxBitmap& GetBitmap() const;
136
137 /**
138 Returns the font associated with the menu item (Windows only).
139 */
140 wxFont GetFont() const;
141
142 /**
143 Returns the help string associated with the menu item.
144 */
145 const wxString& GetHelp() const;
146
147 /**
148 Returns the menu item identifier.
149 */
150 int GetId() const;
151
152 /**
153 Returns the text associated with the menu item including any accelerator
154 characters that were passed to the constructor or SetItemLabel().
155
156 @see GetItemLabelText(), GetLabelText()
157 */
158 virtual wxString GetItemLabel() const;
159
160 /**
161 Returns the text associated with the menu item, without any accelerator
162 characters.
163
164 @see GetItemLabel(), GetLabelText()
165 */
166 virtual wxString GetItemLabelText() const;
167
168 /**
169 Returns the item kind, one of @c wxITEM_SEPARATOR, @c wxITEM_NORMAL,
170 @c wxITEM_CHECK or @c wxITEM_RADIO.
171 */
172 wxItemKind GetKind() const;
173
174 /**
175 Returns the text associated with the menu item without any accelerator
176 characters it might contain.
177
178 @deprecated This function is deprecated in favour of GetItemLabelText().
179
180 @see GetText(), GetLabelFromText()
181 */
182 wxString GetLabel() const;
183
184 /**
185 @deprecated This function is deprecated; please use GetLabelText() instead.
186
187 @see GetText(), GetLabel()
188 */
189 static wxString GetLabelFromText(const wxString& text);
190
191 /**
192 Strips all accelerator characters and mnemonics from the given @a text.
193 For example:
194
195 @code
196 wxMenuItem::GetLabelfromText("&Hello\tCtrl-h");
197 @endcode
198
199 will return just @c "Hello".
200
201 @see GetItemLabelText(), GetItemLabel()
202 */
203 static wxString GetLabelText(const wxString& text);
204
205 /**
206 Gets the width of the menu item checkmark bitmap (Windows only).
207 */
208 int GetMarginWidth() const;
209
210 /**
211 Returns the menu this menu item is in, or @NULL if this menu item is not
212 attached.
213 */
214 wxMenu* GetMenu() const;
215
216 /**
217 Returns the text associated with the menu item.
218
219 @deprecated This function is deprecated. Please use
220
221 GetItemLabel() or GetItemLabelText() instead.
222 */
223 wxString GetName() const;
224
225 /**
226 Returns the submenu associated with the menu item, or @NULL if there isn't one.
227 */
228 wxMenu* GetSubMenu() const;
229
230 /**
231 Returns the text associated with the menu item, such as it was passed to the
232 wxMenuItem constructor, i.e. with any accelerator characters it may contain.
233
234 @deprecated This function is deprecated in favour of GetItemLabel().
235
236 @see GetLabel(), GetLabelFromText()
237 */
238 const wxString& GetText() const;
239
240 /**
241 Returns the text colour associated with the menu item (Windows only).
242 */
243 wxColour GetTextColour() const;
244
245 /**
246 Returns @true if the item is checkable.
247 */
248 bool IsCheckable() const;
249
250 /**
251 Returns @true if the item is checked.
252 */
253 virtual bool IsChecked() const;
254
255 /**
256 Returns @true if the item is enabled.
257 */
258 virtual bool IsEnabled() const;
259
260 /**
261 Returns @true if the item is a separator.
262 */
263 bool IsSeparator() const;
264
265 /**
266 Returns @true if the item is a submenu.
267 */
268 bool IsSubMenu() const;
269
270 /**
271 Sets the background colour associated with the menu item (Windows only).
272 */
273 void SetBackgroundColour(const wxColour& colour) const;
274
275 /**
276 Sets the bitmap for the menu item.
277 It is equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap).
278
279 @onlyfor{wxmsw,wxosx,wxgtk}
280 */
281 virtual void SetBitmap(const wxBitmap& bmp);
282
283 /**
284 Sets the checked/unchecked bitmaps for the menu item.
285 The first bitmap is also used as the single bitmap for uncheckable menu items.
286
287 @onlyfor{wxmsw}
288 */
289 void SetBitmaps(const wxBitmap& checked,
290 const wxBitmap& unchecked = wxNullBitmap);
291
292 /**
293 Sets the font associated with the menu item (Windows only).
294 */
295 void SetFont(const wxFont& font);
296
297 /**
298 Sets the help string.
299 */
300 void SetHelp(const wxString& helpString);
301
302 /**
303 Sets the label associated with the menu item.
304 */
305 virtual void SetItemLabel(const wxString& label);
306
307 /**
308 Sets the width of the menu item checkmark bitmap (Windows only).
309 */
310 void SetMarginWidth(int width) const;
311
312 /**
313 Sets the parent menu which will contain this menu item.
314 */
315 void SetMenu(wxMenu* menu);
316
317 /**
318 Sets the submenu of this menu item.
319 */
320 void SetSubMenu(wxMenu* menu);
321
322 /**
323 Sets the text associated with the menu item.
324
325 @deprecated This function is deprecated in favour of SetItemLabel().
326 */
327 virtual void SetText(const wxString& text);
328
329 /**
330 Sets the text colour associated with the menu item (Windows only).
331 */
332 void SetTextColour(const wxColour& colour);
333 };
334