X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/8d2d37d26864154a55049707c5a693a61f707230..4d98817cfab2654773755cb5c540057c5f3d4fd6:/interface/wx/menu.h diff --git a/interface/wx/menu.h b/interface/wx/menu.h index f1c9b97d05..5cbee4bc0a 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,6 +128,12 @@ 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; @@ -376,8 +386,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 +417,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. @@ -476,45 +491,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 +533,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 +647,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 +659,7 @@ public: @param item Menu item to be deleted. - @see FindItem(), Deletes(), Remove() + @see FindItem(), Delete(), Remove() */ bool Destroy(wxMenuItem* item); @@ -784,9 +781,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; @@ -956,8 +950,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() */