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