]> git.saurik.com Git - wxWidgets.git/blobdiff - interface/wx/menuitem.h
Add test for absence of events from wxSpinCtrlDouble ctor.
[wxWidgets.git] / interface / wx / menuitem.h
index da92070140f01d12a0b2a3e31118fdb1cd1479cc..af5a6d29435fe191a93e1909f5f518483a82da1e 100644 (file)
@@ -2,8 +2,7 @@
 // Name:        menuitem.h
 // Purpose:     interface of wxMenu, wxMenuItem
 // Author:      wxWidgets team
-// RCS-ID:      $Id$
-// Licence:     wxWindows license
+// Licence:     wxWindows licence
 /////////////////////////////////////////////////////////////////////////////
 
 /**
     Also please note that the methods related to fonts and bitmaps are currently
     only implemented for Windows, Mac and GTK+.
 
-    @beginEventTable{wxCommandEvent,wxMenuEvent}
+    @beginEventEmissionTable{wxCommandEvent,wxMenuEvent}
     @event{EVT_MENU(id, func)}
-        Process a @c wxEVT_COMMAND_MENU_SELECTED command, which is generated by a menu item.
+        Process a @c wxEVT_MENU command, which is generated by a menu item.
         This type of event is sent as wxCommandEvent.
     @event{EVT_MENU_RANGE(id1, id2, func)}
-        Process a @c wxEVT_COMMAND_MENU_RANGE command, which is generated by a range of menu items.
+        Process a @c wxEVT_MENU command, which is generated by a range of menu items.
         This type of event is sent as wxCommandEvent.
     @event{EVT_MENU_OPEN(func)}
         A menu is about to be opened. On Windows, this is only sent once for each
@@ -55,8 +54,10 @@ public:
         For the standard menu items (such as commands to open a file, exit the
         program and so on, see @ref page_stockitems for the full list) it is enough
         to specify just the stock ID and leave @a text and @a helpString empty.
+        Some platforms (currently wxGTK only, and see the remark in SetBitmap()
+        documentation) will also show standard bitmaps for stock menu items.
 
-        In fact, leaving at least @a text empty for the stock menu items is strongly
+        Leaving at least @a text empty for the stock menu items is actually strongly
         recommended as they will have appearance and keyboard interface (including
         standard accelerators) familiar to the user.
 
@@ -73,7 +74,7 @@ public:
         helpMenu->Append(wxID_ABOUT);
 
         // use the stock label and the stock accelerator but not the stock help string:
-        helpMenu->Append(wxID_ABOUT, wxEmptyString, wxT("My custom help string"));
+        helpMenu->Append(wxID_ABOUT, "", "My custom help string");
 
         // use all stock properties except for the bitmap:
         wxMenuItem *mymenu = new wxMenuItem(helpMenu, wxID_ABOUT);
@@ -91,9 +92,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
-            be specified using the ampersand " character. In order to embed an
-            ampersand character in the menu item text, the ampersand must be doubled.
+            Text for the menu item, as shown on the menu.
+            See SetItemLabel() for more info.
         @param helpString
             Optional help string that will be shown on the status bar.
         @param kind
@@ -125,19 +125,52 @@ 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
     */
-    wxColour GetBackgroundColour() const;
+    //@{
+    
+    /**
+        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;
+    wxFont& GetFont() const;
 
     /**
         Returns the help string associated with the menu item.
@@ -177,33 +210,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.
-
-        @see GetText(), GetLabel()
-    */
-    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).
+        Gets the width of the menu item checkmark bitmap.
+        
+        @onlyfor{wxmsw}
     */
     int GetMarginWidth() const;
 
@@ -216,9 +230,9 @@ public:
     /**
         Returns the text associated with the menu item.
 
-        @deprecated This function is deprecated. Please use
-
-        GetItemLabel() or GetItemLabelText() instead.
+        @deprecated This function is deprecated. Please use GetItemLabel() or GetItemLabelText() instead.
+        
+        @see GetItemLabel(), GetItemLabelText()
     */
     wxString GetName() const;
 
