2008-03-08 08:52:38 -05:00
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
// Name: menuitem.h
|
2008-10-11 09:10:48 -04:00
|
|
|
// Purpose: interface of wxMenu, wxMenuItem
|
2008-03-08 08:52:38 -05:00
|
|
|
// Author: wxWidgets team
|
|
|
|
// RCS-ID: $Id$
|
|
|
|
// Licence: wxWindows license
|
|
|
|
/////////////////////////////////////////////////////////////////////////////
|
|
|
|
|
|
|
|
/**
|
|
|
|
@class wxMenuItem
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-10-11 09:10:48 -04:00
|
|
|
A menu item represents an item in a menu.
|
|
|
|
|
|
|
|
Note that you usually don't have to deal with it directly as wxMenu methods
|
|
|
|
usually construct an object of this class for you.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
Also please note that the methods related to fonts and bitmaps are currently
|
|
|
|
only implemented for Windows and GTK+.
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
@library{wxcore}
|
|
|
|
@category{menus}
|
2008-03-08 09:43:31 -05:00
|
|
|
|
2008-03-10 11:24:38 -04:00
|
|
|
@see wxMenuBar, wxMenu
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
class wxMenuItem : public wxObject
|
|
|
|
{
|
|
|
|
public:
|
|
|
|
/**
|
|
|
|
Constructs a wxMenuItem object.
|
2008-10-11 09:10:48 -04:00
|
|
|
|
|
|
|
Menu items can be standard, or "stock menu items", or custom.
|
|
|
|
For the standard menu items (such as commands to open a file, exit the
|
|
|
|
program and so on, see @ref page_stockitems for the full list) it is enough
|
|
|
|
to specify just the stock ID and leave @a text and @a helpString empty.
|
|
|
|
|
|
|
|
In fact, leaving at least @a text empty for the stock menu items is strongly
|
2008-03-08 08:52:38 -05:00
|
|
|
recommended as they will have appearance and keyboard interface (including
|
|
|
|
standard accelerators) familiar to the user.
|
2008-10-11 09:10:48 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
For the custom (non-stock) menu items, @a text must be specified and while
|
|
|
|
@a helpString may be left empty, it's recommended to pass the item
|
2008-10-11 09:10:48 -04:00
|
|
|
description (which is automatically shown by the library in the status bar
|
|
|
|
when the menu item is selected) in this parameter.
|
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
Finally note that you can e.g. use a stock menu label without using its stock
|
2008-10-11 09:10:48 -04:00
|
|
|
help string:
|
|
|
|
|
|
|
|
@code
|
|
|
|
// use all stock properties:
|
|
|
|
helpMenu->Append(wxID_ABOUT);
|
|
|
|
|
|
|
|
// use the stock label and the stock accelerator but not the stock help string:
|
|
|
|
helpMenu->Append(wxID_ABOUT, wxEmptyString, wxT("My custom help string"));
|
|
|
|
|
|
|
|
// use all stock properties except for the bitmap:
|
|
|
|
wxMenuItem *mymenu = new wxMenuItem(helpMenu, wxID_ABOUT);
|
|
|
|
mymenu->SetBitmap(wxArtProvider::GetBitmap(wxART_WARNING));
|
|
|
|
helpMenu->Append(mymenu);
|
|
|
|
@endcode
|
|
|
|
|
|
|
|
that is, stock properties are set independently one from the other.
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 09:43:31 -05:00
|
|
|
@param parentMenu
|
2008-06-22 10:47:40 -04:00
|
|
|
Menu that the menu item belongs to. Can be @NULL if the item is
|
|
|
|
going to be added to the menu later.
|
2008-03-08 09:43:31 -05:00
|
|
|
@param id
|
2008-06-22 10:47:40 -04:00
|
|
|
Identifier for this menu item. May be @c wxID_SEPARATOR, in which
|
|
|
|
case the given kind is ignored and taken to be @c wxITEM_SEPARATOR
|
|
|
|
instead.
|
2008-03-08 09:43:31 -05:00
|
|
|
@param text
|
2008-10-11 09:10:48 -04:00
|
|
|
Text for the menu item, as shown on the menu. An accelerator key can
|
|
|
|
be specified using the ampersand " character. In order to embed an
|
2008-03-09 08:33:59 -04:00
|
|
|
ampersand character in the menu item text, the ampersand must be doubled.
|
2008-03-08 09:43:31 -05:00
|
|
|
@param helpString
|
2008-03-09 08:33:59 -04:00
|
|
|
Optional help string that will be shown on the status bar.
|
2008-03-08 09:43:31 -05:00
|
|
|
@param kind
|
2008-10-11 09:10:48 -04:00
|
|
|
May be @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, @c wxITEM_CHECK or
|
|
|
|
@c wxITEM_RADIO
|
2008-03-08 09:43:31 -05:00
|
|
|
@param subMenu
|
2008-03-09 08:33:59 -04:00
|
|
|
If non-@NULL, indicates that the menu item is a submenu.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-03-09 08:33:59 -04:00
|
|
|
wxMenuItem(wxMenu* parentMenu = NULL, int id = wxID_SEPARATOR,
|
2008-03-08 08:52:38 -05:00
|
|
|
const wxString& text = "",
|
|
|
|
const wxString& helpString = "",
|
|
|
|
wxItemKind kind = wxITEM_NORMAL,
|
2008-03-09 08:33:59 -04:00
|
|
|
wxMenu* subMenu = NULL);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Destructor.
|
|
|
|
*/
|
2008-09-27 07:21:10 -04:00
|
|
|
virtual ~wxMenuItem();
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Checks or unchecks the menu item.
|
|
|
|
Note that this only works when the item is already appended to a menu.
|
|
|
|
*/
|
2008-09-27 07:21:10 -04:00
|
|
|
virtual void Check(bool check = true);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Enables or disables the menu item.
|
|
|
|
*/
|
2008-09-27 07:21:10 -04:00
|
|
|
virtual void Enable(bool enable = true);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the background colour associated with the menu item (Windows only).
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
wxColour GetBackgroundColour() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the checked or unchecked bitmap (Windows only).
|
|
|
|
*/
|
2008-10-28 11:36:26 -04:00
|
|
|
virtual const wxBitmap& GetBitmap() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the font associated with the menu item (Windows only).
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
wxFont GetFont() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the help string associated with the menu item.
|
|
|
|
*/
|
2008-10-28 11:36:26 -04:00
|
|
|
const wxString& GetHelp() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the menu item identifier.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
int GetId() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the text associated with the menu item including any accelerator
|
2008-10-11 09:10:48 -04:00
|
|
|
characters that were passed to the constructor or SetItemLabel().
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
@see GetItemLabelText(), GetLabelText()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-27 07:21:10 -04:00
|
|
|
virtual wxString GetItemLabel() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the text associated with the menu item, without any accelerator
|
|
|
|
characters.
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
@see GetItemLabel(), GetLabelText()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-27 07:21:10 -04:00
|
|
|
virtual wxString GetItemLabelText() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-03-08 09:43:31 -05:00
|
|
|
Returns the item kind, one of @c wxITEM_SEPARATOR, @c wxITEM_NORMAL,
|
2008-03-08 08:52:38 -05:00
|
|
|
@c wxITEM_CHECK or @c wxITEM_RADIO.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
wxItemKind GetKind() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the text associated with the menu item without any accelerator
|
|
|
|
characters it might contain.
|
2008-10-11 09:10:48 -04:00
|
|
|
|
2008-06-12 20:05:15 -04:00
|
|
|
@deprecated This function is deprecated in favour of GetItemLabelText().
|
2008-10-11 09:10:48 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
@see GetText(), GetLabelFromText()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
wxString GetLabel() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-06-12 20:05:15 -04:00
|
|
|
@deprecated This function is deprecated; please use GetLabelText() instead.
|
2008-10-11 09:10:48 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
@see GetText(), GetLabel()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
static wxString GetLabelFromText(const wxString& text);
|
|
|
|
|
|
|
|
/**
|
2008-10-11 09:10:48 -04:00
|
|
|
Strips all accelerator characters and mnemonics from the given @a text.
|
2008-06-02 16:45:41 -04:00
|
|
|
For example:
|
|
|
|
|
|
|
|
@code
|
2008-10-11 09:10:48 -04:00
|
|
|
wxMenuItem::GetLabelfromText("&Hello\tCtrl-h");
|
2008-06-02 16:45:41 -04:00
|
|
|
@endcode
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-08 08:52:38 -05:00
|
|
|
will return just @c "Hello".
|
2008-03-20 09:45:17 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
@see GetItemLabelText(), GetItemLabel()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
static wxString GetLabelText(const wxString& text);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Gets the width of the menu item checkmark bitmap (Windows only).
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
int GetMarginWidth() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the menu this menu item is in, or @NULL if this menu item is not
|
|
|
|
attached.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
wxMenu* GetMenu() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the text associated with the menu item.
|
2008-10-11 09:10:48 -04:00
|
|
|
|
2008-06-12 20:05:15 -04:00
|
|
|
@deprecated This function is deprecated. Please use
|
2008-10-11 09:10:48 -04:00
|
|
|
|
2008-06-12 20:05:15 -04:00
|
|
|
GetItemLabel() or GetItemLabelText() instead.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
wxString GetName() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the submenu associated with the menu item, or @NULL if there isn't one.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
wxMenu* GetSubMenu() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the text associated with the menu item, such as it was passed to the
|
|
|
|
wxMenuItem constructor, i.e. with any accelerator characters it may contain.
|
2008-10-11 09:10:48 -04:00
|
|
|
|
2008-06-12 20:05:15 -04:00
|
|
|
@deprecated This function is deprecated in favour of GetItemLabel().
|
2008-10-11 09:10:48 -04:00
|
|
|
|
2008-03-09 08:33:59 -04:00
|
|
|
@see GetLabel(), GetLabelFromText()
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-10-28 11:36:26 -04:00
|
|
|
const wxString& GetText() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns the text colour associated with the menu item (Windows only).
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
wxColour GetTextColour() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns @true if the item is checkable.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
bool IsCheckable() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns @true if the item is checked.
|
|
|
|
*/
|
2008-09-27 07:21:10 -04:00
|
|
|
virtual bool IsChecked() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns @true if the item is enabled.
|
|
|
|
*/
|
2008-09-27 07:21:10 -04:00
|
|
|
virtual bool IsEnabled() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns @true if the item is a separator.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
bool IsSeparator() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Returns @true if the item is a submenu.
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
bool IsSubMenu() const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Sets the background colour associated with the menu item (Windows only).
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
void SetBackgroundColour(const wxColour& colour) const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-10-11 09:10:48 -04:00
|
|
|
Sets the bitmap for the menu item (Windows and GTK+ only).
|
|
|
|
It is equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap).
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-27 07:21:10 -04:00
|
|
|
virtual void SetBitmap(const wxBitmap& bmp);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
2008-10-11 09:10:48 -04:00
|
|
|
Sets the checked/unchecked bitmaps for the menu item (Windows only).
|
|
|
|
The first bitmap is also used as the single bitmap for uncheckable menu items.
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
|
|
|
void SetBitmaps(const wxBitmap& checked,
|
|
|
|
const wxBitmap& unchecked = wxNullBitmap);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Sets the font associated with the menu item (Windows only).
|
|
|
|
*/
|
|
|
|
void SetFont(const wxFont& font);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Sets the help string.
|
|
|
|
*/
|
|
|
|
void SetHelp(const wxString& helpString);
|
|
|
|
|
|
|
|
/**
|
|
|
|
Sets the label associated with the menu item.
|
|
|
|
*/
|
2008-09-27 07:21:10 -04:00
|
|
|
virtual void SetItemLabel(const wxString& label);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Sets the width of the menu item checkmark bitmap (Windows only).
|
|
|
|
*/
|
2008-03-09 12:24:26 -04:00
|
|
|
void SetMarginWidth(int width) const;
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Sets the parent menu which will contain this menu item.
|
|
|
|
*/
|
2008-10-28 11:36:26 -04:00
|
|
|
void SetMenu(wxMenu* menu);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Sets the submenu of this menu item.
|
|
|
|
*/
|
2008-10-28 11:36:26 -04:00
|
|
|
void SetSubMenu(wxMenu* menu);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Sets the text associated with the menu item.
|
2008-10-11 09:10:48 -04:00
|
|
|
|
2008-06-12 20:05:15 -04:00
|
|
|
@deprecated This function is deprecated in favour of SetItemLabel().
|
2008-03-08 08:52:38 -05:00
|
|
|
*/
|
2008-09-27 07:21:10 -04:00
|
|
|
virtual void SetText(const wxString& text);
|
2008-03-08 08:52:38 -05:00
|
|
|
|
|
|
|
/**
|
|
|
|
Sets the text colour associated with the menu item (Windows only).
|
|
|
|
*/
|
|
|
|
void SetTextColour(const wxColour& colour);
|
|
|
|
};
|
2008-03-10 11:24:38 -04:00
|
|
|
|