Defer retrieval of LANG env var, too. No memory management

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

diff --git a/docs/latex/wx/menu.tex b/docs/latex/wx/menu.tex
index fa828b464bf6fd71ed7e4f3fd11d8b2d8004852e..ebaf7fb1a4cfc03600b920b9ccc6c75b6e003667 100644 (file)
--- a/docs/latex/wx/menu.tex
+++ b/docs/latex/wx/menu.tex
@@ -12,6 +12,10 @@ identify the selection, or to change the menu item in some way.
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 

+\wxheading{Include files}
+
+<wx/menu.h>
+

 \wxheading{Event handling}
 
 If the menu is part of a menubar, then \helpref{wxMenuBar}{wxmenubar} event processing is used.
 \wxheading{Event handling}
 
 If the menu is part of a menubar, then \helpref{wxMenuBar}{wxmenubar} event processing is used.


@@ -21,7 +25,7 @@ With a popup menu, there is a variety of ways to handle a menu selection event
 
 \begin{enumerate}\itemsep=0pt
 \item Define a callback of type wxFunction, which you pass to the wxMenu constructor.
 
 \begin{enumerate}\itemsep=0pt
 \item Define a callback of type wxFunction, which you pass to the wxMenu constructor.

-The callback takes a reference to a window, and a reference to a \helpref{wxCommandEvent}{wxcommandevent}.
+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
 \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


@@ -47,20 +51,36 @@ Constructs a wxMenu object.
 
 \docparam{func}{A callback function if the menu is used as a popup using \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu}.}
 
 
 \docparam{func}{A callback function if the menu is used as a popup using \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu}.}
 

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

 \membersection{wxMenu::\destruct{wxMenu}}
 
 \func{}{\destruct{wxMenu}}{\void}
 
 Destructor, destroying the menu.
 
 \membersection{wxMenu::\destruct{wxMenu}}
 
 \func{}{\destruct{wxMenu}}{\void}
 
 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 {\it before} destroying the
+parent window. Re-use in this context means popping up the menu on
+a different window from last time, which causes an implicit destruction
+and recreation of internal data structures.
+

 \membersection{wxMenu::Append}\label{wxmenuappend}
 
 \membersection{wxMenu::Append}\label{wxmenuappend}
 

-\func{void}{Append}{\param{const int}{ id}, \param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""},\rtfsp
+\func{void}{Append}{\param{int}{ id}, \param{const wxString\& }{ item}, \param{const wxString\& }{helpString = ""},\rtfsp

 \param{const bool}{ checkable = FALSE}}
 
 Adds a string item to the end of the menu.
 
 \param{const bool}{ checkable = FALSE}}
 
 Adds a string item to the end of the menu.
 

-\func{void}{Append}{\param{const int}{ id}, \param{const wxString\& }{ item}, \param{wxMenu *}{subMenu},\rtfsp
+\func{void}{Append}{\param{int}{ id}, \param{const wxString\& }{ item}, \param{wxMenu *}{subMenu},\rtfsp

 \param{const wxString\& }{helpString = ""}}
 
 Adds a pull-right submenu to the end of the menu.
 \param{const wxString\& }{helpString = ""}}
 
 Adds a pull-right submenu to the end of the menu.


@@ -97,6 +117,17 @@ creation of a menu or menubar.
 \helpref{wxMenu::AppendSeparator}{wxmenuappendseparator}, \helpref{wxMenu::SetLabel}{wxmenusetlabel}, \helpref{wxMenu::GetHelpString}{wxmenugethelpstring},\rtfsp
 \helpref{wxMenu::SetHelpString}{wxmenusethelpstring}, \helpref{wxMenuItem}{wxmenuitem}
 
 \helpref{wxMenu::AppendSeparator}{wxmenuappendseparator}, \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)}}{}
+\end{twocollist}}
+}
+
+

 \membersection{wxMenu::AppendSeparator}\label{wxmenuappendseparator}
 
 \func{void}{AppendSeparator}{\void}
 \membersection{wxMenu::AppendSeparator}\label{wxmenuappendseparator}
 
 \func{void}{AppendSeparator}{\void}


