/////////////////////////////////////////////////////////////////////////////
// Name: menuitem.h
-// Purpose: interface of wxMenuItem
+// Purpose: interface of wxMenu, wxMenuItem
// Author: wxWidgets team
// RCS-ID: $Id$
// Licence: wxWindows license
/**
@class wxMenuItem
- A menu item represents an item in a menu. Note that you usually don't have to
- deal with it directly as wxMenu methods usually construct an
- object of this class for you.
+ A menu item represents an item in a menu.
+
+ Note that you usually don't have to deal with it directly as wxMenu methods
+ usually construct an object of this class for you.
Also please note that the methods related to fonts and bitmaps are currently
- only implemented for Windows and GTK+.
+ only implemented for Windows, Mac and GTK+.
+
+ @beginEventEmissionTable{wxCommandEvent,wxMenuEvent}
+ @event{EVT_MENU(id, func)}
+ Process a @c wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item.
+ This type of event is sent as wxCommandEvent.
+ @event{EVT_MENU_RANGE(id1, id2, func)}
+ Process a @c wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items.
+ This type of event is sent as wxCommandEvent.
+ @event{EVT_MENU_OPEN(func)}
+ A menu is about to be opened. On Windows, this is only sent once for each
+ navigation of the menubar (up until all menus have closed).
+ This type of event is sent as wxMenuEvent.
+ @event{EVT_MENU_CLOSE(func)}
+ A menu has been just closed.
+ This type of event is sent as wxMenuEvent.
+ @event{EVT_MENU_HIGHLIGHT(id, func)}
+ The menu item with the specified id has been highlighted: used to show
+ help prompts in the status bar by wxFrame
+ This type of event is sent as wxMenuEvent.
+ @event{EVT_MENU_HIGHLIGHT_ALL(func)}
+ A menu item has been highlighted, i.e. the currently selected menu item has changed.
+ This type of event is sent as wxMenuEvent.
+ @endEventTable
@library{wxcore}
@category{menus}
public:
/**
Constructs a wxMenuItem object.
- Menu items can be standard, or "stock menu items", or custom. For the
- standard menu items (such as commands to open a file, exit the program and so
- on, see @ref page_stockitems "Stock Items" for the full list) it is enough
- to specify just the stock ID and leave @a text and @a helpString empty. In
- fact, leaving at least @a text empty for the stock menu items is strongly
+
+ Menu items can be standard, or "stock menu items", or custom.
+ For the standard menu items (such as commands to open a file, exit the
+ program and so on, see @ref page_stockitems for the full list) it is enough
+ to specify just the stock ID and leave @a text and @a helpString empty.
+
+ In fact, leaving at least @a text empty for the stock menu items is strongly
recommended as they will have appearance and keyboard interface (including
standard accelerators) familiar to the user.
+
For the custom (non-stock) menu items, @a text must be specified and while
@a helpString may be left empty, it's recommended to pass the item
- description (which is automatically shown by the library in the status bar when
- the menu item is selected) in this parameter.
+ description (which is automatically shown by the library in the status bar
+ when the menu item is selected) in this parameter.
+
Finally note that you can e.g. use a stock menu label without using its stock
- help string; that is, stock properties are set independently one from the other.
+ help string:
+
+ @code
+ // use all stock properties:
+ helpMenu->Append(wxID_ABOUT);
+
+ // use the stock label and the stock accelerator but not the stock help string:
+ helpMenu->Append(wxID_ABOUT, wxEmptyString, "My custom help string");
+
+ // use all stock properties except for the bitmap:
+ wxMenuItem *mymenu = new wxMenuItem(helpMenu, wxID_ABOUT);
+ mymenu->SetBitmap(wxArtProvider::GetBitmap(wxART_WARNING));
+ helpMenu->Append(mymenu);
+ @endcode
+
+ that is, stock properties are set independently one from the other.
@param parentMenu
Menu that the menu item belongs to. Can be @NULL if the item is
case the given kind is ignored and taken to be @c wxITEM_SEPARATOR
instead.
@param text
- Text for the menu item, as shown on the menu. An accelerator
- key can be specified using the ampersand " character. In order to embed an
+ Text for the menu item, as shown on the menu. An accelerator key can
+ be specified using the ampersand @c & character. In order to embed an
ampersand character in the menu item text, the ampersand must be doubled.
@param helpString
Optional help string that will be shown on the status bar.
@param kind
- May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or @c
- wxITEM_RADIO
+ May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or
+ @c wxITEM_RADIO.
@param subMenu
If non-@NULL, indicates that the menu item is a submenu.
*/
wxMenuItem(wxMenu* parentMenu = NULL, int id = wxID_SEPARATOR,
- const wxString& text = "",
- const wxString& helpString = "",
+ const wxString& text = wxEmptyString,
+ const wxString& helpString = wxEmptyString,
wxItemKind kind = wxITEM_NORMAL,
wxMenu* subMenu = NULL);
/**
Returns the checked or unchecked bitmap (Windows only).
*/
- wxBitmap GetBitmap(bool checked = true) const;
+ virtual const wxBitmap& GetBitmap() const;
/**
Returns the font associated with the menu item (Windows only).
/**
Returns the help string associated with the menu item.
*/
- wxString GetHelp() const;
+ const wxString& GetHelp() const;
/**
Returns the menu item identifier.
/**
Returns the text associated with the menu item including any accelerator
- characters that were passed to the constructor or SetItemLabel.
+ characters that were passed to the constructor or SetItemLabel().
@see GetItemLabelText(), GetLabelText()
*/
/**
Returns the text associated with the menu item without any accelerator
characters it might contain.
+
@deprecated This function is deprecated in favour of GetItemLabelText().
+
@see GetText(), GetLabelFromText()
*/
wxString GetLabel() const;
/**
@deprecated This function is deprecated; please use GetLabelText() instead.
+
@see GetText(), GetLabel()
*/
static wxString GetLabelFromText(const wxString& text);
/**
- Strips all accelerator characters and mnemonics from the given @e text.
+ Strips all accelerator characters and mnemonics from the given @a text.
For example:
@code
- wxMenuItem::GetLabelfromText( "&Hello\tCtrl-h");
+ wxMenuItem::GetLabelfromText("&Hello\tCtrl-h");
@endcode
will return just @c "Hello".
/**
Returns the text associated with the menu item.
+
@deprecated This function is deprecated. Please use
+
GetItemLabel() or GetItemLabelText() instead.
*/
wxString GetName() const;
/**
Returns the text associated with the menu item, such as it was passed to the
wxMenuItem constructor, i.e. with any accelerator characters it may contain.
+
@deprecated This function is deprecated in favour of GetItemLabel().
+
@see GetLabel(), GetLabelFromText()
*/
- wxString GetText() const;
+ const wxString& GetText() const;
/**
Returns the text colour associated with the menu item (Windows only).
void SetBackgroundColour(const wxColour& colour) const;
/**
- Sets the bitmap for the menu item (Windows and GTK+ only). It is
- equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap).
+ Sets the bitmap for the menu item.
+
+ It is equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap) if @a
+ checked is @true (default value) or SetBitmaps(wxNullBitmap, bmp)
+ otherwise.
+
+ @onlyfor{wxmsw,wxosx,wxgtk}
*/
- virtual void SetBitmap(const wxBitmap& bmp);
+ virtual void SetBitmap(const wxBitmap& bmp, bool checked = true);
/**
- Sets the checked/unchecked bitmaps for the menu item (Windows only). The first
- bitmap
- is also used as the single bitmap for uncheckable menu items.
+ Sets the checked/unchecked bitmaps for the menu item.
+ The first bitmap is also used as the single bitmap for uncheckable menu items.
+
+ @onlyfor{wxmsw}
*/
void SetBitmaps(const wxBitmap& checked,
const wxBitmap& unchecked = wxNullBitmap);
/**
Sets the parent menu which will contain this menu item.
*/
- void SetMenu(const wxMenu* menu);
+ void SetMenu(wxMenu* menu);
/**
Sets the submenu of this menu item.
*/
- void SetSubMenu(const wxMenu* menu);
+ void SetSubMenu(wxMenu* menu);
/**
Sets the text associated with the menu item.
+
@deprecated This function is deprecated in favour of SetItemLabel().
*/
virtual void SetText(const wxString& text);
projects / wxWidgets.git / blobdiff