add a detailed description to wxMenuItem::SetItemLabel() partially moving docs from wxMenu::Append; add usage examples; organize wxMenuItem functions in 3 sections (getters, setters, checkers) to make it easier to browse the docs; use @onlyfor tag where necessary instead of the (Windows only) text

git-svn-id: https://svn.wxwidgets.org/svn/wx/wxWidgets/trunk@62956 c3d73ce0-8a6f-49c7-b76d-6d57e0e08775

interface/wx/menu.h

@@ -486,45 +486,27 @@ public:
             The menu command identifier.
         @param item
             The string to appear on the menu item.
+            See wxMenuItem::SetItemLabel() for more details.
         @param helpString
             An optional help string associated with the item.
-            By default, the handler for the wxEVT_MENU_HIGHLIGHT event displays
+            By default, the handler for the @c wxEVT_MENU_HIGHLIGHT event displays
             this string in the status line.
         @param kind
-            May be wxITEM_SEPARATOR, wxITEM_NORMAL, wxITEM_CHECK or wxITEM_RADIO
+            May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or @c wxITEM_RADIO.
+        
+        Example:
+        @code
+        m_pFileMenu->Append(ID_NEW_FILE, "&New file\tCTRL+N", "Creates a new XYZ document");
+        @endcode
+        or even better for stock menu items (see wxMenuItem::wxMenuItem):
+        @code
+        m_pFileMenu->Append(wxID_NEW, "", "Creates a new XYZ document");
+        @endcode
 
         @remarks
         This command can be used after the menu has been shown, as well as on
         initial creation of a menu or menubar.
 