@@ -115,7 +146,7 @@ Inserts a break in a menu, causing the next appended item to appear in a new col
 
 \membersection{wxMenu::Check}\label{wxmenucheck}
 
 
 \membersection{wxMenu::Check}\label{wxmenucheck}
 

-\func{void}{Check}{\param{const int}{ id}, \param{const bool}{ check}}
+\func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}

 
 Checks or unchecks the menu item.
 
 
 Checks or unchecks the menu item.
 


@@ -131,7 +162,7 @@ Checks or unchecks the menu item.
 
 \membersection{wxMenu::Enable}\label{wxmenuenable}
 
 
 \membersection{wxMenu::Enable}\label{wxmenuenable}
 

-\func{void}{Enable}{\param{const int}{ id}, \param{const bool}{ enable}}
+\func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}}

 
 Enables or disables (greys out) a menu item.
 
 
 Enables or disables (greys out) a menu item.
 


@@ -168,15 +199,16 @@ before matching.
 
 \helpref{wxMenu::FindItemForId}{wxmenufinditemforid}
 
 
 \helpref{wxMenu::FindItemForId}{wxmenufinditemforid}
 

-\membersection{wxMenu::FindItemForId}\label{wxmenufinditemforid}
+\membersection{wxMenu::FindItemForId}\label{wxmenufinditem}

 
 

-\constfunc{wxMenuItem*}{FindItemForId}{\param{const int}{ id}}
+\constfunc{wxMenuItem*}{FindItemForId}{\param{int}{ id}, \param{wxMenu **}{ menuForItem = NULL}}

 
 Finds the menu item object associated with the given menu item identifier.
 
 \wxheading{Parameters}
 
 \docparam{id}{Menu item identifier.}
 
 Finds the menu item object associated with the given menu item identifier.
 
 \wxheading{Parameters}
 
 \docparam{id}{Menu item identifier.}

+\docparam{menuForItem}{will be filled with the menu for this item if not NULL.}

 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 


@@ -188,7 +220,7 @@ Returns the menu item object, or NULL if it is not found.
 
 \membersection{wxMenu::GetHelpString}\label{wxmenugethelpstring}
 
 
 \membersection{wxMenu::GetHelpString}\label{wxmenugethelpstring}
 

-\constfunc{wxString}{GetHelpString}{\param{const int}{ id}}
+\constfunc{wxString}{GetHelpString}{\param{int}{ id}}

 
 Returns the help string associated with a menu item.
 
 
 Returns the help string associated with a menu item.
 


@@ -207,7 +239,7 @@ item was not found.
 
 \membersection{wxMenu::GetLabel}\label{wxmenugetlabel}
 
 
 \membersection{wxMenu::GetLabel}\label{wxmenugetlabel}
 

-\constfunc{wxString}{GetLabel}{\param{const int}{ id}}
+\constfunc{wxString}{GetLabel}{\param{int}{ id}}

 
 Returns a menu item label.
 
 
 Returns a menu item label.
 


@@ -239,7 +271,7 @@ This is relevant only to popup menus.
 
 \membersection{wxMenu::IsChecked}\label{wxmenuischecked}
 
 
 \membersection{wxMenu::IsChecked}\label{wxmenuischecked}
 

-\constfunc{bool}{IsChecked}{\param{const int}{ id}}
+\constfunc{bool}{IsChecked}{\param{int}{ id}}

 
 Determines whether a menu item is checked.
 
 
 Determines whether a menu item is checked.
 


@@ -257,7 +289,7 @@ TRUE if the menu item is checked, FALSE otherwise.
 
 \membersection{wxMenu::IsEnabled}\label{wxmenuisenabled}
 
 
 \membersection{wxMenu::IsEnabled}\label{wxmenuisenabled}
 

