interface/wx/menuitem.h

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