@@ -233,17 +247,41 @@ 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;
+    wxColour& GetTextColour() const;
+    
+    //@}
+    
+    
+    
+    /**
+        @name Checkers
+    */
+    //@{
+
+    /**
+        Returns @true if the item is a check item.
+
+        Unlike IsCheckable() this doesn't return @true for the radio buttons.
+
+        @since 2.9.5
+     */
+    bool IsCheck() const;
 
     /**
         Returns @true if the item is checkable.
+
+        Notice that the radio buttons are considered to be checkable as well,
+        so this method returns @true for them too. Use IsCheck() if you want to
+        test for the check items only.
     */
     bool IsCheckable() const;
 
@@ -257,6 +295,13 @@ public:
     */
     virtual bool IsEnabled() const;
 
+    /**
+        Returns @true if the item is a radio button.
+
+        @since 2.9.5
+     */
+    bool IsRadio() const;
+
     /**
         Returns @true if the item is a separator.
     */
@@ -266,19 +311,43 @@ public:
         Returns @true if the item is a submenu.
     */
     bool IsSubMenu() const;
+    
+    //@}
+    
+    
+    
+    /**
+        @name Setters
+    */
+    //@{
 
     /**
-        Sets the background colour associated with the menu item (Windows only).
+        Sets the background colour associated with the menu item.
+        
+        @onlyfor{wxmsw}
     */
-    void SetBackgroundColour(const wxColour& colour) const;
+    void SetBackgroundColour(const wxColour& colour);
 
     /**
         Sets the bitmap for the menu item.
-        It is equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap).
 
-        @onlyfor{wxmsw,wxmac,wxgtk}
+        It is equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap) if 
+        @a checked is @true (default value) or SetBitmaps(wxNullBitmap, bmp)
+        otherwise.
+
+        SetBitmap() must be called before the item is appended to the menu,
+        i.e. appending the item without a bitmap and setting one later is not
+        guaranteed to work. But the bitmap can be changed or reset later if it
+        had been set up initially.
+
+        Notice that GTK+ uses a global setting called @c gtk-menu-images to
+        determine if the images should be shown in the menus at all. If it is
+        off (which is the case in e.g. Gnome 2.28 by default), no images will
+        be shown, consistently with the native behaviour.
+
+        @onlyfor{wxmsw,wxosx,wxgtk}
     */
-    virtual void SetBitmap(const wxBitmap& bmp);
+    virtual void SetBitmap(const wxBitmap& bmp, bool checked = true);
 
     /**
         Sets the checked/unchecked bitmaps for the menu item.
@@ -290,7 +359,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);
 
@@ -301,13 +372,74 @@ public:
 
     /**
         Sets the label associated with the menu item.
+        
+        Note that if the ID of this menu item corresponds 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 "RAWCTRL",  @c
+        "ALT" and @c "SHIFT" strings (case doesn't matter) separated by either
+        @c '-' or @c '+' characters and followed by the accelerator itself.
+        Notice that @c CTRL corresponds to the "Ctrl" key on most platforms but
+        not under Mac OS where it is mapped to "Cmd" key on Mac keyboard.
+        Usually this is exactly what you want in portable code but if you
+        really need to use the (rarely used for this purpose) "Ctrl" key even
+        under Mac, you may use @c RAWCTRL to prevent this mapping. Under the
+        other platforms @c RAWCTRL is the same as plain @c CTRL.
+
+        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 BACK : Backspace 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
+
+        @note In wxGTK using @c "SHIFT" with non-alphabetic characters
+        currently doesn't work, even in combination with other modifiers, due
+        to GTK+ limitation. E.g. @c Shift+Ctrl+A works but @c Shift+Ctrl+1 or
+        @c Shift+/ do not, so avoid using accelerators of this form in portable
+        code.
+
+        @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;
+    void SetMarginWidth(int width);
 
     /**
         Sets the parent menu which will contain this menu item.
@@ -323,12 +455,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);
+    
+    //@}
 };