X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3e083d652da78616c08dad6ecb3ebd347390d3f4..d3fa4bc22e84e3ca4d88cc1772f2d414140a1017:/interface/wx/menu.h diff --git a/interface/wx/menu.h b/interface/wx/menu.h index f0d5009d50..a6b5cbe0d9 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. @@ -103,6 +107,16 @@ public: */ void Enable(int id, bool enable); + /** + Returns true if the menu with the given index is enabled. + + @param pos + The menu position (0-based) + + @since 2.9.4 + */ + bool IsEnabledTop(size_t pos) const; + /** Enables or disables a whole menu. @@ -124,8 +138,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 +383,37 @@ 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. + + @onlyfor{wxosx} + */ + 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. + + @onlyfor{wxosx} + */ + static wxMenuBar* MacGetCommonMenuBar(); + + wxFrame *GetFrame() const; + bool IsAttached() const; + virtual void Attach(wxFrame *frame); + virtual void Detach(); + }; @@ -376,15 +427,15 @@ 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 and have a special meaning since entries using these IDs will be taken out of the normal menus under MacOS X and will be inserted into the system menu (following the appropriate MacOS X interface guideline). - On PalmOS @e wxID_EXIT is disabled according to Palm OS Companion guidelines. Menu items may be either @e normal items, @e check items or @e radio items. Normal items don't have any special properties while the check items have a @@ -406,9 +457,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. @@ -419,7 +474,7 @@ public: If the menu is part of a menubar, then wxMenuBar event processing is used. With a popup menu (see wxWindow::PopupMenu), there is a variety of ways to - handle a menu selection event (@c wxEVT_COMMAND_MENU_SELECTED): + handle a menu selection event (@c wxEVT_MENU): - Provide @c EVT_MENU handlers in the window which pops up the menu, or in an ancestor of that window (the simplest method); - Derive a new class from wxMenu and define event table entries using the @c EVT_MENU macro; @@ -427,7 +482,7 @@ public: specifying an object whose class has @c EVT_MENU entries; Note that instead of static @c EVT_MENU macros you can also use dynamic - connection; see @ref overview_events_connect. + connection; see @ref overview_events_bind. @library{wxcore} @category{menus} @@ -438,6 +493,12 @@ public: class wxMenu : public wxEvtHandler { public: + + /** + Constructs a wxMenu object. + */ + wxMenu(); + /** Constructs a wxMenu object. @@ -476,45 +537,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 +579,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 +693,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 +705,7 @@ public: @param item Menu item to be deleted. - @see FindItem(), Deletes(), Remove() + @see FindItem(), Delete(), Remove() */ bool Destroy(wxMenuItem* item); @@ -777,16 +820,13 @@ public: wxMenuItemList is a pseudo-template list class containing wxMenuItem pointers, see wxList. */ - wxMenuItemList& GetMenuItems() const; + wxMenuItemList& GetMenuItems(); const wxMenuItemList& GetMenuItems() const; //@} /** 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 +839,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. @@ -862,7 +902,7 @@ public: bool IsEnabled(int id) const; /** - Inserts the given @a item at position 0, i.e. before all the other + Inserts the given @a item at position 0, i.e.\ before all the other existing items. @see Append(), Insert() @@ -870,7 +910,7 @@ public: wxMenuItem* Prepend(wxMenuItem* item); /** - Inserts the given @a item at position 0, i.e. before all the other + Inserts the given @a item at position 0, i.e.\ before all the other existing items. @see Append(), Insert() @@ -956,8 +996,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() */ @@ -971,5 +1012,18 @@ public: but the application may call it at other times if required. */ void UpdateUI(wxEvtHandler* source = NULL); + + + void SetInvokingWindow(wxWindow *win); + wxWindow *GetInvokingWindow() const; + wxWindow *GetWindow() const; + long GetStyle() const; + void SetParent(wxMenu *parent); + wxMenu *GetParent() const; + + virtual void Attach(wxMenuBar *menubar); + virtual void Detach(); + bool IsAttached() const; + };