X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/407f36811ed2513233df1343f0b3591f09efb77e..bf7945cef10c0844a32e95695c544d829da9293a:/docs/latex/wx/menu.tex diff --git a/docs/latex/wx/menu.tex b/docs/latex/wx/menu.tex index 8846d7579b..91f540d1ea 100644 --- a/docs/latex/wx/menu.tex +++ b/docs/latex/wx/menu.tex @@ -24,12 +24,14 @@ With a popup menu, there is a variety of ways to handle a menu selection event (wxEVT\_COMMAND\_MENU\_SELECTED). \begin{enumerate}\itemsep=0pt -\item Define a callback of type wxFunction, which you pass to the wxMenu constructor. -The callback takes a reference to the menu, and a reference to a \helpref{wxCommandEvent}{wxcommandevent}. \item Derive a new class from wxMenu and define event table entries using the EVT\_MENU macro. \item Set a new event handler for wxMenu, using an object whose class has EVT\_MENU entries. \item Provide EVT\_MENU handlers in the window which pops up the menu, or in an ancestor of this window. +\item Define a callback of type wxFunction, which you pass to the wxMenu constructor. +The callback takes a reference to the menu, and a reference to a +\helpref{wxCommandEvent}{wxcommandevent}. This method is deprecated and should +not be used in the new code, it is provided for backwards compatibility only. \end{enumerate} \wxheading{See also} @@ -41,8 +43,7 @@ this window. \membersection{wxMenu::wxMenu}\label{wxmenuconstr} -\func{}{wxMenu}{\param{const wxString\& }{title = ""}, - \param{const wxFunction}{ func = NULL}, \param{long}{ style = 0}} +\func{}{wxMenu}{\param{const wxString\& }{title = ""}, \param{long}{ style = 0}} Constructs a wxMenu object. @@ -50,18 +51,7 @@ Constructs a wxMenu object. \docparam{title}{A title for the popup menu: the empty string denotes no title.} -\docparam{func}{A callback function if the menu is used as a popup using \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu}.} - -\docparam{style}{If set to \tt{wxMENU_TEAROFF}, the menu will be detachable.} - -\pythonnote{The wxPython version of the \tt{wxMenu} constructor -doesn't accept the callback argument because of reference counting -issues. There is a specialized wxMenu constructor called -\tt{wxPyMenu} which does and can be used for PopupMenus when callbacks -are needed. You must retain a reference to the menu while useing it -otherwise your callback function will get dereferenced when the menu -does. -} +\docparam{style}{If set to {\tt wxMENU\_TEAROFF}, the menu will be detachable (wxGTK only).} \func{}{wxMenu}{\param{long}{ style}} @@ -69,7 +59,7 @@ Constructs a wxMenu object. \wxheading{Parameters} -\docparam{style}{If set to \tt{wxMENU_TEAROFF}, the menu will be detachable.} +\docparam{style}{If set to {\tt wxMENU\_TEAROFF}, the menu will be detachable (wxGTK only).} \membersection{wxMenu::\destruct{wxMenu}} @@ -98,7 +88,9 @@ Adds a pull-right submenu to the end of the menu. \func{void}{Append}{\param{wxMenuItem*}{ menuItem}} -Adds a menu item object. You can specify various extra properties of a menu item this way, +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. \wxheading{Parameters} @@ -125,15 +117,17 @@ creation of a menu or menubar. \wxheading{See also} -\helpref{wxMenu::AppendSeparator}{wxmenuappendseparator}, \helpref{wxMenu::SetLabel}{wxmenusetlabel}, \helpref{wxMenu::GetHelpString}{wxmenugethelpstring},\rtfsp +\helpref{wxMenu::AppendSeparator}{wxmenuappendseparator},\rtfsp +\helpref{wxMenu::Insert}{wxmenuinsert},\rtfsp +\helpref{wxMenu::SetLabel}{wxmenusetlabel}, \helpref{wxMenu::GetHelpString}{wxmenugethelpstring},\rtfsp \helpref{wxMenu::SetHelpString}{wxmenusethelpstring}, \helpref{wxMenuItem}{wxmenuitem} \pythonnote{In place of a single overloaded method name, wxPython implements the following methods:\par \indented{2cm}{\begin{twocollist} -\twocolitem{\bf{Append(id, string, helpStr="", checkable=FALSE)}}{} -\twocolitem{\bf{AppendMenu(id, string, aMenu, helpStr="")}}{} -\twocolitem{\bf{AppendItem(aMenuItem)}}{} +\twocolitem{{\bf Append(id, string, helpStr="", checkable=FALSE)}}{} +\twocolitem{{\bf AppendMenu(id, string, aMenu, helpStr="")}}{} +\twocolitem{{\bf AppendItem(aMenuItem)}}{} \end{twocollist}} } @@ -173,19 +167,45 @@ Checks or unchecks the menu item. \func{void}{Delete}{\param{int }{id}} -Deletes the menu item from the menu. +\func{void}{Delete}{\param{wxMenuItem *}{item}} + +Deletes the menu item from the menu. If the item is a submenu, it will +{\bf not} be deleted. Use \helpref{Destroy}{wxmenudestroy} if you want to +delete a submenu. \wxheading{Parameters} -\docparam{id}{Menu item to be deleted.} +\docparam{id}{Id of the menu item to be deleted.} -\wxheading{Remarks} +\docparam{item}{Menu item to be deleted.} + +\wxheading{See also} + +\helpref{wxMenu::FindItem}{wxmenufinditem},\rtfsp +\helpref{wxMenu::Destroy}{wxmenudestroy},\rtfsp +\helpref{wxMenu::Remove}{wxmenuremove} + +\membersection{wxMenu::Destroy}\label{wxmenudestroy} + +\func{void}{Destroy}{\param{int }{id}} + +\func{void}{Destroy}{\param{wxMenuItem *}{item}} + +Deletes the menu item from the menu. If the item is a submenu, it will +be deleted. Use \helpref{Remove}{wxmenuremove} if you want to keep the submenu +(for example, to reuse it later). -Does not delete a sub menu, if any. +\wxheading{Parameters} + +\docparam{id}{Id of the menu item to be deleted.} + +\docparam{item}{Menu item to be deleted.} \wxheading{See also} -\helpref{wxMenu::FindItemForId}{wxmenufinditemforid} +\helpref{wxMenu::FindItem}{wxmenufinditem},\rtfsp +\helpref{wxMenu::Deletes}{wxmenudelete},\rtfsp +\helpref{wxMenu::Remove}{wxmenuremove} \membersection{wxMenu::Enable}\label{wxmenuenable} @@ -209,42 +229,37 @@ Enables or disables (greys out) a menu item. Finds the menu item id for a menu item string. -\wxheading{Parameters} - -\docparam{itemString}{Menu item string to find.} - -\wxheading{Return value} - -Menu item identifier, or wxNOT_FOUND if none is found. - -\wxheading{Remarks} - -Any special menu codes are stripped out of source and target strings -before matching. +\constfunc{wxMenuItem *}{FindItem}{\param{int}{ id}, \param{wxMenu **}{menu = NULL}} -\wxheading{See also} +Finds the menu item object associated with the given menu item identifier and, +optionally, the (sub)menu it belongs to. -\helpref{wxMenu::FindItemForId}{wxmenufinditemforid} +\perlnote{In wxPerl this method takes just the {\tt id} parameter; +in scalar context it returns the associated {\tt Wx::MenuItem}, in list +context it returns a two element list ( item, submenu )} -\membersection{wxMenu::FindItemForId}\label{wxmenufinditemforid} +\wxheading{Parameters} -\constfunc{wxMenuItem*}{FindItemForId}{\param{int}{ id}} +\docparam{itemString}{Menu item string to find.} -\constfunc{wxMenuItem*}{FindItem}{\param{int}{ id}} +\docparam{id}{Menu item identifier.} -Finds the menu item object associated with the given menu item identifier. +\docparam{menu}{If the pointer is not NULL, it will be filled with the items +parent menu (if the item was found)} -\wxheading{Parameters} +\wxheading{Return value} -\docparam{id}{Menu item identifier.} +First form: menu item identifier, or wxNOT\_FOUND if none is found. -\wxheading{Return value} +Second form: returns the menu item object, or NULL if it is not found. -Returns the menu item object, or NULL if it is not found. +\wxheading{Remarks} -\wxheading{See also} +Any special menu codes are stripped out of source and target strings +before matching. -\helpref{wxMenu::FindItem}{wxmenufinditem} +\pythonnote{The name of this method in wxPython is {\tt FindItemById} +and it does not support the second parameter.} \membersection{wxMenu::GetHelpString}\label{wxmenugethelpstring} @@ -283,6 +298,19 @@ The item label, or the empty string if the item was not found. \helpref{wxMenu::SetLabel}{wxmenusetlabel} +\membersection{wxMenu::GetMenuItemCount}\label{wxmenugetmenuitemcount} + +\constfunc{size\_t}{GetMenuItemCount}{\void} + +Returns the number of items in the menu. + +\membersection{wxMenu::GetMenuItems}\label{wxmenugetmenuitems} + +\constfunc{wxMenuItemList\&}{GetMenuItems}{\void} + +Returns the list of items in the menu. wxMenuItemList is a pseudo-template +list class containing wxMenuItem pointers. + \membersection{wxMenu::GetTitle}\label{wxmenugettitle} \constfunc{wxString}{GetTitle}{\void} @@ -297,6 +325,18 @@ This is relevant only to popup menus. \helpref{wxMenu::SetTitle}{wxmenusettitle} +\membersection{wxMenu::Insert}\label{wxmenuinsert} + +\func{bool}{Insert}{\param{size\_t }{pos}, \param{wxMenuItem *}{item}} + +Inserts the given {\it item} before the position {\it pos}. Inserting the item +at the position \helpref{GetMenuItemCount}{wxmenugetmenuitemcount} is the same +as appending it. + +\wxheading{See also} + +\helpref{wxMenu::Append}{wxmenuappend} + \membersection{wxMenu::IsChecked}\label{wxmenuischecked} \constfunc{bool}{IsChecked}{\param{int}{ id}} @@ -333,6 +373,26 @@ TRUE if the menu item is enabled, FALSE otherwise. \helpref{wxMenu::Enable}{wxmenuenable} +\membersection{wxMenu::Remove}\label{wxmenuremove} + +\func{wxMenuItem *}{Remove}{\param{int }{id}} + +\func{wxMenuItem *}{Remove}{\param{wxMenuItem *}{item}} + +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 +(especially useful with submenus). + +\wxheading{Parameters} + +\docparam{id}{The identifier of the menu item to remove.} + +\docparam{item}{The menu item to remove.} + +\wxheading{Return value} + +The item which was detached from the menu. + \membersection{wxMenu::SetHelpString}\label{wxmenusethelpstring} \func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}} @@ -429,7 +489,7 @@ by the application frame. \membersection{wxMenuBar::wxMenuBar}\label{wxmenubarconstr} -\func{void}{wxMenuBar}{\void} +\func{void}{wxMenuBar}{\param{long }{style = 0}} Default constructor. @@ -446,9 +506,14 @@ menu bar.} \docparam{titles}{An array of title strings. Deallocate this array after creating the menu bar.} +\docparam{style}{If {\tt wxMB\_DOCKABLE} the menu bar can be detached (wxGTK only).} + \pythonnote{Only the default constructor is supported in wxPython. Use wxMenuBar.Append instead.} +\perlnote{wxPerl only supports the first contructor: +use {\tt Append} instead.} + \membersection{wxMenuBar::\destruct{wxMenuBar}} \func{void}{\destruct{wxMenuBar}}{\void} @@ -457,7 +522,7 @@ Destructor, destroying the menu bar and removing it from the parent frame (if an \membersection{wxMenuBar::Append}\label{wxmenubarappend} -\func{void}{Append}{\param{wxMenu *}{menu}, \param{const wxString\& }{title}} +\func{bool}{Append}{\param{wxMenu *}{menu}, \param{const wxString\& }{title}} Adds the item to the end of the menu bar. @@ -467,6 +532,14 @@ Adds the item to the end of the menu bar. \docparam{title}{The title of the menu.} +\wxheading{Return value} + +TRUE on success, FALSE if an error occurred. + +\wxheading{See also} + +\helpref{wxMenuBar::Insert}{wxmenubarinsert} + \membersection{wxMenuBar::Check}\label{wxmenubarcheck} \func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}} @@ -518,6 +591,15 @@ Enables or disables a whole menu. Only use this when the menu bar has been associated with a frame. +\membersection{wxMenuBar::FindMenu}\label{wxmenubarfindmenu} + +\constfunc{int}{FindMenu}{\param{const wxString\& }{title}} + +Returns the index of the menu with the given {\it title} or wxNOT\_FOUND if no +such menu exists in this menubar. The {\it title} parameter may specify either +the menu title (with accelerator characters, i.e. {\tt "\&File"}) or just the +menu label ({\tt "File"}) indifferently. + \membersection{wxMenuBar::FindMenuItem}\label{wxmenubarfindmenuitem} \constfunc{int}{FindMenuItem}{\param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}} @@ -532,7 +614,7 @@ Finds the menu item id for a menu name/menu item string pair. \wxheading{Return value} -The menu item identifier, or wxNOT_FOUND if none was found. +The menu item identifier, or wxNOT\_FOUND if none was found. \wxheading{Remarks} @@ -626,6 +708,31 @@ Returns the menu at {\it menuIndex} (zero-based). Returns the number of menus in this menubar. +\membersection{wxMenuBar::Insert}\label{wxmenubarinsert} + +\func{bool}{Insert}{\param{size\_t }{pos}, \param{wxMenu *}{menu}, \param{const wxString\& }{title}} + +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 +\helpref{GetMenuCount()}{wxmenubargetmenucount} is the same as calling +\helpref{Append()}{wxmenubarappend}. + +\wxheading{Parameters} + +\docparam{pos}{The position of the new menu in the menu bar} + +\docparam{menu}{The menu to add. wxMenuBar owns the menu and will free it.} + +\docparam{title}{The title of the menu.} + +\wxheading{Return value} + +TRUE on success, FALSE if an error occurred. + +\wxheading{See also} + +\helpref{wxMenuBar::Append}{wxmenubarappend} + \membersection{wxMenuBar::IsChecked}\label{wxmenubarischecked} \constfunc{bool}{IsChecked}{\param{int}{ id}} @@ -660,6 +767,43 @@ TRUE if the item was found and is enabled, FALSE otherwise. Redraw the menu bar +\membersection{wxMenuBar::Remove}\label{wxmenubarremove} + +\func{wxMenu *}{Remove}{\param{size\_t }{pos}} + +Removes the menu from the menu bar and returns the menu object - the caller is +reposnbile for deleting it. This function may be used together with +\helpref{wxMenuBar::Insert}{wxmenubarinsert} to change the menubar +dynamically. + +\wxheading{See also} + +\helpref{wxMenuBar::Replace}{wxmenubarreplace} + +\membersection{wxMenuBar::Replace}\label{wxmenubarreplace} + +\func{wxMenu *}{Replace}{\param{size\_t }{pos}, \param{wxMenu *}{menu}, \param{const wxString\& }{title}} + +Replaces the menu at the given position with another one. + +\wxheading{Parameters} + +\docparam{pos}{The position of the new menu in the menu bar} + +\docparam{menu}{The menu to add.} + +\docparam{title}{The title of the menu.} + +\wxheading{Return value} + +The menu which was previously at the position {\it pos}. The caller is +responsible for deleting it. + +\wxheading{See also} + +\helpref{wxMenuBar::Insert}{wxmenubarinsert},\rtfsp +\helpref{wxMenuBar::Remove}{wxmenubarremove} + \membersection{wxMenuBar::SetHelpString}\label{wxmenubarsethelpstring} \func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}