Added wxCURSOR_ARROWWAIT which is the default arrow+hourglass cursor

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

diff --git a/docs/latex/wx/menu.tex b/docs/latex/wx/menu.tex
index fe20490bb578fe3576285b5ade1d891f0b517603..91f540d1ea066646d413583b347d74172790dee5 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}


@@ -49,8 +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{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).}

 
 \func{}{wxMenu}{\param{long}{ style}}
 
 
 \func{}{wxMenu}{\param{long}{ style}}
 


@@ -58,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}}
 


@@ -87,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}


@@ -114,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}}
 }
 


@@ -162,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.}
+
+\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}

 
 

-Does not delete a sub menu, if any.
+\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}
 


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

 
 

-\wxheading{Remarks}
+Finds the menu item object associated with the given menu item identifier and,
+optionally, the (sub)menu it belongs to.

 
 

-Any special menu codes are stripped out of source and target strings
-before matching.
+\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 )}

 
 

-\wxheading{See also}
-
-\helpref{wxMenu::FindItemForId}{wxmenufinditemforid}
-
-\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}
 


@@ -272,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}


@@ -286,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}}


@@ -322,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}}


@@ -418,7 +489,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.
 


@@ -435,9 +506,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}


@@ -446,7 +522,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.
 


@@ -456,6 +532,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}}


@@ -507,6 +591,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}}


@@ -521,7 +614,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}
 


@@ -615,6 +708,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}}


@@ -649,6 +767,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}}