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