X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/ba1d7a6cec8d9569ce2e380d4a39ddcd4450c9b5..92c0fc34c104c8d7c12d6a3b78ea232690fc23f4:/interface/wx/menuitem.h diff --git a/interface/wx/menuitem.h b/interface/wx/menuitem.h index eb25e171da..af5a6d2943 100644 --- a/interface/wx/menuitem.h +++ b/interface/wx/menuitem.h @@ -2,8 +2,7 @@ // Name: menuitem.h // Purpose: interface of wxMenu, wxMenuItem // Author: wxWidgets team -// RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -15,7 +14,30 @@ 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_MENU 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_MENU 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} @@ -32,8 +54,10 @@ public: 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. + Some platforms (currently wxGTK only, and see the remark in SetBitmap() + documentation) will also show standard bitmaps for stock menu items. - In fact, leaving at least @a text empty for the stock menu items is strongly + Leaving at least @a text empty for the stock menu items is actually strongly recommended as they will have appearance and keyboard interface (including standard accelerators) familiar to the user. @@ -50,7 +74,7 @@ public: helpMenu->Append(wxID_ABOUT); // use the stock label and the stock accelerator but not the stock help string: - helpMenu->Append(wxID_ABOUT, wxEmptyString, wxT("My custom help string")); + helpMenu->Append(wxID_ABOUT, "", "My custom help string"); // use all stock properties except for the bitmap: wxMenuItem *mymenu = new wxMenuItem(helpMenu, wxID_ABOUT); @@ -68,20 +92,19 @@ 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 - ampersand character in the menu item text, the ampersand must be doubled. + Text for the menu item, as shown on the menu. + See SetItemLabel() for more info. @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 + @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); @@ -102,24 +125,57 @@ public: virtual void Enable(bool enable = true); /** - Returns the background colour associated with the menu item (Windows only). + @deprecated This function is deprecated; please use GetLabelText() instead. + + @see GetLabelText() + */ + static wxString GetLabelFromText(const wxString& text); + + /** + Strips all accelerator characters and mnemonics from the given @a text. + For example: + + @code + wxMenuItem::GetLabelfromText("&Hello\tCtrl-h"); + @endcode + + will return just @c "Hello". + + @see GetItemLabelText(), GetItemLabel() */ - wxColour GetBackgroundColour() const; + static wxString GetLabelText(const wxString& text); + + + /** + @name Getters + */ + //@{ + + /** + Returns the background colour associated with the menu item. + + @onlyfor{wxmsw} + */ + wxColour& GetBackgroundColour() const; /** - Returns the checked or unchecked bitmap (Windows only). + Returns the checked or unchecked bitmap. + + @onlyfor{wxmsw} */ - wxBitmap GetBitmap(bool checked = true) const; + virtual const wxBitmap& GetBitmap() const; /** - Returns the font associated with the menu item (Windows only). + Returns the font associated with the menu item. + + @onlyfor{wxmsw} */ - wxFont GetFont() const; + wxFont& GetFont() const; /** Returns the help string associated with the menu item. */ - wxString GetHelp() const; + const wxString& GetHelp() const; /** Returns the menu item identifier. @@ -154,33 +210,14 @@ public: @deprecated This function is deprecated in favour of GetItemLabelText(). - @see GetText(), GetLabelFromText() + @see GetItemLabelText() */ 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 @a text. - For example: - - @code - wxMenuItem::GetLabelfromText("&Hello\tCtrl-h"); - @endcode - - will return just @c "Hello". - - @see GetItemLabelText(), GetItemLabel() - */ - static wxString GetLabelText(const wxString& text); - - /** - Gets the width of the menu item checkmark bitmap (Windows only). + Gets the width of the menu item checkmark bitmap. + + @onlyfor{wxmsw} */ int GetMarginWidth() const; @@ -193,9 +230,9 @@ public: /** Returns the text associated with the menu item. - @deprecated This function is deprecated. Please use - - GetItemLabel() or GetItemLabelText() instead. + @deprecated This function is deprecated. Please use GetItemLabel() or GetItemLabelText() instead. + + @see GetItemLabel(), GetItemLabelText() */ wxString GetName() const; @@ -210,17 +247,41 @@ public: @deprecated This function is deprecated in favour of GetItemLabel(). - @see GetLabel(), GetLabelFromText() + @see GetLabelFromText() */ - wxString GetText() const; + const wxString& GetText() const; /** - Returns the text colour associated with the menu item (Windows only). + Returns the text colour associated with the menu item. + + @onlyfor{wxmsw} + */ + wxColour& GetTextColour() const; + + //@} + + + + /** + @name Checkers */ - wxColour GetTextColour() const; + //@{ + + /** + Returns @true if the item is a check item. + + Unlike IsCheckable() this doesn't return @true for the radio buttons. + + @since 2.9.5 + */ + bool IsCheck() const; /** Returns @true if the item is checkable. + + Notice that the radio buttons are considered to be checkable as well, + so this method returns @true for them too. Use IsCheck() if you want to + test for the check items only. */ bool IsCheckable() const; @@ -234,6 +295,13 @@ public: */ virtual bool IsEnabled() const; + /** + Returns @true if the item is a radio button. + + @since 2.9.5 + */ + bool IsRadio() const; + /** Returns @true if the item is a separator. */ @@ -243,27 +311,57 @@ public: Returns @true if the item is a submenu. */ bool IsSubMenu() const; + + //@} + + + + /** + @name Setters + */ + //@{ /** - Sets the background colour associated with the menu item (Windows only). + Sets the background colour associated with the menu item. + + @onlyfor{wxmsw} */ - void SetBackgroundColour(const wxColour& colour) const; + void SetBackgroundColour(const wxColour& colour); /** - 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. + + SetBitmap() must be called before the item is appended to the menu, + i.e. appending the item without a bitmap and setting one later is not + guaranteed to work. But the bitmap can be changed or reset later if it + had been set up initially. + + Notice that GTK+ uses a global setting called @c gtk-menu-images to + determine if the images should be shown in the menus at all. If it is + off (which is the case in e.g. Gnome 2.28 by default), no images will + be shown, consistently with the native behaviour. + + @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). + 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 font associated with the menu item (Windows only). + Sets the font associated with the menu item. + + @onlyfor{wxmsw} */ void SetFont(const wxFont& font); @@ -274,34 +372,101 @@ public: /** Sets the label associated with the menu item. + + Note that if the ID of this menu item corresponds to a stock ID, then it is + not necessary to specify a label: wxWidgets will automatically use the stock + item label associated with that ID. See the @ref wxMenuItem::wxMenuItem "constructor" + for more info. + + The label string for the normal menu items (not separators) may include the + accelerator which can be used to activate the menu item from keyboard. + An accelerator key can be specified using the ampersand & character. + In order to embed an ampersand character in the menu item text, the ampersand + must be doubled. + + Optionally you can specify also an accelerator string appending a tab character + \\t followed by a valid key combination (e.g. CTRL+V). + Its general syntax is any combination of @c "CTRL", @c "RAWCTRL", @c + "ALT" and @c "SHIFT" strings (case doesn't matter) separated by either + @c '-' or @c '+' characters and followed by the accelerator itself. + Notice that @c CTRL corresponds to the "Ctrl" key on most platforms but + not under Mac OS where it is mapped to "Cmd" key on Mac keyboard. + Usually this is exactly what you want in portable code but if you + really need to use the (rarely used for this purpose) "Ctrl" key even + under Mac, you may use @c RAWCTRL to prevent this mapping. Under the + other platforms @c RAWCTRL is the same as plain @c CTRL. + + The accelerator may be any alphanumeric character, any function key + (from F1 to F12) or one of the special characters listed in the table + below (again, case doesn't matter): + - @c DEL or @c DELETE: Delete key + - @c BACK : Backspace key + - @c INS or @c INSERT: Insert key + - @c ENTER or @c RETURN: Enter key + - @c PGUP: PageUp key + - @c PGDN: PageDown key + - @c LEFT: Left cursor arrow key + - @c RIGHT: Right cursor arrow key + - @c UP: Up cursor arrow key + - @c DOWN: Down cursor arrow key + - @c HOME: Home key + - @c END: End key + - @c SPACE: Space + - @c TAB: Tab key + - @c ESC or @c ESCAPE: Escape key (Windows only) + + Examples: + + @code + m_pMyMenuItem->SetItemLabel("My &item\tCTRL+I"); + m_pMyMenuItem2->SetItemLabel("Clean && build\tF7"); + m_pMyMenuItem3->SetItemLabel("Simple item"); + m_pMyMenuItem4->SetItemLabel("Item with &accelerator"); + @endcode + + @note In wxGTK using @c "SHIFT" with non-alphabetic characters + currently doesn't work, even in combination with other modifiers, due + to GTK+ limitation. E.g. @c Shift+Ctrl+A works but @c Shift+Ctrl+1 or + @c Shift+/ do not, so avoid using accelerators of this form in portable + code. + + @see GetItemLabel(), GetItemLabelText() */ virtual void SetItemLabel(const wxString& label); /** - Sets the width of the menu item checkmark bitmap (Windows only). + Sets the width of the menu item checkmark bitmap. + + @onlyfor{wxmsw} */ - void SetMarginWidth(int width) const; + void SetMarginWidth(int width); /** 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(). + + @see SetItemLabel(). */ virtual void SetText(const wxString& text); /** - Sets the text colour associated with the menu item (Windows only). + Sets the text colour associated with the menu item. + + @onlyfor{wxmsw} */ void SetTextColour(const wxColour& colour); + + //@} };