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.
  95             See SetItemLabel() for more info.
  96         @param helpString
  97             Optional help string that will be shown on the status bar.
  98         @param kind
  99             May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or
 100             @c wxITEM_RADIO.
 101         @param subMenu
 102             If non-@NULL, indicates that the menu item is a submenu.
 103     */
 104     wxMenuItem(wxMenu* parentMenu = NULL, int id = wxID_SEPARATOR,
 105                const wxString& text = wxEmptyString,
 106                const wxString& helpString = wxEmptyString,
 107                wxItemKind kind = wxITEM_NORMAL,
 108                wxMenu* subMenu = NULL);
 109
 110     /**
 111         Destructor.
 112     */
 113     virtual ~wxMenuItem();
 114
 115     /**
 116         Checks or unchecks the menu item.
 117         Note that this only works when the item is already appended to a menu.
 118     */
 119     virtual void Check(bool check = true);
 120
 121     /**
 122         Enables or disables the menu item.
 123     */
 124     virtual void Enable(bool enable = true);
 125
 126     /**
 127         @deprecated This function is deprecated; please use GetLabelText() instead.
 128
 129         @see GetLabelText()
 130     */
 131     static wxString GetLabelFromText(const wxString& text);
 132
 133     /**
 134         Strips all accelerator characters and mnemonics from the given @a text.
 135         For example:
 136
 137         @code
 138           wxMenuItem::GetLabelfromText("&Hello\tCtrl-h");
 139         @endcode
 140
 141         will return just @c "Hello".
 142
 143         @see GetItemLabelText(), GetItemLabel()
 144     */
 145     static wxString GetLabelText(const wxString& text);
 146
 147
 148     /**
 149         @name Getters
 150     */
 151     //@{
 152
 153     /**
 154         Returns the background colour associated with the menu item.
 155
 156         @onlyfor{wxmsw}
 157     */
 158     wxColour GetBackgroundColour() const;
 159
 160     /**
 161         Returns the checked or unchecked bitmap.
 162
 163         @onlyfor{wxmsw}
 164     */
 165     virtual const wxBitmap& GetBitmap() const;
 166
 167     /**
 168         Returns the font associated with the menu item.
 169
 170         @onlyfor{wxmsw}
 171     */
 172     wxFont GetFont() const;
 173
 174     /**
 175         Returns the help string associated with the menu item.
 176     */
 177     const wxString& GetHelp() const;
 178
 179     /**
 180         Returns the menu item identifier.
 181     */
 182     int GetId() const;
 183
 184     /**
 185         Returns the text associated with the menu item including any accelerator
 186         characters that were passed to the constructor or SetItemLabel().
 187
 188         @see GetItemLabelText(), GetLabelText()
 189     */
 190     virtual wxString GetItemLabel() const;
 191
 192     /**
 193         Returns the text associated with the menu item, without any accelerator
 194         characters.
 195
 196         @see GetItemLabel(), GetLabelText()
 197     */
 198     virtual wxString GetItemLabelText() const;
 199
 200     /**
 201         Returns the item kind, one of @c wxITEM_SEPARATOR, @c wxITEM_NORMAL,
 202         @c wxITEM_CHECK or @c wxITEM_RADIO.
 203     */
 204     wxItemKind GetKind() const;
 205
 206     /**
 207         Returns the text associated with the menu item without any accelerator
 208         characters it might contain.
 209
 210         @deprecated This function is deprecated in favour of GetItemLabelText().
 211
 212         @see GetItemLabelText()
 213     */
 214     wxString GetLabel() const;
 215
 216     /**
 217         Gets the width of the menu item checkmark bitmap.
 218
 219         @onlyfor{wxmsw}
 220     */
 221     int GetMarginWidth() const;
 222
 223     /**
 224         Returns the menu this menu item is in, or @NULL if this menu item is not
 225         attached.
 226     */
 227     wxMenu* GetMenu() const;
 228
 229     /**
 230         Returns the text associated with the menu item.
 231
 232         @deprecated This function is deprecated. Please use GetItemLabel() or GetItemLabelText() instead.
 233
 234         @see GetItemLabel(), GetItemLabelText()
 235     */
 236     wxString GetName() const;
 237
 238     /**
 239         Returns the submenu associated with the menu item, or @NULL if there isn't one.
 240     */
 241     wxMenu* GetSubMenu() const;
 242
 243     /**
 244         Returns the text associated with the menu item, such as it was passed to the
 245         wxMenuItem constructor, i.e. with any accelerator characters it may contain.
 246
 247         @deprecated This function is deprecated in favour of GetItemLabel().
 248
 249         @see GetLabelFromText()
 250     */
 251     const wxString& GetText() const;
 252
 253     /**
 254         Returns the text colour associated with the menu item.
 255
 256         @onlyfor{wxmsw}
 257     */
 258     wxColour GetTextColour() const;
 259
 260     //@}
 261
 262
 263
 264     /**
 265         @name Checkers
 266     */
 267     //@{
 268
 269     /**
 270         Returns @true if the item is checkable.
 271     */
 272     bool IsCheckable() const;
 273
 274     /**
 275         Returns @true if the item is checked.
 276     */
 277     virtual bool IsChecked() const;
 278
 279     /**
 280         Returns @true if the item is enabled.
 281     */
 282     virtual bool IsEnabled() const;
 283
 284     /**
 285         Returns @true if the item is a separator.
 286     */
 287     bool IsSeparator() const;
 288
 289     /**
 290         Returns @true if the item is a submenu.
 291     */
 292     bool IsSubMenu() const;
 293
 294     //@}
 295
 296
 297
 298     /**
 299         @name Setters
 300     */
 301     //@{
 302
 303     /**
 304         Sets the background colour associated with the menu item.
 305
 306         @onlyfor{wxmsw}
 307     */
 308     void SetBackgroundColour(const wxColour& colour) const;
 309
 310     /**
 311         Sets the bitmap for the menu item.
 312
 313         It is equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap) if
 314         @a checked is @true (default value) or SetBitmaps(wxNullBitmap, bmp)
 315         otherwise.
 316
 317         Notice that GTK+ uses a global setting called @c gtk-menu-images to
 318         determine if the images should be shown in the menus at all. If it is
 319         off (which is the case in e.g. Gnome 2.28 by default), no images will
 320         be shown, consistently with the native behaviour.
 321
 322         @onlyfor{wxmsw,wxosx,wxgtk}
 323     */
 324     virtual void SetBitmap(const wxBitmap& bmp, bool checked = true);
 325
 326     /**
 327         Sets the checked/unchecked bitmaps for the menu item.
 328         The first bitmap is also used as the single bitmap for uncheckable menu items.
 329
 330         @onlyfor{wxmsw}
 331     */
 332     void SetBitmaps(const wxBitmap& checked,
 333                     const wxBitmap& unchecked = wxNullBitmap);
 334
 335     /**
 336         Sets the font associated with the menu item.
 337
 338         @onlyfor{wxmsw}
 339     */
 340     void SetFont(const wxFont& font);
 341
 342     /**
 343         Sets the help string.
 344     */
 345     void SetHelp(const wxString& helpString);
 346
 347     /**
 348         Sets the label associated with the menu item.
 349
 350         Note that if the ID of this menu item corrisponds to a stock ID, then it is
 351         not necessary to specify a label: wxWidgets will automatically use the stock
 352         item label associated with that ID. See the @ref wxMenuItem::wxMenuItem "constructor"
 353         for more info.
 354
 355         The label string for the normal menu items (not separators) may include the
 356         accelerator which can be used to activate the menu item from keyboard.
 357         An accelerator key can be specified using the ampersand <tt>&</tt> character.
 358         In order to embed an ampersand character in the menu item text, the ampersand
 359         must be doubled.
 360
 361         Optionally you can specify also an accelerator string appending a tab character
 362         <tt>\\t</tt> followed by a valid key combination (e.g. <tt>CTRL+V</tt>).
 363         Its general syntax is any combination of @c "CTRL", @c "ALT" and @c "SHIFT" strings
 364         (case doesn't matter) separated by either @c '-' or @c '+' characters and followed
 365         by the accelerator itself.
 366         The accelerator may be any alphanumeric character, any function key
 367         (from F1 to F12) or one of the special characters listed in the table
 368         below (again, case doesn't matter):
 369         - @c DEL or @c DELETE: Delete key
 370         - @c INS or @c INSERT: Insert key
 371         - @c ENTER or @c RETURN: Enter key
 372         - @c PGUP: PageUp key
 373         - @c PGDN: PageDown key
 374         - @c LEFT: Left cursor arrow key
 375         - @c RIGHT: Right cursor arrow key
 376         - @c UP: Up cursor arrow key
 377         - @c DOWN: Down cursor arrow key
 378         - @c HOME: Home key
 379         - @c END: End key
 380         - @c SPACE: Space
 381         - @c TAB: Tab key
 382         - @c ESC or @c ESCAPE: Escape key (Windows only)
 383
 384         Examples:
 385
 386         @code
 387         m_pMyMenuItem->SetItemLabel("My &item\tCTRL+I");
 388         m_pMyMenuItem2->SetItemLabel("Clean && build\tF7");
 389         m_pMyMenuItem3->SetItemLabel("Simple item");
 390         m_pMyMenuItem4->SetItemLabel("Item with &accelerator");
 391         @endcode
 392
 393         @see GetItemLabel(), GetItemLabelText()
 394     */
 395     virtual void SetItemLabel(const wxString& label);
 396
 397     /**
 398         Sets the width of the menu item checkmark bitmap.
 399
 400         @onlyfor{wxmsw}
 401     */
 402     void SetMarginWidth(int width) const;
 403
 404     /**
 405         Sets the parent menu which will contain this menu item.
 406     */
 407     void SetMenu(wxMenu* menu);
 408
 409     /**
 410         Sets the submenu of this menu item.
 411     */
 412     void SetSubMenu(wxMenu* menu);
 413
 414     /**
 415         Sets the text associated with the menu item.
 416
 417         @deprecated This function is deprecated in favour of SetItemLabel().
 418
 419         @see SetItemLabel().
 420     */
 421     virtual void SetText(const wxString& text);
 422
 423     /**
 424         Sets the text colour associated with the menu item.
 425
 426         @onlyfor{wxmsw}
 427     */
 428     void SetTextColour(const wxColour& colour);
 429
 430     //@}
 431 };
 432