-\constfunc{bool}{IsEnabled}{\param{const int}{ id}}
+\constfunc{bool}{IsEnabled}{\param{int}{ id}}

 
 Determines whether a menu item is enabled.
 
 
 Determines whether a menu item is enabled.
 


@@ -275,7 +307,7 @@ TRUE if the menu item is enabled, FALSE otherwise.
 
 \membersection{wxMenu::SetHelpString}\label{wxmenusethelpstring}
 
 
 \membersection{wxMenu::SetHelpString}\label{wxmenusethelpstring}
 

-\func{void}{SetHelpString}{\param{const int}{ id}, \param{const wxString\& }{helpString}}
+\func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}

 
 Sets an item's help string.
 
 
 Sets an item's help string.
 


@@ -291,7 +323,7 @@ Sets an item's help string.
 
 \membersection{wxMenu::SetLabel}\label{wxmenusetlabel}
 
 
 \membersection{wxMenu::SetLabel}\label{wxmenusetlabel}
 

-\func{void}{SetLabel}{\param{const int}{ id}, \param{const wxString\& }{label}}
+\func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}

 
 Sets the label of a menu item.
 
 
 Sets the label of a menu item.
 


@@ -323,6 +355,18 @@ This is relevant only to popup menus.
 
 \helpref{wxMenu::SetTitle}{wxmenusettitle}
 
 
 \helpref{wxMenu::SetTitle}{wxmenusettitle}
 

+\membersection{wxMenu::UpdateUI}\label{wxmenuupdateui}
+
+\constfunc{void}{UpdateUI}{\param{wxEvtHandler*}{ source = NULL}}
+
+Sends events to {\it source} (or owning window if NULL) to update the
+menu UI. This is called just before the menu is popped up with \helpref{wxWindow::PopupMenu}{wxwindowpopupmenu}, but
+the application may call it at other times if required.
+
+\wxheading{See also}
+
+\helpref{wxUpdateUIEvent}{wxupdateuievent}
+

 \section{\class{wxMenuBar}}\label{wxmenubar}
 
 A menu bar is a series of menus accessible from the top of a frame.
 \section{\class{wxMenuBar}}\label{wxmenubar}
 
 A menu bar is a series of menus accessible from the top of a frame.


@@ -332,10 +376,22 @@ A menu bar is a series of menus accessible from the top of a frame.
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 
 \helpref{wxEvtHandler}{wxevthandler}\\
 \helpref{wxObject}{wxobject}
 

+\wxheading{Include files}
+
+<wx/menu.h>
+

 \wxheading{Event handling}
 
 To respond to a menu selection, provide a handler for EVT\_MENU, in the frame
 \wxheading{Event handling}
 
 To respond to a menu selection, provide a handler for EVT\_MENU, in the frame

-that contains the menu bar.
+that contains the menu bar. If you have a toolbar which uses the same identifiers
+as your EVT\_MENU entries, events from the toolbar will also be processed by your
+EVT\_MENU event handlers.
+
+Note that menu commands (and UI update events for menus) are first sent to
+the focus window within the frame. If no window within the frame has the focus,
+then the events are sent directly to the frame. This allows command and UI update
+handling to be processed by specific windows and controls, and not necessarily
+by the application frame.

 
 \wxheading{See also}
 
 
 \wxheading{See also}
 


@@ -349,7 +405,7 @@ that contains the menu bar.
 
 Default constructor.
 
 
 Default constructor.
 

-\func{void}{wxMenuBar}{\param{const int}{ n}, \param{wxMenu*}{ menus[]}, \param{const wxString }{titles[]}}
+\func{void}{wxMenuBar}{\param{int}{ n}, \param{wxMenu*}{ menus[]}, \param{const wxString }{titles[]}}

 
 Construct a menu bar from arrays of menus and titles.
 
 
 Construct a menu bar from arrays of menus and titles.
 


@@ -362,6 +418,10 @@ 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.}
 

