X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/7c913512a4c9f36e11e07ea707002fab1608d324..27608f1130d577131674dc546b62ef11f75226d1:/interface/menu.h?ds=sidebyside diff --git a/interface/menu.h b/interface/menu.h index 537679b5ec..f19fc4ca04 100644 --- a/interface/menu.h +++ b/interface/menu.h @@ -1,6 +1,6 @@ ///////////////////////////////////////////////////////////////////////////// // Name: menu.h -// Purpose: documentation for wxMenuBar class +// Purpose: interface of wxMenuBar // Author: wxWidgets team // RCS-ID: $Id$ // Licence: wxWindows license @@ -15,33 +15,35 @@ @library{wxcore} @category{menus} - @seealso - wxMenu, @ref overview_eventhandlingoverview "Event handling overview" + @see wxMenu, @ref overview_eventhandling "Event Handling Overview" */ class wxMenuBar : public wxWindow { public: - //@{ + /** + Construct an empty menu barM + + @param style + If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). + */ + wxMenuBar(long style = 0); + /** Construct a menu bar from arrays of menus and titles. - + @param n - The number of menus. - + The number of menus. @param menus - An array of menus. Do not use this array again - it now belongs to the - menu bar. - + An array of menus. Do not use this array again - it now belongs to + the menu bar. @param titles - An array of title strings. Deallocate this array after creating the menu bar. - + An array of title strings. Deallocate this array after creating + the menu bar. @param style - If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). + If wxMB_DOCKABLE the menu bar can be detached (wxGTK only). */ - wxMenuBar(long style = 0); wxMenuBar(size_t n, wxMenu* menus[], const wxString titles[], long style = 0); - //@} /** Destructor, destroying the menu bar and removing it from the parent frame (if @@ -51,222 +53,214 @@ public: /** Adds the item to the end of the menu bar. - + @param menu - The menu to add. Do not deallocate this menu after calling Append. - + The menu to add. Do not deallocate this menu after calling Append. @param title - The title of the menu. - - @returns @true on success, @false if an error occurred. - - @sa Insert() + The title of the menu. + + @return @true on success, @false if an error occurred. + + @see Insert() */ - bool Append(wxMenu * menu, const wxString& title); + bool Append(wxMenu* menu, const wxString& title); /** Checks or unchecks a menu item. - + @param id - The menu item identifier. - + The menu item identifier. @param check - If @true, checks the menu item, otherwise the item is unchecked. - + If @true, checks the menu item, otherwise the item is unchecked. + @remarks Only use this when the menu bar has been associated with a - frame; otherwise, use the wxMenu equivalent call. + frame; otherwise, use the wxMenu equivalent call. */ void Check(int id, const bool check); /** Enables or disables (greys out) a menu item. - + @param id - The menu item identifier. - + The menu item identifier. @param enable - @true to enable the item, @false to disable it. - + @true to enable the item, @false to disable it. + @remarks Only use this when the menu bar has been associated with a - frame; otherwise, use the wxMenu equivalent call. + frame; otherwise, use the wxMenu equivalent call. */ void Enable(int id, const bool enable); /** Enables or disables a whole menu. - + @param pos - The position of the menu, starting from zero. - + The position of the menu, starting from zero. @param enable - @true to enable the menu, @false to disable it. - + @true to enable the menu, @false to disable it. + @remarks Only use this when the menu bar has been associated with a frame. */ void EnableTop(int pos, const bool enable); /** Finds the menu item object associated with the given menu item identifier. - + @param id - Menu item identifier. - + Menu item identifier. @param menu - If not @NULL, menu will get set to the associated menu. - - @returns The found menu item object, or @NULL if one was not found. + If not @NULL, menu will get set to the associated menu. + + @return The found menu item object, or @NULL if one was not found. */ - wxMenuItem * FindItem(int id, wxMenu menu = @NULL); + wxMenuItem* FindItem(int id, wxMenu menu = NULL) const; /** - Returns the index of the menu with the given @e title or @c wxNOT_FOUND if no - such menu exists in this menubar. The @e title parameter may specify either + Returns the index of the menu with the given @a title or @c wxNOT_FOUND if no + such menu exists in this menubar. The @a title parameter may specify either the menu title (with accelerator characters, i.e. @c "File") or just the menu label (@c "File") indifferently. */ - int FindMenu(const wxString& title); + int FindMenu(const wxString& title) const; /** Finds the menu item id for a menu name/menu item string pair. - + @param menuString - Menu title to find. - + Menu title to find. @param itemString - Item to find. - - @returns The menu item identifier, or wxNOT_FOUND if none was found. - + Item to find. + + @return The menu item identifier, or wxNOT_FOUND if none was found. + @remarks Any special menu codes are stripped out of source and target - strings before matching. + strings before matching. */ int FindMenuItem(const wxString& menuString, - const wxString& itemString); + const wxString& itemString) const; /** Gets the help string associated with the menu item identifier. - + @param id - The menu item identifier. - - @returns The help string, or the empty string if there was no help string - or the menu item was not found. - - @sa SetHelpString() + The menu item identifier. + + @return The help string, or the empty string if there was no help string + or the menu item was not found. + + @see SetHelpString() */ - wxString GetHelpString(int id); + wxString GetHelpString(int id) const; /** Gets the label associated with a menu item. - + @param id - The menu item identifier. - - @returns The menu item label, or the empty string if the item was not - found. - + The menu item identifier. + + @return The menu item label, or the empty string if the item was not + found. + @remarks Use only after the menubar has been associated with a frame. */ - wxString GetLabel(int id); + wxString GetLabel(int id) const; /** Returns the label of a top-level menu. Note that the returned string does not include the accelerator characters which could have been specified in the menu title string during its construction. - + @param pos - Position of the menu on the menu bar, starting from zero. - - @returns The menu label, or the empty string if the menu was not found. - + Position of the menu on the menu bar, starting from zero. + + @return The menu label, or the empty string if the menu was not found. + @remarks Use only after the menubar has been associated with a frame. - - @sa SetLabelTop() + + @see SetLabelTop() */ - wxString GetLabelTop(int pos); + wxString GetLabelTop(int pos) const; /** - Returns the menu at @e menuIndex (zero-based). + Returns the menu at @a menuIndex (zero-based). */ - wxMenu* GetMenu(int menuIndex); + wxMenu* GetMenu(int menuIndex) const; /** Returns the number of menus in this menubar. */ - size_t GetMenuCount(); + size_t GetMenuCount() const; /** Returns the label of a top-level menu. Note that the returned string includes the accelerator characters that have been specified in the menu title string during its construction. - + @param pos - Position of the menu on the menu bar, starting from zero. - - @returns The menu label, or the empty string if the menu was not found. - + Position of the menu on the menu bar, starting from zero. + + @return The menu label, or the empty string if the menu was not found. + @remarks Use only after the menubar has been associated with a frame. - - @sa GetMenuLabelText(), SetMenuLabel() + + @see GetMenuLabelText(), SetMenuLabel() */ - wxString GetMenuLabel(int pos); + wxString GetMenuLabel(int pos) const; /** Returns the label of a top-level menu. Note that the returned string does not include any accelerator characters that may have been specified in the menu title string during its construction. - + @param pos - Position of the menu on the menu bar, starting from zero. - - @returns The menu label, or the empty string if the menu was not found. - + Position of the menu on the menu bar, starting from zero. + + @return The menu label, or the empty string if the menu was not found. + @remarks Use only after the menubar has been associated with a frame. - - @sa GetMenuLabel(), SetMenuLabel() + + @see GetMenuLabel(), SetMenuLabel() */ - wxString GetMenuLabelText(int pos); + wxString GetMenuLabelText(int pos) const; /** Inserts the menu at the given position into the menu bar. Inserting menu at position 0 will insert it in the very beginning of it, inserting at position GetMenuCount() is the same as calling Append(). - + @param pos - The position of the new menu in the menu bar - + The position of the new menu in the menu bar @param menu - The menu to add. wxMenuBar owns the menu and will free it. - + The menu to add. wxMenuBar owns the menu and will free it. @param title - The title of the menu. - - @returns @true on success, @false if an error occurred. - - @sa Append() + The title of the menu. + + @return @true on success, @false if an error occurred. + + @see Append() */ - bool Insert(size_t pos, wxMenu * menu, const wxString& title); + bool Insert(size_t pos, wxMenu* menu, const wxString& title); /** Determines whether an item is checked. - + @param id - The menu item identifier. - - @returns @true if the item was found and is checked, @false otherwise. + The menu item identifier. + + @return @true if the item was found and is checked, @false otherwise. */ - bool IsChecked(int id); + bool IsChecked(int id) const; /** Determines whether an item is enabled. - + @param id - The menu item identifier. - - @returns @true if the item was found and is enabled, @false otherwise. + The menu item identifier. + + @return @true if the item was found and is enabled, @false otherwise. */ - bool IsEnabled(int id); + bool IsEnabled(int id) const; /** Redraw the menu bar @@ -278,89 +272,83 @@ public: responsible for deleting it. This function may be used together with Insert() to change the menubar dynamically. - - @sa Replace() + + @see Replace() */ - wxMenu * Remove(size_t pos); + wxMenu* Remove(size_t pos); /** Replaces the menu at the given position with another one. - + @param pos - The position of the new menu in the menu bar - + The position of the new menu in the menu bar @param menu - The menu to add. - + The menu to add. @param title - The title of the menu. - - @returns The menu which was previously at position pos. The caller is - responsible for deleting it. - - @sa Insert(), Remove() + The title of the menu. + + @return The menu which was previously at position pos. The caller is + responsible for deleting it. + + @see Insert(), Remove() */ - wxMenu * Replace(size_t pos, wxMenu * menu, - const wxString& title); + wxMenu* Replace(size_t pos, wxMenu* menu, const wxString& title); /** Sets the help string associated with a menu item. - + @param id - Menu item identifier. - + Menu item identifier. @param helpString - Help string to associate with the menu item. - - @sa GetHelpString() + Help string to associate with the menu item. + + @see GetHelpString() */ void SetHelpString(int id, const wxString& helpString); /** Sets the label of a menu item. - + @param id - Menu item identifier. - + Menu item identifier. @param label - Menu item label. - + Menu item label. + @remarks Use only after the menubar has been associated with a frame. - - @sa GetLabel() + + @see GetLabel() */ void SetLabel(int id, const wxString& label); /** Sets the label of a top-level menu. - + @param pos - The position of a menu on the menu bar, starting from zero. - + The position of a menu on the menu bar, starting from zero. @param label - The menu label. - + The menu label. + @remarks Use only after the menubar has been associated with a frame. - - @sa GetLabelTop() + + @see GetLabelTop() */ void SetLabelTop(int pos, const wxString& label); /** Sets the label of a top-level menu. - + @param pos - The position of a menu on the menu bar, starting from zero. - + The position of a menu on the menu bar, starting from zero. @param label - The menu label. - + The menu label. + @remarks Use only after the menubar has been associated with a frame. */ void SetMenuLabel(int pos, const wxString& label); }; + /** @class wxMenu @wxheader{menu.h} @@ -374,7 +362,7 @@ public: 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. - @b NB: Please note that @e wxID_ABOUT and @e wxID_EXIT are + @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 @@ -402,27 +390,33 @@ public: @library{wxcore} @category{menus} - @seealso - wxMenuBar, wxWindow::PopupMenu, @ref overview_eventhandlingoverview "Event - handling overview", @ref overview_wxfilehistory "wxFileHistory (most recently used files menu)" + @see wxMenuBar, wxWindow::PopupMenu, + @ref overview_eventhandling "Event Handling Overview", + @ref wxFileHistory "wxFileHistory (most recently used files menu)" */ class wxMenu : public wxEvtHandler { public: - //@{ /** Constructs a wxMenu object. - + @param style - If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only). + If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only). */ - wxMenu(const wxString& title = "", long style = 0); wxMenu(long style); - //@} + /** + Constructs a wxMenu object with a title + + @param title + Title at the top of the menu (not always supported). + @param style + If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only). + */ + wxMenu(const wxString& title = "", long style = 0); + /** Destructor, destroying the menu. - Note: under Motif, a popup menu must have a valid parent (the window it was last popped up on) when being destroyed. Therefore, make sure you delete or re-use the popup menu @e before destroying the @@ -432,55 +426,73 @@ public: */ ~wxMenu(); - //@{ /** - Adds a menu item object. This is the most generic variant of Append() method - because it may be used for both items (including separators) and submenus and - because you can also specify various extra properties of a menu item this way, - such as bitmaps and fonts. - + Adds a menu item. + @param id - The menu command identifier. - + The menu command identifier. @param item - The string to appear on the menu item. - - @param menu - Pull-right submenu. - - @param kind - May be wxITEM_SEPARATOR, wxITEM_NORMAL, - wxITEM_CHECK or wxITEM_RADIO - + The string to appear on the menu item. @param helpString - An optional help string associated with the item. - By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays - this string in the status line. - - @param menuItem - A menuitem object. It will be owned by the wxMenu object after this function - is called, so do not delete it yourself. - - @remarks This command can be used after the menu has been shown, as well - as on initial creation of a menu or menubar. - - @sa AppendSeparator(), AppendCheckItem(), AppendRadioItem(), - AppendSubMenu(), Insert(), SetLabel(), - GetHelpString(), SetHelpString(), wxMenuItem - */ - wxMenuItem* Append(int id, const wxString& item = "", - const wxString& helpString = "", + An optional help string associated with the item. + By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays + this string in the status line. + @param kind + May be wxITEM_SEPARATOR, wxITEM_NORMAL, + wxITEM_CHECK or wxITEM_RADIO + + @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), + AppendSubMenu(), Insert(), SetLabel(), + GetHelpString(), SetHelpString(), wxMenuItem + */ + wxMenuItem* Append(int id, const wxString& item = wxEmptyString, + const wxString& helpString = wxEmptyString, wxItemKind kind = wxITEM_NORMAL); + + /** + Adds a submenu. + + @deprecated This function is deprecated, use AppendSubMenu() instead. + + @param id + The menu command identifier. + @param item + The string to appear on the menu item. + @param subMenu + Pull-right submenu. + @param helpString + An optional help string associated with the item. + By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays + this string in the status line. + + @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), + AppendSubMenu(), Insert(), SetLabel(), + GetHelpString(), SetHelpString(), wxMenuItem + */ wxMenuItem* Append(int id, const wxString& item, - wxMenu * subMenu, - const wxString& helpString = ""); + wxMenu* subMenu, + const wxString& helpString = wxEmptyString); + + /** + Adds a menu item object. This is the most generic variant of Append() method + because it may be used for both items (including separators) and submenus and + because you can also specify various extra properties of a menu item this way, + such as bitmaps and fonts. + + @param menuItem + A menuitem object. It will be owned by the wxMenu object after this function + is called, so do not delete it yourself. + + @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(), + AppendSubMenu(), Insert(), SetLabel(), + GetHelpString(), SetHelpString(), wxMenuItem + */ wxMenuItem* Append(wxMenuItem* menuItem); - //@} /** Adds a checkable item to the end of the menu. - - @sa Append(), InsertCheckItem() + + @see Append(), InsertCheckItem() */ wxMenuItem* AppendCheckItem(int id, const wxString& item, const wxString& helpString = ""); @@ -489,27 +501,26 @@ public: Adds a radio item to the end of the menu. All consequent radio items form a group and when an item in the group is checked, all the others are automatically unchecked. - - @sa Append(), InsertRadioItem() + + @see Append(), InsertRadioItem() */ wxMenuItem* AppendRadioItem(int id, const wxString& item, const wxString& helpString = ""); /** Adds a separator to the end of the menu. - - @sa Append(), InsertSeparator() + + @see Append(), InsertSeparator() */ wxMenuItem* AppendSeparator(); /** - Adds the given @e submenu to this menu. @e text is the text shown in the - menu for it and @e help is the help string shown in the status bar when the + Adds the given @a submenu to this menu. @a text is the text shown in the + menu for it and @a help is the help string shown in the status bar when the submenu item is selected. */ - wxMenuItem * AppendSubMenu(wxMenu * submenu, - const wxString& text, - const wxString& help = wxEmptyString); + wxMenuItem* AppendSubMenu(wxMenu* submenu, const wxString& text, + const wxString& help = wxEmptyString); /** Inserts a break in a menu, causing the next appended item to appear in a new @@ -519,174 +530,190 @@ public: /** Checks or unchecks the menu item. - + @param id - The menu item identifier. - + The menu item identifier. @param check - If @true, the item will be checked, otherwise it will be unchecked. - - @sa IsChecked() + If @true, the item will be checked, otherwise it will be unchecked. + + @see IsChecked() */ void Check(int id, const bool check); - //@{ /** Deletes the menu item from the menu. If the item is a submenu, it will - @b not be deleted. Use Destroy() if you want to - delete a submenu. - + @b not be deleted. Use Destroy() if you want to delete a submenu. + @param id - Id of the menu item to be deleted. - - @param item - Menu item to be deleted. - - @sa FindItem(), Destroy(), Remove() + Id of the menu item to be deleted. + + @see FindItem(), Destroy(), Remove() */ void Delete(int id); - void Delete(wxMenuItem * item); - //@} - //@{ /** Deletes the menu item from the menu. If the item is a submenu, it will - be deleted. Use Remove() if you want to keep the submenu - (for example, to reuse it later). - - @param id - Id of the menu item to be deleted. - + @b not be deleted. Use Destroy() if you want to delete a submenu. + @param item - Menu item to be deleted. - - @sa FindItem(), Deletes(), Remove() + Menu item to be deleted. + + @see FindItem(), Destroy(), Remove() + */ + void Delete(wxMenuItem* item); + + /** + Deletes the menu item from the menu. If the item is a submenu, it will + be deleted. Use Remove() if you want to keep the submenu (for example, + to reuse it later). + + @param id + Id of the menu item to be deleted. + + @see FindItem(), Deletes(), Remove() */ void Destroy(int id); - void Destroy(wxMenuItem * item); - //@} + + /** + Deletes the menu item from the menu. If the item is a submenu, it will + be deleted. Use Remove() if you want to keep the submenu (for example, + to reuse it later). + + @param item + Menu item to be deleted. + + @see FindItem(), Deletes(), Remove() + */ + void Destroy(wxMenuItem* item); /** Enables or disables (greys out) a menu item. - + @param id - The menu item identifier. - + The menu item identifier. @param enable - @true to enable the menu item, @false to disable it. - - @sa IsEnabled() + @true to enable the menu item, @false to disable it. + + @see IsEnabled() */ void Enable(int id, const bool enable); - //@{ + /** + Finds the menu id for a menu item string. + + @param itemString + Menu item string to find. + + @return Menu item identifier, or wxNOT_FOUND if none is found. + + @remarks Any special menu codes are stripped out of source and target + strings before matching. + */ + int FindItem(const wxString& itemString) const; + /** Finds the menu item object associated with the given menu item identifier and, optionally, the (sub)menu it belongs to. - - @param itemString - Menu item string to find. - + @param id - Menu item identifier. - + Menu item identifier. @param menu - If the pointer is not @NULL, it will be filled with the item's - parent menu (if the item was found) - - @returns First form: menu item identifier, or wxNOT_FOUND if none is - found. - - @remarks Any special menu codes are stripped out of source and target - strings before matching. + If the pointer is not @NULL, it will be filled with the item's + parent menu (if the item was found) + + @return Menu item object or NULL if none is found. */ - int FindItem(const wxString& itemString); - wxMenuItem * FindItem(int id, wxMenu ** menu = @NULL); - //@} + const wxMenuItem * FindItem(int id, wxMenu** menu = NULL) const; /** Returns the wxMenuItem given a position in the menu. */ - wxMenuItem* FindItemByPosition(size_t position); + wxMenuItem* FindItemByPosition(size_t position) const; /** Returns the help string associated with a menu item. - + @param id - The menu item identifier. - - @returns The help string, or the empty string if there is no help string - or the item was not found. - - @sa SetHelpString(), Append() + The menu item identifier. + + @return The help string, or the empty string if there is no help string + or the item was not found. + + @see SetHelpString(), Append() */ - wxString GetHelpString(int id); + wxString GetHelpString(int id) const; /** Returns a menu item label. - + @param id - The menu item identifier. - - @returns The item label, or the empty string if the item was not found. - - @sa GetLabelText(), SetLabel() + The menu item identifier. + + @return The item label, or the empty string if the item was not found. + + @see GetLabelText(), SetLabel() */ - wxString GetLabel(int id); + wxString GetLabel(int id) const; /** Returns a menu item label, without any of the original mnemonics and accelerators. - + @param id - The menu item identifier. - - @returns The item label, or the empty string if the item was not found. - - @sa GetLabel(), SetLabel() + The menu item identifier. + + @return The item label, or the empty string if the item was not found. + + @see GetLabel(), SetLabel() */ - wxString GetLabelText(int id); + wxString GetLabelText(int id) const; /** Returns the number of items in the menu. */ - size_t GetMenuItemCount(); + size_t GetMenuItemCount() const; /** Returns the list of items in the menu. wxMenuItemList is a pseudo-template list class containing wxMenuItem pointers, see wxList. */ - wxMenuItemList GetMenuItems(); + 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. - - @sa SetTitle() + wxMenuBar::GetMenuLabel for the menus in the menubar. + + @see SetTitle() */ - wxString GetTitle(); + wxString GetTitle() const; + + /** + Inserts the given @a item before the position @e pos. Inserting the item + at position GetMenuItemCount() is the same + as appending it. - //@{ + @see Append(), Prepend() + */ + wxMenuItem* Insert(size_t pos, wxMenuItem* item); + /** - Inserts the given @e item before the position @e pos. Inserting the item + Inserts the given @a item before the position @e pos. Inserting the item at position GetMenuItemCount() is the same as appending it. - - @sa Append(), Prepend() + + @see Append(), Prepend() */ - wxMenuItem* Insert(size_t pos, wxMenuItem * item); wxMenuItem* Insert(size_t pos, int id, const wxString& item = "", const wxString& helpString = "", wxItemKind kind = wxITEM_NORMAL); - //@} /** Inserts a checkable item at the given position. - - @sa Insert(), AppendCheckItem() + + @see Insert(), AppendCheckItem() */ wxMenuItem* InsertCheckItem(size_t pos, int id, const wxString& item, @@ -694,8 +721,8 @@ public: /** Inserts a radio item at the given position. - - @sa Insert(), AppendRadioItem() + + @see Insert(), AppendRadioItem() */ wxMenuItem* InsertRadioItem(size_t pos, int id, const wxString& item, @@ -703,133 +730,143 @@ public: /** Inserts a separator at the given position. - - @sa Insert(), AppendSeparator() + + @see Insert(), AppendSeparator() */ wxMenuItem* InsertSeparator(size_t pos); /** Determines whether a menu item is checked. - + @param id - The menu item identifier. - - @returns @true if the menu item is checked, @false otherwise. - - @sa Check() + The menu item identifier. + + @return @true if the menu item is checked, @false otherwise. + + @see Check() */ - bool IsChecked(int id); + bool IsChecked(int id) const; /** Determines whether a menu item is enabled. - + @param id - The menu item identifier. - - @returns @true if the menu item is enabled, @false otherwise. - - @sa Enable() + The menu item identifier. + + @return @true if the menu item is enabled, @false otherwise. + + @see Enable() */ - bool IsEnabled(int id); + bool IsEnabled(int id) const; - //@{ /** - Inserts the given @e 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. - - @sa Append(), Insert() + + @see Append(), Insert() + */ + wxMenuItem* Prepend(wxMenuItem* item); + + /** + Inserts the given @a item at position 0, i.e. before all the other + existing items. + + @see Append(), Insert() */ - wxMenuItem* Prepend(wxMenuItem * item); wxMenuItem* Prepend(int id, const wxString& item = "", const wxString& helpString = "", wxItemKind kind = wxITEM_NORMAL); - //@} /** Inserts a checkable item at position 0. - - @sa Prepend(), AppendCheckItem() + + @see Prepend(), AppendCheckItem() */ wxMenuItem* PrependCheckItem(int id, const wxString& item, const wxString& helpString = ""); /** Inserts a radio item at position 0. - - @sa Prepend(), AppendRadioItem() + + @see Prepend(), AppendRadioItem() */ wxMenuItem* PrependRadioItem(int id, const wxString& item, const wxString& helpString = ""); /** Inserts a separator at position 0. - - @sa Prepend(), AppendSeparator() + + @see Prepend(), AppendSeparator() */ wxMenuItem* PrependSeparator(); - //@{ /** Removes the menu item from the menu but doesn't delete the associated C++ - object. This allows to reuse the same item later by adding it back to the menu + object. This allows you to reuse the same item later by adding it back to the menu (especially useful with submenus). - + @param id - The identifier of the menu item to remove. - + The identifier of the menu item to remove. + + @return A pointer to the item which was detached from the menu. + */ + wxMenuItem* Remove(int id); + + /** + Removes the menu item from the menu but doesn't delete the associated C++ + object. This allows you to reuse the same item later by adding it back to the menu + (especially useful with submenus). + @param item - The menu item to remove. - - @returns The item which was detached from the menu. + The menu item to remove. + + @return A pointer to the item which was detached from the menu. */ - wxMenuItem * Remove(int id); - wxMenuItem * Remove(wxMenuItem * item); - //@} + wxMenuItem* Remove(wxMenuItem* item); /** Sets an item's help string. - + @param id - The menu item identifier. - + The menu item identifier. @param helpString - The help string to set. - - @sa GetHelpString() + The help string to set. + + @see GetHelpString() */ void SetHelpString(int id, const wxString& helpString); /** Sets the label of a menu item. - + @param id - The menu item identifier. - + The menu item identifier. @param label - The menu item label to set. - - @sa Append(), GetLabel() + The menu item label to set. + + @see Append(), GetLabel() */ void SetLabel(int id, const wxString& label); /** Sets the title of the menu. - + @param title - The title to set. - + The title to set. + @remarks This is relevant only to popup menus, use - wxMenuBar::SetLabelTop for the menus in the menubar. - - @sa GetTitle() + wxMenuBar::SetLabelTop for the menus in the menubar. + + @see GetTitle() */ void SetTitle(const wxString& title); /** - Sends events to @e source (or owning window if @NULL) to update the + Sends events to @a source (or owning window if @NULL) to update the menu UI. This is called just before the menu is popped up with wxWindow::PopupMenu, but the application may call it at other times if required. */ - void UpdateUI(wxEvtHandler* source = @NULL); + void UpdateUI(wxEvtHandler* source = NULL) const; }; +