Small corrections -- please remember to put a blank line at the end of each input...

[wxWidgets.git] / docs / latex / wx / menu.tex

diff --git a/docs/latex/wx/menu.tex b/docs/latex/wx/menu.tex
index 8846d7579bbf01f189c942c3e1f8c0fb390c1e89..33946872fee8f9430838c52a48e7bc3fc31d09cb 100644 (file)
--- 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
 (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 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}
 \end{enumerate}
 
 \wxheading{See also}


@@ -41,8 +43,7 @@ this window.
 
 \membersection{wxMenu::wxMenu}\label{wxmenuconstr}
 
 
 \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.
 
 
 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{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}}
 
 
 \func{}{wxMenu}{\param{long}{ style}}
 


@@ -69,7 +59,7 @@ Constructs a wxMenu object.
 
 \wxheading{Parameters}
 
 
 \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}}
 
 
 \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}}
 
 
 \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}
 such as bitmaps and fonts.
 
 \wxheading{Parameters}


@@ -125,15 +117,17 @@ creation of a menu or menubar.
 
 \wxheading{See also}
 
 
 \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}
 \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}}
 }
 
 \end{twocollist}}
 }
 


@@ -173,19 +167,45 @@ Checks or unchecks the menu item.
 
 \func{void}{Delete}{\param{int }{id}}
 
 
 \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}
 
 
 \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.}

 
 

-Does not delete a sub menu, if any.
+\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).
+
+\wxheading{Parameters}
+
+\docparam{id}{Id of the menu item to be deleted.}
+
+\docparam{item}{Menu item to be deleted.}

 
 \wxheading{See also}
 
 
 \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}
 
 
 \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.
 
 
 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}
+\constfunc{wxMenuItem *}{FindItem}{\param{int}{ id}, \param{wxMenu **}{menu = NULL}}

 
 

-Any special menu codes are stripped out of source and target strings
-before matching.
-
-\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 2-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}
 
 
 \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}
 
 
 \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}
 \membersection{wxMenu::GetTitle}\label{wxmenugettitle}
 
 \constfunc{wxString}{GetTitle}{\void}


@@ -297,6 +325,18 @@ This is relevant only to popup menus.
 
 \helpref{wxMenu::SetTitle}{wxmenusettitle}
 
 
 \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}}
 \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}
 
 
 \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}}
 \membersection{wxMenu::SetHelpString}\label{wxmenusethelpstring}
 
 \func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}


@@ -421,6 +481,11 @@ then the events are sent directly to the frame. This allows command and UI updat
 handling to be processed by specific windows and controls, and not necessarily
 by the application frame.
 
 handling to be processed by specific windows and controls, and not necessarily
 by the application frame.
 

+{\bf Tip:} under Windows, if you discover that menu shortcuts (for example, Alt-F to show the file menu)
+are not working, check any EVT\_CHAR events you are handling in child windows.
+If you are not calling {\tt event.Skip()} for events that you don't process in these event handlers,
+menu shortcuts may cease to work.
+

 \wxheading{See also}
 
 \helpref{wxMenu}{wxmenu}, \helpref{Event handling overview}{eventhandlingoverview}
 \wxheading{See also}
 
 \helpref{wxMenu}{wxmenu}, \helpref{Event handling overview}{eventhandlingoverview}


@@ -429,7 +494,7 @@ by the application frame.
 
 \membersection{wxMenuBar::wxMenuBar}\label{wxmenubarconstr}
 
 
 \membersection{wxMenuBar::wxMenuBar}\label{wxmenubarconstr}
 

-\func{void}{wxMenuBar}{\void}
+\func{void}{wxMenuBar}{\param{long }{style = 0}}

 
 Default constructor.
 
 
 Default constructor.
 


@@ -446,9 +511,14 @@ menu bar.}
 
 \docparam{titles}{An array of title strings. Deallocate this array after creating the 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.}
 
 \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}
 \membersection{wxMenuBar::\destruct{wxMenuBar}}
 
 \func{void}{\destruct{wxMenuBar}}{\void}


@@ -457,7 +527,7 @@ Destructor, destroying the menu bar and removing it from the parent frame (if an
 
 \membersection{wxMenuBar::Append}\label{wxmenubarappend}
 
 
 \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.
 
 
 Adds the item to the end of the menu bar.
 


@@ -467,6 +537,14 @@ Adds the item to the end of the menu bar.
 
 \docparam{title}{The title of the menu.}
 
 
 \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}}
 \membersection{wxMenuBar::Check}\label{wxmenubarcheck}
 
 \func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}


@@ -518,6 +596,15 @@ Enables or disables a whole menu.
 Only use this when the menu bar has been
 associated with a frame.
 
 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}}
 \membersection{wxMenuBar::FindMenuItem}\label{wxmenubarfindmenuitem}
 
 \constfunc{int}{FindMenuItem}{\param{const wxString\& }{menuString}, \param{const wxString\& }{itemString}}


@@ -532,7 +619,7 @@ Finds the menu item id for a menu name/menu item string pair.
 
 \wxheading{Return value}
 
 
 \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}
 
 
 \wxheading{Remarks}
 


@@ -626,6 +713,31 @@ Returns the menu at {\it menuIndex} (zero-based).
 
 Returns the number of menus in this menubar.
 
 
 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}}
 \membersection{wxMenuBar::IsChecked}\label{wxmenubarischecked}
 
 \constfunc{bool}{IsChecked}{\param{int}{ id}}


@@ -660,6 +772,43 @@ TRUE if the item was found and is enabled, FALSE otherwise.
 
 Redraw the menu bar
 
 
 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}}
 \membersection{wxMenuBar::SetHelpString}\label{wxmenubarsethelpstring}
 
 \func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}