+\pythonnote{Only the default constructor is supported in wxPython.
+Use wxMenuBar.Append instead.}
+
+

 \membersection{wxMenuBar::\destruct{wxMenuBar}}
 
 \func{void}{\destruct{wxMenuBar}}{\void}
 \membersection{wxMenuBar::\destruct{wxMenuBar}}
 
 \func{void}{\destruct{wxMenuBar}}{\void}


@@ -382,7 +442,7 @@ Adds the item to the end of the menu bar.
 
 \membersection{wxMenuBar::Check}\label{wxmenubarcheck}
 
 
 \membersection{wxMenuBar::Check}\label{wxmenubarcheck}
 

-\func{void}{Check}{\param{const int}{ id}, \param{const bool}{ check}}
+\func{void}{Check}{\param{int}{ id}, \param{const bool}{ check}}

 
 Checks or unchecks a menu item.
 
 
 Checks or unchecks a menu item.
 


@@ -399,7 +459,7 @@ with a frame; otherwise, use the wxMenu equivalent call.
 
 \membersection{wxMenuBar::Enable}\label{wxmenubarenable}
 
 
 \membersection{wxMenuBar::Enable}\label{wxmenubarenable}
 

-\func{void}{Enable}{\param{const int}{ id}, \param{const bool}{ enable}}
+\func{void}{Enable}{\param{int}{ id}, \param{const bool}{ enable}}

 
 Enables or disables (greys out) a menu item.
 
 
 Enables or disables (greys out) a menu item.
 


@@ -416,7 +476,7 @@ associated with a frame; otherwise, use the wxMenu equivalent call.
 
 \membersection{wxMenuBar::EnableTop}\label{wxmenubarenabletop}
 
 
 \membersection{wxMenuBar::EnableTop}\label{wxmenubarenabletop}
 

-\func{void}{EnableTop}{\param{const int}{ pos}, \param{const bool}{ enable}}
+\func{void}{EnableTop}{\param{int}{ pos}, \param{const bool}{ enable}}

 
 Enables or disables a whole menu.
 
 
 Enables or disables a whole menu.
 


@@ -452,9 +512,9 @@ The menu item identifier, or -1 if none was found.
 Any special menu codes are stripped out of source and target strings
 before matching.
 
 Any special menu codes are stripped out of source and target strings
 before matching.
 

-\membersection{wxMenuBar::FindItemById}\label{wxmenubarfinditembyid}
+\membersection{wxMenuBar::FindItemForId}\label{wxmenubarfinditemforid}

 
 

-\constfunc{wxMenuItem *}{FindItemById}{\param{const int}{ id}}
+\constfunc{wxMenuItem *}{FindItemForId}{\param{int}{ id}}

 
 Finds the menu item object associated with the given menu item identifier,
 
 
 Finds the menu item object associated with the given menu item identifier,
 


@@ -468,7 +528,7 @@ The found menu item object, or NULL if one was not found.
 
 \membersection{wxMenuBar::GetHelpString}\label{wxmenubargethelpstring}
 
 
 \membersection{wxMenuBar::GetHelpString}\label{wxmenubargethelpstring}
 

-\constfunc{wxString}{GetHelpString}{\param{const int}{ id}}
+\constfunc{wxString}{GetHelpString}{\param{int}{ id}}

 
 Gets the help string associated with the menu item identifer.
 
 
 Gets the help string associated with the menu item identifer.
 


@@ -487,7 +547,7 @@ was not found.
 
 \membersection{wxMenuBar::GetLabel}\label{wxmenubargetlabel}
 
 
 \membersection{wxMenuBar::GetLabel}\label{wxmenubargetlabel}
 

-\constfunc{wxString}{GetLabel}{\param{const int}{ id}}
+\constfunc{wxString}{GetLabel}{\param{int}{ id}}

 
 Gets the label associated with a menu item.
 
 
 Gets the label associated with a menu item.
 


