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 page_stockitems "Stock Items" for the full list) it is enough
  33         to specify just the stock ID and leave @a text and @a helpString empty. In
  34         fact, leaving at least @a text empty for the stock menu items is strongly
  35         recommended as they will have appearance and keyboard interface (including
  36         standard accelerators) familiar to the user.
  37         For the custom (non-stock) menu items, @a text must be specified and while
  38         @a helpString may be left empty, it's recommended to pass the item
  39         description (which is automatically shown by the library in the status bar when
  40         the menu item is selected) in this parameter.
  41         Finally note that you can e.g. use a stock menu label without using its stock
  42         help string; that is, stock properties are set independently one from the other.
  43
  44         @param parentMenu
  45             Menu that the menu item belongs to. Can be @NULL if the item is
  46             going to be added to the menu later.
  47         @param id
  48             Identifier for this menu item. May be @c wxID_SEPARATOR, in which
  49             case the given kind is ignored and taken to be @c wxITEM_SEPARATOR
  50             instead.
  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 @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or @c
  59             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         @deprecated This function is deprecated in favour of GetItemLabelText().
 136         @see GetText(), GetLabelFromText()
 137     */
 138     wxString GetLabel() const;
 139
 140     /**
 141         @deprecated This function is deprecated; please use GetLabelText() instead.
 142         @see GetText(), GetLabel()
 143     */
 144     static wxString GetLabelFromText(const wxString& text);
 145
 146     /**
 147         Strips all accelerator characters and mnemonics from the given @e text.
 148         For example:
 149
 150         @code
 151           wxMenuItem::GetLabelfromText( "&Hello\tCtrl-h");
 152         @endcode
 153
 154         will return just @c "Hello".
 155
 156         @see GetItemLabelText(), GetItemLabel()
 157     */
 158     static wxString GetLabelText(const wxString& text);
 159
 160     /**
 161         Gets the width of the menu item checkmark bitmap (Windows only).
 162     */
 163     int GetMarginWidth() const;
 164
 165     /**
 166         Returns the menu this menu item is in, or @NULL if this menu item is not
 167         attached.
 168     */
 169     wxMenu* GetMenu() const;
 170
 171     /**
 172         Returns the text associated with the menu item.
 173         @deprecated This function is deprecated. Please use
 174         GetItemLabel() or GetItemLabelText() instead.
 175     */
 176     wxString GetName() const;
 177
 178     /**
 179         Returns the submenu associated with the menu item, or @NULL if there isn't one.
 180     */
 181     wxMenu* GetSubMenu() const;
 182
 183     /**
 184         Returns the text associated with the menu item, such as it was passed to the
 185         wxMenuItem constructor, i.e. with any accelerator characters it may contain.
 186         @deprecated This function is deprecated in favour of GetItemLabel().
 187         @see GetLabel(), GetLabelFromText()
 188     */
 189     wxString GetText() const;
 190
 191     /**
 192         Returns the text colour associated with the menu item (Windows only).
 193     */
 194     wxColour GetTextColour() const;
 195
 196     /**
 197         Returns @true if the item is checkable.
 198     */
 199     bool IsCheckable() const;
 200
 201     /**
 202         Returns @true if the item is checked.
 203     */
 204     bool IsChecked() const;
 205
 206     /**
 207         Returns @true if the item is enabled.
 208     */
 209     bool IsEnabled() const;
 210
 211     /**
 212         Returns @true if the item is a separator.
 213     */
 214     bool IsSeparator() const;
 215
 216     /**
 217         Returns @true if the item is a submenu.
 218     */
 219     bool IsSubMenu() const;
 220
 221     /**
 222         Sets the background colour associated with the menu item (Windows only).
 223     */
 224     void SetBackgroundColour(const wxColour& colour) const;
 225
 226     /**
 227         Sets the bitmap for the menu item (Windows and GTK+ only). It is
 228         equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap).
 229     */
 230     void SetBitmap(const wxBitmap& bmp);
 231
 232     /**
 233         Sets the checked/unchecked bitmaps for the menu item (Windows only). The first
 234         bitmap
 235         is also used as the single bitmap for uncheckable menu items.
 236     */
 237     void SetBitmaps(const wxBitmap& checked,
 238                     const wxBitmap& unchecked = wxNullBitmap);
 239
 240     /**
 241         Sets the font associated with the menu item (Windows only).
 242     */
 243     void SetFont(const wxFont& font);
 244
 245     /**
 246         Sets the help string.
 247     */
 248     void SetHelp(const wxString& helpString);
 249
 250     /**
 251         Sets the label associated with the menu item.
 252     */
 253     void SetItemLabel(const wxString& label);
 254
 255     /**
 256         Sets the width of the menu item checkmark bitmap (Windows only).
 257     */
 258     void SetMarginWidth(int width) const;
 259
 260     /**
 261         Sets the parent menu which will contain this menu item.
 262     */
 263     void SetMenu(const wxMenu* menu);
 264
 265     /**
 266         Sets the submenu of this menu item.
 267     */
 268     void SetSubMenu(const wxMenu* menu);
 269
 270     /**
 271         Sets the text associated with the menu item.
 272         @deprecated This function is deprecated in favour of SetItemLabel().
 273     */
 274     void SetText(const wxString& text);
 275
 276     /**
 277         Sets the text colour associated with the menu item (Windows only).
 278     */
 279     void SetTextColour(const wxColour& colour);
 280 };
 281