don't call wxYield() from EnsureVisible(), this is too dangerous - and unnecessary...

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

diff --git a/docs/latex/wx/menu.tex b/docs/latex/wx/menu.tex
index 2025b94c10941664112eebdddc4129fc943ffe70..cbcd3148adcd9434efc7c73ba5e58bbee909235f 100644 (file)
--- a/docs/latex/wx/menu.tex
+++ b/docs/latex/wx/menu.tex
@@ -29,7 +29,7 @@ With a popup menu, there is a variety of ways to handle a menu selection event
 \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.
 \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 
+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}
 \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}


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


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


@@ -125,9 +125,9 @@ creation of a menu or menubar.
 \pythonnote{In place of a single overloaded method name, wxPython
 implements the following methods:\par
 \indented{2cm}{\begin{twocollist}
 \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}}
 }
 


@@ -169,7 +169,7 @@ Checks or unchecks the menu item.
 
 \func{void}{Delete}{\param{wxMenuItem *}{item}}
 
 
 \func{void}{Delete}{\param{wxMenuItem *}{item}}
 

-Deletes the menu item from the menu. If the item is a submenu, it will 
+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.
 
 {\bf not} be deleted. Use \helpref{Destroy}{wxmenudestroy} if you want to
 delete a submenu.
 


@@ -191,7 +191,7 @@ delete a submenu.
 
 \func{void}{Destroy}{\param{wxMenuItem *}{item}}
 
 
 \func{void}{Destroy}{\param{wxMenuItem *}{item}}
 

-Deletes the menu item from the menu. If the item is a submenu, it will 
+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).
 
 be deleted. Use \helpref{Remove}{wxmenuremove} if you want to keep the submenu
 (for example, to reuse it later).
 


@@ -229,32 +229,19 @@ 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}
-
-Any special menu codes are stripped out of source and target strings
-before matching.
-
-\wxheading{See also}
-
-\helpref{wxMenu::FindItem}{wxmenufinditem}
-
-\membersection{wxMenu::FindItem}\label{wxmenufinditem}
-

 \constfunc{wxMenuItem *}{FindItem}{\param{int}{ id}, \param{wxMenu **}{menu = NULL}}
 
 Finds the menu item object associated with the given menu item identifier and,
 optionally, the (sub)menu it belongs to.
 
 \constfunc{wxMenuItem *}{FindItem}{\param{int}{ id}, \param{wxMenu **}{menu = NULL}}
 
 Finds the menu item object associated with the given menu item identifier and,
 optionally, the (sub)menu it belongs to.
 

+\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{Parameters}
 
 \wxheading{Parameters}
 

+\docparam{itemString}{Menu item string to find.}
+

 \docparam{id}{Menu item identifier.}
 
 \docparam{menu}{If the pointer is not NULL, it will be filled with the items
 \docparam{id}{Menu item identifier.}
 
 \docparam{menu}{If the pointer is not NULL, it will be filled with the items


@@ -262,11 +249,17 @@ parent menu (if the item was found)}
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-Returns the menu item object, or NULL if it is not found.
+First form: menu item identifier, or wxNOT\_FOUND if none is found.

 
 

-\wxheading{See also}
+Second form: returns the menu item object, or NULL if it is not found.
+
+\wxheading{Remarks}
+
+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}
 


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


@@ -496,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.
 


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


@@ -536,7 +539,7 @@ Adds the item to the end of the menu bar.
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-TRUE on success, FALSE if an error occured.
+TRUE on success, FALSE if an error occurred.

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


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


@@ -701,7 +713,7 @@ 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}{wxmenubarinsert}
+\membersection{wxMenuBar::Insert}\label{wxmenubarinsert}

 
 \func{bool}{Insert}{\param{size\_t }{pos}, \param{wxMenu *}{menu}, \param{const wxString\& }{title}}
 
 
 \func{bool}{Insert}{\param{size\_t }{pos}, \param{wxMenu *}{menu}, \param{const wxString\& }{title}}
 


@@ -720,7 +732,7 @@ position $0$ will insert it in the very beginning of it, inserting at position
 
 \wxheading{Return value}
 
 
 \wxheading{Return value}
 

-TRUE on success, FALSE if an error occured.
+TRUE on success, FALSE if an error occurred.

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


@@ -777,7 +789,7 @@ dynamically.
 
 \func{wxMenu *}{Replace}{\param{size\_t }{pos}, \param{wxMenu *}{menu}, \param{const wxString\& }{title}}
 
 
 \func{wxMenu *}{Replace}{\param{size\_t }{pos}, \param{wxMenu *}{menu}, \param{const wxString\& }{title}}
 

-Replaces the menu at givenm position with another one.
+Replaces the menu at the given position with another one.

 
 \wxheading{Parameters}
 
 
 \wxheading{Parameters}
 


@@ -797,8 +809,6 @@ responsible for deleting it.
 \helpref{wxMenuBar::Insert}{wxmenubarinsert},\rtfsp
 \helpref{wxMenuBar::Remove}{wxmenubarremove}
 
 \helpref{wxMenuBar::Insert}{wxmenubarinsert},\rtfsp
 \helpref{wxMenuBar::Remove}{wxmenubarremove}
 

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

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