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 licence
   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_MENU 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_MENU 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         Some platforms (currently wxGTK only, and see the remark in SetBitmap()
  59         documentation) will also show standard bitmaps for stock menu items.
  60
  61         Leaving at least @a text empty for the stock menu items is actually strongly
  62         recommended as they will have appearance and keyboard interface (including
  63         standard accelerators) familiar to the user.
  64
  65         For the custom (non-stock) menu items, @a text must be specified and while
  66         @a helpString may be left empty, it's recommended to pass the item
  67         description (which is automatically shown by the library in the status bar
  68         when the menu item is selected) in this parameter.
  69
  70         Finally note that you can e.g. use a stock menu label without using its stock
  71         help string:
  72
  73         @code
  74         // use all stock properties:
  75         helpMenu->Append(wxID_ABOUT);
  76
  77         // use the stock label and the stock accelerator but not the stock help string:
  78         helpMenu->Append(wxID_ABOUT, "", "My custom help string");
  79
  80         // use all stock properties except for the bitmap:
  81         wxMenuItem *mymenu = new wxMenuItem(helpMenu, wxID_ABOUT);
  82         mymenu->SetBitmap(wxArtProvider::GetBitmap(wxART_WARNING));
  83         helpMenu->Append(mymenu);
  84         @endcode
  85
  86         that is, stock properties are set independently one from the other.
  87
  88         @param parentMenu
  89             Menu that the menu item belongs to. Can be @NULL if the item is
  90             going to be added to the menu later.
  91         @param id
  92             Identifier for this menu item. May be @c wxID_SEPARATOR, in which
  93             case the given kind is ignored and taken to be @c wxITEM_SEPARATOR
  94             instead.
  95         @param text
  96             Text for the menu item, as shown on the menu.
  97             See SetItemLabel() for more info.
  98         @param helpString
  99             Optional help string that will be shown on the status bar.
 100         @param kind
 101             May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or
 102             @c wxITEM_RADIO.
 103         @param subMenu
 104             If non-@NULL, indicates that the menu item is a submenu.
 105     */
 106     wxMenuItem(wxMenu* parentMenu = NULL, int id = wxID_SEPARATOR,
 107                const wxString& text = wxEmptyString,
 108                const wxString& helpString = wxEmptyString,
 109                wxItemKind kind = wxITEM_NORMAL,
 110                wxMenu* subMenu = NULL);
 111
 112     /**
 113         Destructor.
 114     */
 115     virtual ~wxMenuItem();
 116
 117     /**
 118         Checks or unchecks the menu item.
 119         Note that this only works when the item is already appended to a menu.
 120     */
 121     virtual void Check(bool check = true);
 122
 123     /**
 124         Enables or disables the menu item.
 125     */
 126     virtual void Enable(bool enable = true);
 127
 128     /**
 129         @deprecated This function is deprecated; please use GetLabelText() instead.
 130
 131         @see GetLabelText()
 132     */
 133     static wxString GetLabelFromText(const wxString& text);
 134
 135     /**
 136         Strips all accelerator characters and mnemonics from the given @a text.
 137         For example:
 138
 139         @code
 140           wxMenuItem::GetLabelfromText("&Hello\tCtrl-h");
 141         @endcode
 142
 143         will return just @c "Hello".
 144
 145         @see GetItemLabelText(), GetItemLabel()
 146     */
 147     static wxString GetLabelText(const wxString& text);
 148
 149
 150     /**
 151         @name Getters
 152     */
 153     //@{
 154
 155     /**
 156         Returns the background colour associated with the menu item.
 157
 158         @onlyfor{wxmsw}
 159     */
 160     wxColour& GetBackgroundColour() const;
 161
 162     /**
 163         Returns the checked or unchecked bitmap.
 164
 165         @onlyfor{wxmsw}
 166     */
 167     virtual const wxBitmap& GetBitmap() const;
 168
 169     /**
 170         Returns the font associated with the menu item.
 171
 172         @onlyfor{wxmsw}
 173     */
 174     wxFont& GetFont() const;
 175
 176     /**
 177         Returns the help string associated with the menu item.
 178     */
 179     const wxString& GetHelp() const;
 180
 181     /**
 182         Returns the menu item identifier.
 183     */
 184     int GetId() const;
 185
 186     /**
 187         Returns the text associated with the menu item including any accelerator
 188         characters that were passed to the constructor or SetItemLabel().
 189
 190         @see GetItemLabelText(), GetLabelText()
 191     */
 192     virtual wxString GetItemLabel() const;
 193
 194     /**
 195         Returns the text associated with the menu item, without any accelerator
 196         characters.
 197
 198         @see GetItemLabel(), GetLabelText()
 199     */
 200     virtual wxString GetItemLabelText() const;
 201
 202     /**
 203         Returns the item kind, one of @c wxITEM_SEPARATOR, @c wxITEM_NORMAL,
 204         @c wxITEM_CHECK or @c wxITEM_RADIO.
 205     */
 206     wxItemKind GetKind() const;
 207
 208     /**
 209         Returns the text associated with the menu item without any accelerator
 210         characters it might contain.
 211
 212         @deprecated This function is deprecated in favour of GetItemLabelText().
 213
 214         @see GetItemLabelText()
 215     */
 216     wxString GetLabel() const;
 217
 218     /**
 219         Gets the width of the menu item checkmark bitmap.
 220
 221         @onlyfor{wxmsw}
 222     */
 223     int GetMarginWidth() const;
 224
 225     /**
 226         Returns the menu this menu item is in, or @NULL if this menu item is not
 227         attached.
 228     */
 229     wxMenu* GetMenu() const;
 230
 231     /**
 232         Returns the text associated with the menu item.
 233
 234         @deprecated This function is deprecated. Please use GetItemLabel() or GetItemLabelText() instead.
 235
 236         @see GetItemLabel(), GetItemLabelText()
 237     */
 238     wxString GetName() const;
 239
 240     /**
 241         Returns the submenu associated with the menu item, or @NULL if there isn't one.
 242     */
 243     wxMenu* GetSubMenu() const;
 244
 245     /**
 246         Returns the text associated with the menu item, such as it was passed to the
 247         wxMenuItem constructor, i.e. with any accelerator characters it may contain.
 248
 249         @deprecated This function is deprecated in favour of GetItemLabel().
 250
 251         @see GetLabelFromText()
 252     */
 253     const wxString& GetText() const;
 254
 255     /**
 256         Returns the text colour associated with the menu item.
 257
 258         @onlyfor{wxmsw}
 259     */
 260     wxColour& GetTextColour() const;
 261
 262     //@}
 263
 264
 265
 266     /**
 267         @name Checkers
 268     */
 269     //@{
 270
 271     /**
 272         Returns @true if the item is a check item.
 273
 274         Unlike IsCheckable() this doesn't return @true for the radio buttons.
 275
 276         @since 2.9.5
 277      */
 278     bool IsCheck() const;
 279
 280     /**
 281         Returns @true if the item is checkable.
 282
 283         Notice that the radio buttons are considered to be checkable as well,
 284         so this method returns @true for them too. Use IsCheck() if you want to
 285         test for the check items only.
 286     */
 287     bool IsCheckable() const;
 288
 289     /**
 290         Returns @true if the item is checked.
 291     */
 292     virtual bool IsChecked() const;
 293
 294     /**
 295         Returns @true if the item is enabled.
 296     */
 297     virtual bool IsEnabled() const;
 298
 299     /**
 300         Returns @true if the item is a radio button.
 301
 302         @since 2.9.5
 303      */
 304     bool IsRadio() const;
 305
 306     /**
 307         Returns @true if the item is a separator.
 308     */
 309     bool IsSeparator() const;
 310
 311     /**
 312         Returns @true if the item is a submenu.
 313     */
 314     bool IsSubMenu() const;
 315
 316     //@}
 317
 318
 319
 320     /**
 321         @name Setters
 322     */
 323     //@{
 324
 325     /**
 326         Sets the background colour associated with the menu item.
 327
 328         @onlyfor{wxmsw}
 329     */
 330     void SetBackgroundColour(const wxColour& colour);
 331
 332     /**
 333         Sets the bitmap for the menu item.
 334
 335         It is equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap) if
 336         @a checked is @true (default value) or SetBitmaps(wxNullBitmap, bmp)
 337         otherwise.
 338
 339         SetBitmap() must be called before the item is appended to the menu,
 340         i.e. appending the item without a bitmap and setting one later is not
 341         guaranteed to work. But the bitmap can be changed or reset later if it
 342         had been set up initially.
 343
 344         Notice that GTK+ uses a global setting called @c gtk-menu-images to
 345         determine if the images should be shown in the menus at all. If it is
 346         off (which is the case in e.g. Gnome 2.28 by default), no images will
 347         be shown, consistently with the native behaviour.
 348
 349         @onlyfor{wxmsw,wxosx,wxgtk}
 350     */
 351     virtual void SetBitmap(const wxBitmap& bmp, bool checked = true);
 352
 353     /**
 354         Sets the checked/unchecked bitmaps for the menu item.
 355         The first bitmap is also used as the single bitmap for uncheckable menu items.
 356
 357         @onlyfor{wxmsw}
 358     */
 359     void SetBitmaps(const wxBitmap& checked,
 360                     const wxBitmap& unchecked = wxNullBitmap);
 361
 362     /**
 363         Sets the font associated with the menu item.
 364
 365         @onlyfor{wxmsw}
 366     */
 367     void SetFont(const wxFont& font);
 368
 369     /**
 370         Sets the help string.
 371     */
 372     void SetHelp(const wxString& helpString);
 373
 374     /**
 375         Sets the label associated with the menu item.
 376
 377         Note that if the ID of this menu item corresponds to a stock ID, then it is
 378         not necessary to specify a label: wxWidgets will automatically use the stock
 379         item label associated with that ID. See the @ref wxMenuItem::wxMenuItem "constructor"
 380         for more info.
 381
 382         The label string for the normal menu items (not separators) may include the
 383         accelerator which can be used to activate the menu item from keyboard.
 384         An accelerator key can be specified using the ampersand <tt>&</tt> character.
 385         In order to embed an ampersand character in the menu item text, the ampersand
 386         must be doubled.
 387
 388         Optionally you can specify also an accelerator string appending a tab character
 389         <tt>\\t</tt> followed by a valid key combination (e.g. <tt>CTRL+V</tt>).
 390         Its general syntax is any combination of @c "CTRL", @c "RAWCTRL",  @c
 391         "ALT" and @c "SHIFT" strings (case doesn't matter) separated by either
 392         @c '-' or @c '+' characters and followed by the accelerator itself.
 393         Notice that @c CTRL corresponds to the "Ctrl" key on most platforms but
 394         not under Mac OS where it is mapped to "Cmd" key on Mac keyboard.
 395         Usually this is exactly what you want in portable code but if you
 396         really need to use the (rarely used for this purpose) "Ctrl" key even
 397         under Mac, you may use @c RAWCTRL to prevent this mapping. Under the
 398         other platforms @c RAWCTRL is the same as plain @c CTRL.
 399
 400         The accelerator may be any alphanumeric character, any function key
 401         (from F1 to F12) or one of the special characters listed in the table
 402         below (again, case doesn't matter):
 403         - @c DEL or @c DELETE: Delete key
 404         - @c BACK : Backspace key
 405         - @c INS or @c INSERT: Insert key
 406         - @c ENTER or @c RETURN: Enter key
 407         - @c PGUP: PageUp key
 408         - @c PGDN: PageDown key
 409         - @c LEFT: Left cursor arrow key
 410         - @c RIGHT: Right cursor arrow key
 411         - @c UP: Up cursor arrow key
 412         - @c DOWN: Down cursor arrow key
 413         - @c HOME: Home key
 414         - @c END: End key
 415         - @c SPACE: Space
 416         - @c TAB: Tab key
 417         - @c ESC or @c ESCAPE: Escape key (Windows only)
 418
 419         Examples:
 420
 421         @code
 422         m_pMyMenuItem->SetItemLabel("My &item\tCTRL+I");
 423         m_pMyMenuItem2->SetItemLabel("Clean && build\tF7");
 424         m_pMyMenuItem3->SetItemLabel("Simple item");
 425         m_pMyMenuItem4->SetItemLabel("Item with &accelerator");
 426         @endcode
 427
 428         @note In wxGTK using @c "SHIFT" with non-alphabetic characters
 429         currently doesn't work, even in combination with other modifiers, due
 430         to GTK+ limitation. E.g. @c Shift+Ctrl+A works but @c Shift+Ctrl+1 or
 431         @c Shift+/ do not, so avoid using accelerators of this form in portable
 432         code.
 433
 434         @see GetItemLabel(), GetItemLabelText()
 435     */
 436     virtual void SetItemLabel(const wxString& label);
 437
 438     /**
 439         Sets the width of the menu item checkmark bitmap.
 440
 441         @onlyfor{wxmsw}
 442     */
 443     void SetMarginWidth(int width);
 444
 445     /**
 446         Sets the parent menu which will contain this menu item.
 447     */
 448     void SetMenu(wxMenu* menu);
 449
 450     /**
 451         Sets the submenu of this menu item.
 452     */
 453     void SetSubMenu(wxMenu* menu);
 454
 455     /**
 456         Sets the text associated with the menu item.
 457
 458         @deprecated This function is deprecated in favour of SetItemLabel().
 459
 460         @see SetItemLabel().
 461     */
 462     virtual void SetText(const wxString& text);
 463
 464     /**
 465         Sets the text colour associated with the menu item.
 466
 467         @onlyfor{wxmsw}
 468     */
 469     void SetTextColour(const wxColour& colour);
 470
 471     //@}
 472 };
 473