-        The item string for the normal menu items (not submenus or separators)
-        may include the accelerator which can be used to activate the menu item
-        from keyboard.
-        The accelerator string follows the item label and is separated from it
-        by a TAB character ('\\t').
-
-        Its general syntax is any combination of "CTRL", "ALT" and "SHIFT" strings
-        (case doesn't matter) separated by either '-' or '+' characters and followed
-        by the accelerator itself.
-        The accelerator may be any alphanumeric character, any function key
-        (from F1 to F12) or one of the special characters listed in the table
-        below (again, case doesn't matter):
-
-        - DEL or DELETE: Delete key
-        - INS or INSERT: Insert key
-        - ENTER or RETURN: Enter key
-        - PGUP: PageUp key
-        - PGDN: PageDown key
-        - LEFT: Left cursor arrow key
-        - RIGHT: Right cursor arrow key
-        - UP: Up cursor arrow key
-        - DOWN: Down cursor arrow key
-        - HOME: Home key
-        - END: End key
-        - SPACE: Space
-        - TAB: Tab key
-        - ESC: or ESCAPE Escape key (Windows only)
-
         @see AppendSeparator(), AppendCheckItem(), AppendRadioItem(),
              AppendSubMenu(), Insert(), SetLabel(), GetHelpString(),
              SetHelpString(), wxMenuItem

interface/wx/menuitem.h

@@ -91,9 +91,8 @@ public:
             case the given kind is ignored and taken to be @c wxITEM_SEPARATOR
             instead.
         @param text
-            Text for the menu item, as shown on the menu. An accelerator key can
+            Text for the menu item, as shown on the menu.
-            be specified using the ampersand @c & character. In order to embed an
+            See SetItemLabel() for more info.
-            ampersand character in the menu item text, the ampersand must be doubled.
         @param helpString
             Optional help string that will be shown on the status bar.
         @param kind
@@ -125,17 +124,50 @@ public:
     virtual void Enable(bool enable = true);
 
     /**
-        Returns the background colour associated with the menu item (Windows only).
+        @deprecated This function is deprecated; please use GetLabelText() instead.
+
+        @see GetLabelText()
+    */
+    static wxString GetLabelFromText(const wxString& text);
+
+    /**
+        Strips all accelerator characters and mnemonics from the given @a text.
+        For example:
+
+        @code
+          wxMenuItem::GetLabelfromText("&Hello\tCtrl-h");
+        @endcode
+
+        will return just @c "Hello".
+
+        @see GetItemLabelText(), GetItemLabel()
+    */
+    static wxString GetLabelText(const wxString& text);
+    
+    
+    /**
+        @name Getters
+    */
+    //@{
+    
+    /**
+        Returns the background colour associated with the menu item.
+        
+        @onlyfor{wxmsw}
     */
     wxColour GetBackgroundColour() const;
 
     /**
-        Returns the checked or unchecked bitmap (Windows only).
+        Returns the checked or unchecked bitmap.
+        
+        @onlyfor{wxmsw}
     */
     virtual const wxBitmap& GetBitmap() const;
 
     /**
-        Returns the font associated with the menu item (Windows only).
+        Returns the font associated with the menu item.
+        
+        @onlyfor{wxmsw}
     */
     wxFont GetFont() const;
 
@@ -177,33 +209,14 @@ public:
 
         @deprecated This function is deprecated in favour of GetItemLabelText().
 
-        @see GetText(), GetLabelFromText()
+        @see GetItemLabelText()
     */
     wxString GetLabel() const;
 
     /**
-        @deprecated This function is deprecated; please use GetLabelText() instead.
+        Gets the width of the menu item checkmark bitmap.
         
-        @see GetText(), GetLabel()
+        @onlyfor{wxmsw}
-    */
-    static wxString GetLabelFromText(const wxString& text);
-
-    /**
-        Strips all accelerator characters and mnemonics from the given @a text.
-        For example:
-
-        @code
-          wxMenuItem::GetLabelfromText("&Hello\tCtrl-h");
-        @endcode
-
-        will return just @c "Hello".
-
-        @see GetItemLabelText(), GetItemLabel()
-    */
-    static wxString GetLabelText(const wxString& text);
-
-    /**
-        Gets the width of the menu item checkmark bitmap (Windows only).
     */
     int GetMarginWidth() const;
 
@@ -216,9 +229,9 @@ public:
     /**
         Returns the text associated with the menu item.
 
-        @deprecated This function is deprecated. Please use
+        @deprecated This function is deprecated. Please use GetItemLabel() or GetItemLabelText() instead.
         
-        GetItemLabel() or GetItemLabelText() instead.
+        @see GetItemLabel(), GetItemLabelText()
     */
     wxString GetName() const;
 
@@ -233,15 +246,26 @@ public:
 
         @deprecated This function is deprecated in favour of GetItemLabel().
 
-        @see GetLabel(), GetLabelFromText()
+        @see GetLabelFromText()
     */
     const wxString& GetText() const;
 
     /**
-        Returns the text colour associated with the menu item (Windows only).
+        Returns the text colour associated with the menu item.
+        
+        @onlyfor{wxmsw}
     */
     wxColour GetTextColour() const;
     
+    //@}
+    
+    
+    
+    /**
+        @name Checkers
+    */
+    //@{
+
     /**
         Returns @true if the item is checkable.
     */
@@ -267,16 +291,27 @@ public:
     */
     bool IsSubMenu() const;
     
+    //@}
+    
+    
+    
     /**
-        Sets the background colour associated with the menu item (Windows only).
+        @name Setters
+    */
+    //@{
+
+    /**
+        Sets the background colour associated with the menu item.
+        
+        @onlyfor{wxmsw}
     */
     void SetBackgroundColour(const wxColour& colour) const;
 
     /**
         Sets the bitmap for the menu item.
 
-        It is equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap) if @a
+        It is equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap) if 
-        checked is @true (default value) or SetBitmaps(wxNullBitmap, bmp)
+        @a checked is @true (default value) or SetBitmaps(wxNullBitmap, bmp)
         otherwise.
 
         @onlyfor{wxmsw,wxosx,wxgtk}
@@ -293,7 +328,9 @@ public:
                     const wxBitmap& unchecked = wxNullBitmap);
 
     /**
-        Sets the font associated with the menu item (Windows only).
+        Sets the font associated with the menu item.
+        
+        @onlyfor{wxmsw}
     */
     void SetFont(const wxFont& font);
 
@@ -304,11 +341,58 @@ public:
 
     /**
         Sets the label associated with the menu item.
+        
+        Note that if the ID of this menu item corrisponds to a stock ID, then it is 
+        not necessary to specify a label: wxWidgets will automatically use the stock
+        item label associated with that ID. See the @ref wxMenuItem::wxMenuItem "constructor"
+        for more info.
+        
+        The label string for the normal menu items (not separators) may include the 
+        accelerator which can be used to activate the menu item from keyboard.
+        An accelerator key can be specified using the ampersand <tt>&</tt> character. 
+        In order to embed an ampersand character in the menu item text, the ampersand 
+        must be doubled.
+        
+        Optionally you can specify also an accelerator string appending a tab character 
+        <tt>\\t</tt> followed by a valid key combination (e.g. <tt>CTRL+V</tt>).
+        Its general syntax is any combination of @c "CTRL", @c "ALT" and @c "SHIFT" strings
+        (case doesn't matter) separated by either @c '-' or @c '+' characters and followed
+        by the accelerator itself.
+        The accelerator may be any alphanumeric character, any function key
+        (from F1 to F12) or one of the special characters listed in the table
+        below (again, case doesn't matter):
+        - @c DEL or @c DELETE: Delete key
+        - @c INS or @c INSERT: Insert key
+        - @c ENTER or @c RETURN: Enter key
+        - @c PGUP: PageUp key
+        - @c PGDN: PageDown key
+        - @c LEFT: Left cursor arrow key
+        - @c RIGHT: Right cursor arrow key
+        - @c UP: Up cursor arrow key
+        - @c DOWN: Down cursor arrow key
+        - @c HOME: Home key
+        - @c END: End key
+        - @c SPACE: Space
+        - @c TAB: Tab key
+        - @c ESC or @c ESCAPE: Escape key (Windows only)
+
+        Examples:
+
+        @code
+        m_pMyMenuItem->SetItemLabel("My &item\tCTRL+I");
+        m_pMyMenuItem2->SetItemLabel("Clean && build\tF7");
+        m_pMyMenuItem3->SetItemLabel("Simple item");
+        m_pMyMenuItem4->SetItemLabel("Item with &accelerator");
+        @endcode
+        
+        @see GetItemLabel(), GetItemLabelText()
     */
     virtual void SetItemLabel(const wxString& label);
 
     /**
-        Sets the width of the menu item checkmark bitmap (Windows only).
+        Sets the width of the menu item checkmark bitmap.
+        
+        @onlyfor{wxmsw}
     */
     void SetMarginWidth(int width) const;
 
@@ -326,12 +410,18 @@ public:
         Sets the text associated with the menu item.
 
         @deprecated This function is deprecated in favour of SetItemLabel().
+        
+        @see SetItemLabel().
     */
     virtual void SetText(const wxString& text);
 
     /**
-        Sets the text colour associated with the menu item (Windows only).
+        Sets the text colour associated with the menu item.
+        
+        @onlyfor{wxmsw}
     */
     void SetTextColour(const wxColour& colour);
+    
+    //@}
 };