interface/menuitem.h

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