X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ae3c17b4013e80b99976c750c19fca47729517f6..23790a2a29ef25f28568b30e78b7f251f1492a12:/interface/wx/menuitem.h diff --git a/interface/wx/menuitem.h b/interface/wx/menuitem.h index f9372b5b7c..324dbdc0d2 100644 --- a/interface/wx/menuitem.h +++ b/interface/wx/menuitem.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: menuitem.h -// Purpose: interface of wxMenuItem +// Purpose: interface of wxMenu, wxMenuItem // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -8,14 +8,37 @@ /** @class wxMenuItem - @wxheader{menuitem.h} - 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} @@ -27,19 +50,38 @@ class wxMenuItem : public wxObject 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 @@ -49,38 +91,38 @@ public: 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); /** Destructor. */ - ~wxMenuItem(); + virtual ~wxMenuItem(); /** Checks or unchecks the menu item. Note that this only works when the item is already appended to a menu. */ - void Check(bool check = true); + virtual void Check(bool check = true); /** Enables or disables the menu item. */ - void Enable(bool enable = true); + virtual void Enable(bool enable = true); /** Returns the background colour associated with the menu item (Windows only). @@ -90,7 +132,7 @@ public: /** 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). @@ -100,7 +142,7 @@ public: /** Returns the help string associated with the menu item. */ - wxString GetHelp() const; + const wxString& GetHelp() const; /** Returns the menu item identifier. @@ -109,11 +151,11 @@ public: /** 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() */ - wxString GetItemLabel() const; + virtual wxString GetItemLabel() const; /** Returns the text associated with the menu item, without any accelerator @@ -121,7 +163,7 @@ public: @see GetItemLabel(), GetLabelText() */ - wxString GetItemLabelText() const; + virtual wxString GetItemLabelText() const; /** Returns the item kind, one of @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @@ -132,23 +174,26 @@ public: /** 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". @@ -170,7 +215,9 @@ public: /** Returns the text associated with the menu item. + @deprecated This function is deprecated. Please use + GetItemLabel() or GetItemLabelText() instead. */ wxString GetName() const; @@ -183,10 +230,12 @@ public: /** 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). @@ -201,12 +250,12 @@ public: /** Returns @true if the item is checked. */ - bool IsChecked() const; + virtual bool IsChecked() const; /** Returns @true if the item is enabled. */ - bool IsEnabled() const; + virtual bool IsEnabled() const; /** Returns @true if the item is a separator. @@ -224,15 +273,21 @@ public: 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} */ - 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); @@ -250,7 +305,7 @@ public: /** Sets the label associated with the menu item. */ - void SetItemLabel(const wxString& label); + virtual void SetItemLabel(const wxString& label); /** Sets the width of the menu item checkmark bitmap (Windows only). @@ -260,18 +315,19 @@ public: /** 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(). */ - void SetText(const wxString& text); + virtual void SetText(const wxString& text); /** Sets the text colour associated with the menu item (Windows only).