add wxShowEvent::IsShown() and wxIconizeEvent::IsIconized() instead of (now deprecate...

[wxWidgets.git] / interface / menu.h

diff --git a/interface/menu.h b/interface/menu.h
index bfc5f442ffe6e6bbe300d47393e88e66f9b55b28..f19fc4ca04ed1890dab435e9f265ffdb9c929995 100644 (file)
--- a/interface/menu.h
+++ b/interface/menu.h
@@ -15,30 +15,35 @@
     @library{wxcore}
     @category{menus}
 
     @library{wxcore}
     @category{menus}
 

-    @see wxMenu, @ref overview_eventhandlingoverview
+    @see wxMenu, @ref overview_eventhandling "Event Handling Overview"

 */
 class wxMenuBar : public wxWindow
 {
 public:
 */
 class wxMenuBar : public wxWindow
 {
 public:

-    //@{
+    /**
+        Construct an empty menu barM
+
+        @param style
+            If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
+    */
+    wxMenuBar(long style = 0);
+    

     /**
         Construct a menu bar from arrays of menus and titles.
 
         @param n
             The number of menus.
         @param menus
     /**
         Construct a menu bar from arrays of menus and titles.
 
         @param n
             The number of menus.
         @param menus

-            An array of menus. Do not use this array again - it now belongs to the
-            menu bar.
+            An array of menus. Do not use this array again - it now belongs to
+            the menu bar.

         @param titles
         @param titles

-            An array of title strings. Deallocate this array after creating the menu
-        bar.
+            An array of title strings. Deallocate this array after creating
+            the menu bar.

         @param style
             If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
     */
         @param style
             If wxMB_DOCKABLE the menu bar can be detached (wxGTK only).
     */

-    wxMenuBar(long style = 0);

     wxMenuBar(size_t n, wxMenu* menus[], const wxString titles[],
               long style = 0);
     wxMenuBar(size_t n, wxMenu* menus[], const wxString titles[],
               long style = 0);

-    //@}

 
     /**
         Destructor, destroying the menu bar and removing it from the parent frame (if
 
     /**
         Destructor, destroying the menu bar and removing it from the parent frame (if


@@ -54,7 +59,7 @@ public:
         @param title
             The title of the menu.
 
         @param title
             The title of the menu.
 

-        @returns @true on success, @false if an error occurred.
+        @return @true on success, @false if an error occurred.

 
         @see Insert()
     */
 
         @see Insert()
     */


@@ -106,7 +111,7 @@ public:
         @param menu
             If not @NULL, menu will get set to the associated menu.
 
         @param menu
             If not @NULL, menu will get set to the associated menu.
 

-        @returns The found menu item object, or @NULL if one was not found.
+        @return The found menu item object, or @NULL if one was not found.

     */
     wxMenuItem* FindItem(int id, wxMenu menu = NULL) const;
 
     */
     wxMenuItem* FindItem(int id, wxMenu menu = NULL) const;
 


@@ -126,7 +131,7 @@ public:
         @param itemString
             Item to find.
 
         @param itemString
             Item to find.
 

-        @returns The menu item identifier, or wxNOT_FOUND if none was found.
+        @return The menu item identifier, or wxNOT_FOUND if none was found.

 
         @remarks Any special menu codes are stripped out of source and target
                  strings before matching.
 
         @remarks Any special menu codes are stripped out of source and target
                  strings before matching.


@@ -140,8 +145,8 @@ public:
         @param id
             The menu item identifier.
 
         @param id
             The menu item identifier.
 

-        @returns The help string, or the empty string if there was no help string
-                 or the menu item was not found.
+        @return The help string, or the empty string if there was no help string
+                or the menu item was not found.

 
         @see SetHelpString()
     */
 
         @see SetHelpString()
     */


@@ -153,8 +158,8 @@ public:
         @param id
             The menu item identifier.
 
         @param id
             The menu item identifier.
 

-        @returns The menu item label, or the empty string if the item was not
-                 found.
+        @return The menu item label, or the empty string if the item was not
+                found.

 
         @remarks Use only after the menubar has been associated with a frame.
     */
 
         @remarks Use only after the menubar has been associated with a frame.
     */


@@ -168,7 +173,7 @@ public:
         @param pos
             Position of the menu on the menu bar, starting from zero.
 
         @param pos
             Position of the menu on the menu bar, starting from zero.
 

-        @returns The menu label, or the empty string if the menu was not found.
+        @return The menu label, or the empty string if the menu was not found.

 
         @remarks Use only after the menubar has been associated with a frame.
 
 
         @remarks Use only after the menubar has been associated with a frame.
 


@@ -194,7 +199,7 @@ public:
         @param pos
             Position of the menu on the menu bar, starting from zero.
 
         @param pos
             Position of the menu on the menu bar, starting from zero.
 

-        @returns The menu label, or the empty string if the menu was not found.
+        @return The menu label, or the empty string if the menu was not found.

 
         @remarks Use only after the menubar has been associated with a frame.
 
 
         @remarks Use only after the menubar has been associated with a frame.
 


@@ -210,7 +215,7 @@ public:
         @param pos
             Position of the menu on the menu bar, starting from zero.
 
         @param pos
             Position of the menu on the menu bar, starting from zero.
 

-        @returns The menu label, or the empty string if the menu was not found.
+        @return The menu label, or the empty string if the menu was not found.

 
         @remarks Use only after the menubar has been associated with a frame.
 
 
         @remarks Use only after the menubar has been associated with a frame.
 


@@ -231,7 +236,7 @@ public:
         @param title
             The title of the menu.
 
         @param title
             The title of the menu.
 

-        @returns @true on success, @false if an error occurred.
+        @return @true on success, @false if an error occurred.

 
         @see Append()
     */
 
         @see Append()
     */


@@ -243,7 +248,7 @@ public:
         @param id
             The menu item identifier.
 
         @param id
             The menu item identifier.
 

-        @returns @true if the item was found and is checked, @false otherwise.
+        @return @true if the item was found and is checked, @false otherwise.

     */
     bool IsChecked(int id) const;
 
     */
     bool IsChecked(int id) const;
 


@@ -253,7 +258,7 @@ public:
         @param id
             The menu item identifier.
 
         @param id
             The menu item identifier.
 

-        @returns @true if the item was found and is enabled, @false otherwise.
+        @return @true if the item was found and is enabled, @false otherwise.

     */
     bool IsEnabled(int id) const;
 
     */
     bool IsEnabled(int id) const;
 


@@ -282,8 +287,8 @@ public:
         @param title
             The title of the menu.
 
         @param title
             The title of the menu.
 

-        @returns The menu which was previously at position pos. The caller is
-                 responsible for deleting it.
+        @return The menu which was previously at position pos. The caller is
+                responsible for deleting it.

 
         @see Insert(), Remove()
     */
 
         @see Insert(), Remove()
     */


@@ -385,23 +390,31 @@ public:
     @library{wxcore}
     @category{menus}
 
     @library{wxcore}
     @category{menus}
 

-    @see wxMenuBar, wxWindow::PopupMenu, @ref overview_eventhandlingoverview, @ref
-    overview_wxfilehistory "wxFileHistory (most recently used files menu)"
+    @see wxMenuBar, wxWindow::PopupMenu,
+    @ref overview_eventhandling "Event Handling Overview",
+    @ref wxFileHistory "wxFileHistory (most recently used files menu)"

 */
 class wxMenu : public wxEvtHandler
 {
 public:
 */
 class wxMenu : public wxEvtHandler
 {
 public:

-    //@{

     /**
         Constructs a wxMenu object.
 
         @param style
             If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
     */
     /**
         Constructs a wxMenu object.
 
         @param style
             If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
     */

-    wxMenu(const wxString& title = "", long style = 0);

     wxMenu(long style);
     wxMenu(long style);

-    //@}

 
 

+    /**
+        Constructs a wxMenu object with a title
+
+        @param title
+            Title at the top of the menu (not always supported).
+        @param style
+            If set to wxMENU_TEAROFF, the menu will be detachable (wxGTK only).
+    */
+    wxMenu(const wxString& title = "", long style = 0);
+    

     /**
         Destructor, destroying the menu.
         Note: under Motif, a popup menu must have a valid parent (the window
     /**
         Destructor, destroying the menu.
         Note: under Motif, a popup menu must have a valid parent (the window


@@ -413,45 +426,68 @@ public:
     */
     ~wxMenu();
 
     */
     ~wxMenu();
 

-    //@{

     /**
     /**

-        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.
+        Adds a menu item. 

 
         @param id
             The menu command identifier.
         @param item
             The string to appear on the menu item.
 
         @param id
             The menu command identifier.
         @param item
             The string to appear on the menu item.

-        @param menu
-            Pull-right submenu.
+        @param helpString
+            An optional help string associated with the item.
+            By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
+            this string in the status line.

         @param kind
             May be wxITEM_SEPARATOR, wxITEM_NORMAL,
             wxITEM_CHECK or wxITEM_RADIO
         @param kind
             May be wxITEM_SEPARATOR, wxITEM_NORMAL,
             wxITEM_CHECK or wxITEM_RADIO

+
+        @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
+             AppendSubMenu(), Insert(), SetLabel(),
+             GetHelpString(), SetHelpString(), wxMenuItem
+    */
+    wxMenuItem* Append(int id, const wxString& item = wxEmptyString,
+                       const wxString& helpString = wxEmptyString,
+                       wxItemKind kind = wxITEM_NORMAL);
+                       
+    /**
+        Adds a submenu.
+
+        @deprecated This function is deprecated, use AppendSubMenu() instead.
+
+        @param id
+            The menu command identifier.
+        @param item
+            The string to appear on the menu item.
+        @param subMenu
+            Pull-right submenu.

         @param helpString
             An optional help string associated with the item.
             By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
             this string in the status line.
         @param helpString
             An optional help string associated with the item.
             By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
             this string in the status line.

+
+        @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
+             AppendSubMenu(), Insert(), SetLabel(),
+             GetHelpString(), SetHelpString(), wxMenuItem
+    */
+    wxMenuItem* Append(int id, const wxString& item,
+                       wxMenu* subMenu,
+                       const wxString& helpString = wxEmptyString);
+                       
+    /**
+        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.
+

         @param menuItem
             A menuitem object. It will be owned by the wxMenu object after this function
             is called, so do not delete it yourself.
 
         @param menuItem
             A menuitem object. It will be owned by the wxMenu object after this function
             is called, so do not delete it yourself.
 

-        @remarks This command can be used after the menu has been shown, as well
-                 as on initial creation of a menu or menubar.
-

         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
              AppendSubMenu(), Insert(), SetLabel(),
              GetHelpString(), SetHelpString(), wxMenuItem
     */
         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
              AppendSubMenu(), Insert(), SetLabel(),
              GetHelpString(), SetHelpString(), wxMenuItem
     */

-    wxMenuItem* Append(int id, const wxString& item = "",
-                       const wxString& helpString = "",
-                       wxItemKind kind = wxITEM_NORMAL);
-    wxMenuItem* Append(int id, const wxString& item,
-                       wxMenu* subMenu,
-                       const wxString& helpString = "");

     wxMenuItem* Append(wxMenuItem* menuItem);
     wxMenuItem* Append(wxMenuItem* menuItem);

-    //@}

 
     /**
         Adds a checkable item to the end of the menu.
 
     /**
         Adds a checkable item to the end of the menu.


@@ -504,39 +540,51 @@ public:
     */
     void Check(int id, const bool check);
 
     */
     void Check(int id, const bool check);
 

-    //@{

     /**
         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

-        @b not be deleted. Use Destroy() if you want to
-        delete a submenu.
+        @b not be deleted. Use Destroy() if you want to delete a submenu.

 
         @param id
             Id of the menu item to be deleted.
 
         @param id
             Id of the menu item to be deleted.

+
+        @see FindItem(), Destroy(), Remove()
+    */
+    void Delete(int id);
+
+    /**
+        Deletes the menu item from the menu. If the item is a submenu, it will
+        @b not be deleted. Use Destroy() if you want to delete a submenu.
+

         @param item
             Menu item to be deleted.
 
         @see FindItem(), Destroy(), Remove()
     */
         @param item
             Menu item to be deleted.
 
         @see FindItem(), Destroy(), Remove()
     */

-    void Delete(int id);

     void Delete(wxMenuItem* item);
     void Delete(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 Remove() if you want to keep the submenu
-        (for example, to reuse it later).
+        be deleted. Use Remove() if you want to keep the submenu (for example,
+        to reuse it later).

 
         @param id
             Id of the menu item to be deleted.
 
         @param id
             Id of the menu item to be deleted.

+
+        @see FindItem(), Deletes(), Remove()
+    */
+    void Destroy(int id);
+
+    /**
+        Deletes the menu item from the menu. If the item is a submenu, it will
+        be deleted. Use Remove() if you want to keep the submenu (for example,
+        to reuse it later).
+

         @param item
             Menu item to be deleted.
 
         @see FindItem(), Deletes(), Remove()
     */
         @param item
             Menu item to be deleted.
 
         @see FindItem(), Deletes(), Remove()
     */

-    void Destroy(int id);

     void Destroy(wxMenuItem* item);
     void Destroy(wxMenuItem* item);

-    //@}

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


@@ -550,28 +598,32 @@ public:
     */
     void Enable(int id, const bool enable);
 
     */
     void Enable(int id, const bool enable);
 

-    //@{

     /**
     /**

-        Finds the menu item object associated with the given menu item identifier and,
-        optionally, the (sub)menu it belongs to.
+        Finds the menu id for a menu item string.

 
         @param itemString
             Menu item string to find.
 
         @param itemString
             Menu item string to find.

+
+        @return Menu item identifier, or wxNOT_FOUND if none is found.
+
+        @remarks Any special menu codes are stripped out of source and target
+                 strings before matching.
+    */
+    int FindItem(const wxString& itemString) const;
+
+    /**
+        Finds the menu item object associated with the given menu item identifier and,
+        optionally, the (sub)menu it belongs to.
+

         @param id
             Menu item identifier.
         @param menu
             If the pointer is not @NULL, it will be filled with the item's
             parent menu (if the item was found)
 
         @param id
             Menu item identifier.
         @param menu
             If the pointer is not @NULL, it will be filled with the item's
             parent menu (if the item was found)
 

-        @returns First form: menu item identifier, or wxNOT_FOUND if none is
-                 found.
-
-        @remarks Any special menu codes are stripped out of source and target
-                 strings before matching.
+        @return Menu item object or NULL if none is found.

     */
     */

-    int FindItem(const wxString& itemString) const;

     const wxMenuItem *  FindItem(int id, wxMenu** menu = NULL) const;
     const wxMenuItem *  FindItem(int id, wxMenu** menu = NULL) const;

-    //@}

 
     /**
         Returns the wxMenuItem given a position in the menu.
 
     /**
         Returns the wxMenuItem given a position in the menu.


@@ -584,8 +636,8 @@ public:
         @param id
             The menu item identifier.
 
         @param id
             The menu item identifier.
 

-        @returns The help string, or the empty string if there is no help string
-                 or the item was not found.
+        @return The help string, or the empty string if there is no help string
+                or the item was not found.

 
         @see SetHelpString(), Append()
     */
 
         @see SetHelpString(), Append()
     */


@@ -597,7 +649,7 @@ public:
         @param id
             The menu item identifier.
 
         @param id
             The menu item identifier.
 

-        @returns The item label, or the empty string if the item was not found.
+        @return The item label, or the empty string if the item was not found.

 
         @see GetLabelText(), SetLabel()
     */
 
         @see GetLabelText(), SetLabel()
     */


@@ -610,7 +662,7 @@ public:
         @param id
             The menu item identifier.
 
         @param id
             The menu item identifier.
 

-        @returns The item label, or the empty string if the item was not found.
+        @return The item label, or the empty string if the item was not found.

 
         @see GetLabel(), SetLabel()
     */
 
         @see GetLabel(), SetLabel()
     */


@@ -637,7 +689,6 @@ public:
     */
     wxString GetTitle() const;
 
     */
     wxString GetTitle() const;
 

-    //@{

     /**
         Inserts the given @a item before the position @e pos. Inserting the item
         at position GetMenuItemCount() is the same
     /**
         Inserts the given @a item before the position @e pos. Inserting the item
         at position GetMenuItemCount() is the same


@@ -646,11 +697,18 @@ public:
         @see Append(), Prepend()
     */
     wxMenuItem* Insert(size_t pos, wxMenuItem* item);
         @see Append(), Prepend()
     */
     wxMenuItem* Insert(size_t pos, wxMenuItem* item);

+    
+    /**
+        Inserts the given @a item before the position @e pos. Inserting the item
+        at position GetMenuItemCount() is the same
+        as appending it.
+
+        @see Append(), Prepend()
+    */

     wxMenuItem* Insert(size_t pos, int id,
                        const wxString& item = "",
                        const wxString& helpString = "",
                        wxItemKind kind = wxITEM_NORMAL);
     wxMenuItem* Insert(size_t pos, int id,
                        const wxString& item = "",
                        const wxString& helpString = "",
                        wxItemKind kind = wxITEM_NORMAL);

-    //@}

 
     /**
         Inserts a checkable item at the given position.
 
     /**
         Inserts a checkable item at the given position.


@@ -683,7 +741,7 @@ public:
         @param id
             The menu item identifier.
 
         @param id
             The menu item identifier.
 

-        @returns @true if the menu item is checked, @false otherwise.
+        @return @true if the menu item is checked, @false otherwise.

 
         @see Check()
     */
 
         @see Check()
     */


@@ -695,13 +753,12 @@ public:
         @param id
             The menu item identifier.
 
         @param id
             The menu item identifier.
 

-        @returns @true if the menu item is enabled, @false otherwise.
+        @return @true if the menu item is enabled, @false otherwise.

 
         @see Enable()
     */
     bool IsEnabled(int id) const;
 
 
         @see Enable()
     */
     bool IsEnabled(int id) const;
 

-    //@{

     /**
         Inserts the given @a item at position 0, i.e. before all the other
         existing items.
     /**
         Inserts the given @a item at position 0, i.e. before all the other
         existing items.


@@ -709,10 +766,16 @@ public:
         @see Append(), Insert()
     */
     wxMenuItem* Prepend(wxMenuItem* item);
         @see Append(), Insert()
     */
     wxMenuItem* Prepend(wxMenuItem* item);

+
+    /**
+        Inserts the given @a item at position 0, i.e. before all the other
+        existing items.
+
+        @see Append(), Insert()
+    */

     wxMenuItem* Prepend(int id, const wxString& item = "",
                         const wxString& helpString = "",
                         wxItemKind kind = wxITEM_NORMAL);
     wxMenuItem* Prepend(int id, const wxString& item = "",
                         const wxString& helpString = "",
                         wxItemKind kind = wxITEM_NORMAL);

-    //@}

 
     /**
         Inserts a checkable item at position 0.
 
     /**
         Inserts a checkable item at position 0.


@@ -737,22 +800,29 @@ public:
     */
     wxMenuItem* PrependSeparator();
 
     */
     wxMenuItem* PrependSeparator();
 

-    //@{

     /**
         Removes the menu item from the menu but doesn't delete the associated C++
     /**
         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
+        object. This allows you to reuse the same item later by adding it back to the menu

         (especially useful with submenus).
 
         @param id
             The identifier of the menu item to remove.
         (especially useful with submenus).
 
         @param id
             The identifier of the menu item to remove.

+
+        @return A pointer to the item which was detached from the menu.
+    */
+    wxMenuItem* Remove(int id);
+    
+    /**
+        Removes the menu item from the menu but doesn't delete the associated C++
+        object. This allows you to reuse the same item later by adding it back to the menu
+        (especially useful with submenus).
+

         @param item
             The menu item to remove.
 
         @param item
             The menu item to remove.
 

-        @returns The item which was detached from the menu.
+        @return A pointer to the item which was detached from the menu.

     */
     */

-    wxMenuItem* Remove(int id);

     wxMenuItem* Remove(wxMenuItem* item);
     wxMenuItem* Remove(wxMenuItem* item);

-    //@}

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