// Purpose: interface of wxMenuBar
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
@library{wxcore}
@category{menus}
- @see wxMenu, @ref overview_eventhandling
+ @see wxMenu, @ref overview_events
*/
class wxMenuBar : public wxWindow
{
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);
@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.
*/
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.
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
@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();
+
};
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
@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.
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;
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_eventhandling_connect.
+ connection; see @ref overview_events_bind.
@library{wxcore}
@category{menus}
- @see wxMenuBar, wxWindow::PopupMenu, @ref overview_eventhandling,
+ @see wxMenuBar, wxWindow::PopupMenu, @ref overview_events,
@ref wxFileHistory "wxFileHistory (most recently used files menu)"
*/
class wxMenu : public wxEvtHandler
{
public:
+
+ /**
+ Constructs a wxMenu object.
+ */
+ wxMenu();
+
/**
Constructs a wxMenu object.
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
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(),
@param id
Id of the menu item to be deleted.
- @see FindItem(), Deletes(), Remove()
+ @see FindItem(), Delete(), Remove()
*/
bool Destroy(int id);
@param item
Menu item to be deleted.
- @see FindItem(), Deletes(), Remove()
+ @see FindItem(), Delete(), Remove()
*/
bool Destroy(wxMenuItem* item);
*/
void Enable(int id, bool enable);
+ /**
+ Finds the menu item object associated with the given menu item identifier
+ and, optionally, the position of the item in the menu.
+
+ Unlike FindItem(), this function doesn't recurse but only looks at the
+ direct children of this menu.
+
+ @param id
+ The identifier of the menu item to find.
+ @param pos
+ If the pointer is not @NULL, it is filled with the item's position if
+ it was found or @c (size_t)wxNOT_FOUND otherwise.
+ @return
+ Menu item object or @NULL if not found.
+ */
+ wxMenuItem *FindChildItem(int id, size_t *pos = NULL) const;
+
/**
Finds the menu id for a menu item string.
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;
@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.
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()
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()
@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()
*/
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;
+
};
projects / wxWidgets.git / blobdiff