interface/wx/menuitem.h

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        menuitem.h
   3 // Purpose:     interface of wxMenu, wxMenuItem
   4 // Author:      wxWidgets team
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows license
   7 /////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxMenuItem
  11
  12     A menu item represents an item in a menu.
  13
  14     Note that you usually don't have to deal with it directly as wxMenu methods
  15     usually construct an object of this class for you.
  16
  17     Also please note that the methods related to fonts and bitmaps are currently
  18     only implemented for Windows, Mac and GTK+.
  19
  20     @library{wxcore}
  21     @category{menus}
  22
  23     @see wxMenuBar, wxMenu
  24 */
  25 class wxMenuItem : public wxObject
  26 {
  27 public:
  28     /**
  29         Constructs a wxMenuItem object.
  30
  31         Menu items can be standard, or "stock menu items", or custom.
  32         For the standard menu items (such as commands to open a file, exit the
  33         program and so on, see @ref page_stockitems for the full list) it is enough
  34         to specify just the stock ID and leave @a text and @a helpString empty.
  35
  36         In fact, leaving at least @a text empty for the stock menu items is strongly
  37         recommended as they will have appearance and keyboard interface (including
  38         standard accelerators) familiar to the user.
  39
  40         For the custom (non-stock) menu items, @a text must be specified and while
  41         @a helpString may be left empty, it's recommended to pass the item
  42         description (which is automatically shown by the library in the status bar
  43         when the menu item is selected) in this parameter.
  44
  45         Finally note that you can e.g. use a stock menu label without using its stock
  46         help string:
  47
  48         @code
  49         // use all stock properties:
  50         helpMenu->Append(wxID_ABOUT);
  51
  52         // use the stock label and the stock accelerator but not the stock help string:
  53         helpMenu->Append(wxID_ABOUT, wxEmptyString, wxT("My custom help string"));
  54
  55         // use all stock properties except for the bitmap:
  56         wxMenuItem *mymenu = new wxMenuItem(helpMenu, wxID_ABOUT);
  57         mymenu->SetBitmap(wxArtProvider::GetBitmap(wxART_WARNING));
  58         helpMenu->Append(mymenu);
  59         @endcode
  60
  61         that is, stock properties are set independently one from the other.
  62
  63         @param parentMenu
  64             Menu that the menu item belongs to. Can be @NULL if the item is
  65             going to be added to the menu later.
  66         @param id
  67             Identifier for this menu item. May be @c wxID_SEPARATOR, in which
  68             case the given kind is ignored and taken to be @c wxITEM_SEPARATOR
  69             instead.
  70         @param text
  71             Text for the menu item, as shown on the menu. An accelerator key can
  72             be specified using the ampersand " character. In order to embed an
  73             ampersand character in the menu item text, the ampersand must be doubled.
  74         @param helpString
  75             Optional help string that will be shown on the status bar.
  76         @param kind
  77             May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or
  78             @c wxITEM_RADIO.
  79         @param subMenu
  80             If non-@NULL, indicates that the menu item is a submenu.
  81     */
  82     wxMenuItem(wxMenu* parentMenu = NULL, int id = wxID_SEPARATOR,
  83                const wxString& text = wxEmptyString,
  84                const wxString& helpString = wxEmptyString,
  85                wxItemKind kind = wxITEM_NORMAL,
  86                wxMenu* subMenu = NULL);
  87
  88     /**
  89         Destructor.
  90     */
  91     virtual ~wxMenuItem();
  92
  93     /**
  94         Checks or unchecks the menu item.
  95         Note that this only works when the item is already appended to a menu.
  96     */
  97     virtual void Check(bool check = true);
  98
  99     /**
 100         Enables or disables the menu item.
 101     */
 102     virtual void Enable(bool enable = true);
 103
 104     /**
 105         Returns the background colour associated with the menu item (Windows only).
 106     */
 107     wxColour GetBackgroundColour() const;
 108
 109     /**
 110         Returns the checked or unchecked bitmap (Windows only).
 111     */
 112     virtual const wxBitmap& GetBitmap() const;
 113
 114     /**
 115         Returns the font associated with the menu item (Windows only).
 116     */
 117     wxFont GetFont() const;
 118
 119     /**
 120         Returns the help string associated with the menu item.
 121     */
 122     const wxString& GetHelp() const;
 123
 124     /**
 125         Returns the menu item identifier.
 126     */
 127     int GetId() const;
 128
 129     /**
 130         Returns the text associated with the menu item including any accelerator
 131         characters that were passed to the constructor or SetItemLabel().
 132
 133         @see GetItemLabelText(), GetLabelText()
 134     */
 135     virtual wxString GetItemLabel() const;
 136
 137     /**
 138         Returns the text associated with the menu item, without any accelerator
 139         characters.
 140
 141         @see GetItemLabel(), GetLabelText()
 142     */
 143     virtual wxString GetItemLabelText() const;
 144
 145     /**
 146         Returns the item kind, one of @c wxITEM_SEPARATOR, @c wxITEM_NORMAL,
 147         @c wxITEM_CHECK or @c wxITEM_RADIO.
 148     */
 149     wxItemKind GetKind() const;
 150
 151     /**
 152         Returns the text associated with the menu item without any accelerator
 153         characters it might contain.
 154
 155         @deprecated This function is deprecated in favour of GetItemLabelText().
 156
 157         @see GetText(), GetLabelFromText()
 158     */
 159     wxString GetLabel() const;
 160
 161     /**
 162         @deprecated This function is deprecated; please use GetLabelText() instead.
 163
 164         @see GetText(), GetLabel()
 165     */
 166     static wxString GetLabelFromText(const wxString& text);
 167
 168     /**
 169         Strips all accelerator characters and mnemonics from the given @a text.
 170         For example:
 171
 172         @code
 173           wxMenuItem::GetLabelfromText("&Hello\tCtrl-h");
 174         @endcode
 175
 176         will return just @c "Hello".
 177
 178         @see GetItemLabelText(), GetItemLabel()
 179     */
 180     static wxString GetLabelText(const wxString& text);
 181
 182     /**
 183         Gets the width of the menu item checkmark bitmap (Windows only).
 184     */
 185     int GetMarginWidth() const;
 186
 187     /**
 188         Returns the menu this menu item is in, or @NULL if this menu item is not
 189         attached.
 190     */
 191     wxMenu* GetMenu() const;
 192
 193     /**
 194         Returns the text associated with the menu item.
 195
 196         @deprecated This function is deprecated. Please use
 197
 198         GetItemLabel() or GetItemLabelText() instead.
 199     */
 200     wxString GetName() const;
 201
 202     /**
 203         Returns the submenu associated with the menu item, or @NULL if there isn't one.
 204     */
 205     wxMenu* GetSubMenu() const;
 206
 207     /**
 208         Returns the text associated with the menu item, such as it was passed to the
 209         wxMenuItem constructor, i.e. with any accelerator characters it may contain.
 210
 211         @deprecated This function is deprecated in favour of GetItemLabel().
 212
 213         @see GetLabel(), GetLabelFromText()
 214     */
 215     const wxString& GetText() const;
 216
 217     /**
 218         Returns the text colour associated with the menu item (Windows only).
 219     */
 220     wxColour GetTextColour() const;
 221
 222     /**
 223         Returns @true if the item is checkable.
 224     */
 225     bool IsCheckable() const;
 226
 227     /**
 228         Returns @true if the item is checked.
 229     */
 230     virtual bool IsChecked() const;
 231
 232     /**
 233         Returns @true if the item is enabled.
 234     */
 235     virtual bool IsEnabled() const;
 236
 237     /**
 238         Returns @true if the item is a separator.
 239     */
 240     bool IsSeparator() const;
 241
 242     /**
 243         Returns @true if the item is a submenu.
 244     */
 245     bool IsSubMenu() const;
 246
 247     /**
 248         Sets the background colour associated with the menu item (Windows only).
 249     */
 250     void SetBackgroundColour(const wxColour& colour) const;
 251
 252     /**
 253         Sets the bitmap for the menu item.
 254         It is equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap).
 255
 256         @onlyfor{wxmsw,wxmac,wxgtk}
 257     */
 258     virtual void SetBitmap(const wxBitmap& bmp);
 259
 260     /**
 261         Sets the checked/unchecked bitmaps for the menu item.
 262         The first bitmap is also used as the single bitmap for uncheckable menu items.
 263
 264         @onlyfor{wxmsw}
 265     */
 266     void SetBitmaps(const wxBitmap& checked,
 267                     const wxBitmap& unchecked = wxNullBitmap);
 268
 269     /**
 270         Sets the font associated with the menu item (Windows only).
 271     */
 272     void SetFont(const wxFont& font);
 273
 274     /**
 275         Sets the help string.
 276     */
 277     void SetHelp(const wxString& helpString);
 278
 279     /**
 280         Sets the label associated with the menu item.
 281     */
 282     virtual void SetItemLabel(const wxString& label);
 283
 284     /**
 285         Sets the width of the menu item checkmark bitmap (Windows only).
 286     */
 287     void SetMarginWidth(int width) const;
 288
 289     /**
 290         Sets the parent menu which will contain this menu item.
 291     */
 292     void SetMenu(wxMenu* menu);
 293
 294     /**
 295         Sets the submenu of this menu item.
 296     */
 297     void SetSubMenu(wxMenu* menu);
 298
 299     /**
 300         Sets the text associated with the menu item.
 301
 302         @deprecated This function is deprecated in favour of SetItemLabel().
 303     */
 304     virtual void SetText(const wxString& text);
 305
 306     /**
 307         Sets the text colour associated with the menu item (Windows only).
 308     */
 309     void SetTextColour(const wxColour& colour);
 310 };
 311