@@ -505,7 +565,7 @@ Use only after the menubar has been associated with a frame.
 
 \membersection{wxMenuBar::GetLabelTop}\label{wxmenubargetlabeltop}
 
 
 \membersection{wxMenuBar::GetLabelTop}\label{wxmenubargetlabeltop}
 

-\constfunc{wxString}{GetLabelTop}{\param{const int}{ pos}}
+\constfunc{wxString}{GetLabelTop}{\param{int}{ pos}}

 
 Returns the label of a top-level menu.
 
 
 Returns the label of a top-level menu.
 


@@ -525,9 +585,21 @@ Use only after the menubar has been associated with a frame.
 
 \helpref{wxMenuBar::SetLabelTop}{wxmenubarsetlabeltop}
 
 
 \helpref{wxMenuBar::SetLabelTop}{wxmenubarsetlabeltop}
 

+\membersection{wxMenuBar::GetMenu}\label{wxmenubargetmenu}
+
+\constfunc{wxMenu*}{GetMenu}{\param{int}{ menuIndex}}
+
+Returns the menu at {\it menuIndex} (zero-based).
+
+\membersection{wxMenuBar::GetMenuCount}\label{wxmenubargetmenucount}
+
+\constfunc{int}{GetMenuCount}{\void}
+
+Returns the number of menus in this menubar.
+

 \membersection{wxMenuBar::IsChecked}\label{wxmenubarischecked}
 
 \membersection{wxMenuBar::IsChecked}\label{wxmenubarischecked}
 

-\constfunc{bool}{IsChecked}{\param{const int}{ id}}
+\constfunc{bool}{IsChecked}{\param{int}{ id}}

 
 Determines whether an item is checked.
 
 
 Determines whether an item is checked.
 


@@ -541,7 +613,7 @@ TRUE if the item was found and is checked, FALSE otherwise.
 
 \membersection{wxMenuBar::IsEnabled}\label{wxmenubarisenabled}
 
 
 \membersection{wxMenuBar::IsEnabled}\label{wxmenubarisenabled}
 

-\constfunc{bool}{IsEnabled}{\param{const int}{ id}}
+\constfunc{bool}{IsEnabled}{\param{int}{ id}}

 
 Determines whether an item is enabled.
 
 
 Determines whether an item is enabled.
 


@@ -555,7 +627,7 @@ TRUE if the item was found and is enabled, FALSE otherwise.
 
 \membersection{wxMenuBar::SetHelpString}\label{wxmenubarsethelpstring}
 
 
 \membersection{wxMenuBar::SetHelpString}\label{wxmenubarsethelpstring}
 

-\func{void}{SetHelpString}{\param{const int}{ id}, \param{const wxString\& }{helpString}}
+\func{void}{SetHelpString}{\param{int}{ id}, \param{const wxString\& }{helpString}}

 
 Sets the help string associated with a menu item.
 
 
 Sets the help string associated with a menu item.
 


@@ -571,7 +643,7 @@ Sets the help string associated with a menu item.
 
 \membersection{wxMenuBar::SetLabel}\label{wxmenubarsetlabel}
 
 
 \membersection{wxMenuBar::SetLabel}\label{wxmenubarsetlabel}
 

-\func{void}{SetLabel}{\param{const int}{ id}, \param{const wxString\& }{label}}
+\func{void}{SetLabel}{\param{int}{ id}, \param{const wxString\& }{label}}

 
 Sets the label of a menu item.
 
 
 Sets the label of a menu item.
 


@@ -591,7 +663,7 @@ Use only after the menubar has been associated with a frame.
 
 \membersection{wxMenuBar::SetLabelTop}\label{wxmenubarsetlabeltop}
 
 
 \membersection{wxMenuBar::SetLabelTop}\label{wxmenubarsetlabeltop}
 

-\func{void}{SetLabelTop}{\param{const int}{ pos}, \param{const wxString\& }{label}}
+\func{void}{SetLabelTop}{\param{int}{ pos}, \param{const wxString\& }{label}}

 
 Sets the label of a top-level menu.
 
 
 Sets the label of a top-level menu.