X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/8d2d37d26864154a55049707c5a693a61f707230..dc73d7f5d468881a9cbb71f1a234f364ff52ceaa:/interface/wx/menu.h diff --git a/interface/wx/menu.h b/interface/wx/menu.h index f1c9b97d05..d1df2b809f 100644 --- a/interface/wx/menu.h +++ b/interface/wx/menu.h @@ -3,7 +3,7 @@ // Purpose: interface of wxMenuBar // Author: wxWidgets team // RCS-ID: $Id$ -// Licence: wxWindows license +// Licence: wxWindows licence ///////////////////////////////////////////////////////////////////////////// /** @@ -53,6 +53,10 @@ public: the menu bar. @param style If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). + + @beginWxPerlOnly + Not supported by wxPerl. + @endWxPerlOnly */ wxMenuBar(size_t n, wxMenu* menus[], const wxString titles[], long style = 0); @@ -69,7 +73,7 @@ public: @param menu The menu to add. Do not deallocate this menu after calling Append(). @param title - The title of the menu. + The title of the menu, must be non-empty. @return @true on success, @false if an error occurred. @@ -124,8 +128,14 @@ public: If not @NULL, menu will get set to the associated menu. @return The found menu item object, or @NULL if one was not found. + + @beginWxPerlOnly + In wxPerl this method takes just the @a id parameter; + in scalar context it returns the associated @c Wx::MenuItem, in list + context it returns a 2-element list (item, submenu). + @endWxPerlOnly */ - virtual wxMenuItem* FindItem(int id, wxMenu* menu = NULL) const; + virtual wxMenuItem* FindItem(int id, wxMenu** menu = NULL) const; /** Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no @@ -363,6 +373,28 @@ public: @remarks Use only after the menubar has been associated with a frame. */ virtual void SetMenuLabel(size_t pos, const wxString& label); + + /** + Enables you to set the global menubar on Mac, that is, the menubar displayed + when the app is running without any frames open. + + @param menubar + The menubar to set. + + @remarks Only exists on Mac, other platforms do not have this method. + */ + static void MacSetCommonMenuBar(wxMenuBar* menubar); + + /** + Enables you to get the global menubar on Mac, that is, the menubar displayed + when the app is running without any frames open. + + @return The global menubar. + + @remarks Only exists on Mac, other platforms do not have this method. + */ + static wxMenuBar* MacGetCommonMenuBar(); + }; @@ -376,8 +408,9 @@ public: A menu item has an integer ID associated with it which can be used to identify the selection, or to change the menu item in some way. A menu item - with a special identifier -1 is a separator item and doesn't have an - associated command but just makes a separator line appear in the menu. + with a special identifier @e wxID_SEPARATOR is a separator item and doesn't + have an associated command but just makes a separator line appear in the + menu. @note Please note that @e wxID_ABOUT and @e wxID_EXIT are predefined by wxWidgets @@ -406,9 +439,13 @@ public: @section menu_allocation Allocation strategy - All menus except the popup ones must be created on the @b heap. - All menus attached to a menubar or to another menu will be deleted by their - parent when it is deleted. + All menus must be created on the @b heap because all menus attached to a + menubar or to another menu will be deleted by their parent when it is + deleted. The only exception to this rule are the popup menus (i.e. menus + used with wxWindow::PopupMenu()) as wxWidgets does not destroy them to + allow reusing the same menu more than once. But the exception applies only + to the menus themselves and not to any submenus of popup menus which are + still destroyed by wxWidgets as usual and so must be heap-allocated. As the frame menubar is deleted by the frame itself, it means that normally all menus used are deleted automatically. @@ -438,6 +475,12 @@ public: class wxMenu : public wxEvtHandler { public: + + /** + Constructs a wxMenu object. + */ + wxMenu(); + /** Constructs a wxMenu object. @@ -476,45 +519,27 @@ public: The menu command identifier. @param item The string to appear on the menu item. + See wxMenuItem::SetItemLabel() for more details. @param helpString An optional help string associated with the item. - By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays + By default, the handler for the @c wxEVT_MENU_HIGHLIGHT event displays this string in the status line. @param kind - May be wxITEM_SEPARATOR, wxITEM_NORMAL, wxITEM_CHECK or wxITEM_RADIO + May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or @c wxITEM_RADIO. + + Example: + @code + m_pFileMenu->Append(ID_NEW_FILE, "&New file\tCTRL+N", "Creates a new XYZ document"); + @endcode + or even better for stock menu items (see wxMenuItem::wxMenuItem): + @code + m_pFileMenu->Append(wxID_NEW, "", "Creates a new XYZ document"); + @endcode @remarks This command can be used after the menu has been shown, as well as on initial creation of a menu or menubar. - The item string for the normal menu items (not submenus or separators) - may include the accelerator which can be used to activate the menu item - from keyboard. - The accelerator string follows the item label and is separated from it - by a TAB character ('\\t'). - - Its general syntax is any combination of "CTRL", "ALT" and "SHIFT" strings - (case doesn't matter) separated by either '-' or '+' characters and followed - by the accelerator itself. - 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): - - - DEL or DELETE: Delete key - - INS or INSERT: Insert key - - ENTER or RETURN: Enter key - - PGUP: PageUp key - - PGDN: PageDown key - - LEFT: Left cursor arrow key - - RIGHT: Right cursor arrow key - - UP: Up cursor arrow key - - DOWN: Down cursor arrow key - - HOME: Home key - - END: End key - - SPACE: Space - - TAB: Tab key - - ESC: or ESCAPE Escape key (Windows only) - @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), AppendSubMenu(), Insert(), SetLabel(), GetHelpString(), SetHelpString(), wxMenuItem @@ -536,7 +561,7 @@ public: Pull-right submenu. @param helpString An optional help string associated with the item. - By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays + By default, the handler for the @c wxEVT_MENU_HIGHLIGHT event displays this string in the status line. @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), @@ -650,7 +675,7 @@ public: @param id Id of the menu item to be deleted. - @see FindItem(), Deletes(), Remove() + @see FindItem(), Delete(), Remove() */ bool Destroy(int id); @@ -662,7 +687,7 @@ public: @param item Menu item to be deleted. - @see FindItem(), Deletes(), Remove() + @see FindItem(), Delete(), Remove() */ bool Destroy(wxMenuItem* item); @@ -784,9 +809,6 @@ public: /** Returns the title of the menu. - @remarks This is relevant only to popup menus, use - wxMenuBar::GetMenuLabel for the menus in the menubar. - @see SetTitle() */ const wxString& GetTitle() const; @@ -799,7 +821,7 @@ public: @see Append(), Prepend() */ - wxMenuItem* Insert(size_t pos, wxMenuItem* item); + wxMenuItem* Insert(size_t pos, wxMenuItem* menuItem); /** Inserts the given @a item before the position @a pos. @@ -956,8 +978,9 @@ public: @param title The title to set. - @remarks This is relevant only to popup menus, use - wxMenuBar::SetLabelTop for the menus in the menubar. + @remarks Notice that you can only call this method directly for the + popup menus, to change the title of a menu that is part of a menu + bar you need to use wxMenuBar::SetLabelTop(). @see GetTitle() */