[wxWidgets.git] / interface / menuitem.h

/////////////////////////////////////////////////////////////////////////////
// Name:        menuitem.h
// Purpose:     documentation for wxMenuItem class
// Author:      wxWidgets team
// RCS-ID:      $Id$
// Licence:     wxWindows license
/////////////////////////////////////////////////////////////////////////////

/**
    @class wxMenuItem
    @wxheader{menuitem.h}
    
    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.
    
    Also please note that the methods related to fonts and bitmaps are currently
    only implemented for Windows and GTK+.
    
    @library{wxcore}
    @category{menus}
    
    @seealso
    wxMenuBar, wxMenu
*/
class wxMenuItem : public wxObject
{
public:
    /**
        Constructs a wxMenuItem object.
        
        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 overview_stockitems "stock items" for the full list) it is enough
        to
        specify just the stock ID and leave @e text and @e helpString empty. In
        fact, leaving at least @e text empty for the stock menu items is strongly
        recommended as they will have appearance and keyboard interface (including
        standard accelerators) familiar to the user.
        
        For the custom (non-stock) menu items, @e text must be specified and while 
        @e helpString may be left empty, it's recommended to pass the item
        description (which is automatically shown by the library in the status bar when
        the menu item is selected) in this parameter.
        
        Finally note that you can e.g. use a stock menu label without using its stock
        help string:
        that is, stock properties are set independently one from the other.
        
        @param parentMenu 
        Menu that the menu item belongs to.
        
        @param id 
        Identifier for this menu item, or wxID_SEPARATOR to indicate a separator.
        
        @param text 
        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
        ampersand character in the menu item text, the ampersand must be doubled.
        
        @param helpString 
        Optional help string that will be shown on the status bar.
        
        @param kind 
        May be wxITEM_SEPARATOR, wxITEM_NORMAL, 
        wxITEM_CHECK or wxITEM_RADIO
        
        @param subMenu 
        If non-@NULL, indicates that the menu item is a submenu.
    */
    wxMenuItem(wxMenu* parentMenu = @NULL, int id = wxID_SEPARATOR,
               const wxString& text = "",
               const wxString& helpString = "",
               wxItemKind kind = wxITEM_NORMAL,
               wxMenu* subMenu = @NULL);

    /**
        Destructor.
    */
    ~wxMenuItem();

    /**
        Checks or unchecks the menu item.
        
        Note that this only works when the item is already appended to a menu.
    */
    void Check(bool check = @true);

    /**
        Enables or disables the menu item.
    */
    void Enable(bool enable = @true);

    /**
        Returns the background colour associated with the menu item (Windows only).
    */
    wxColour GetBackgroundColour();

    /**
        Returns the checked or unchecked bitmap (Windows only).
    */
    wxBitmap GetBitmap(bool checked = @true);

    /**
        Returns the font associated with the menu item (Windows only).
    */
    wxFont GetFont();

    /**
        Returns the help string associated with the menu item.
    */
    wxString GetHelp();

    /**
        Returns the menu item identifier.
    */
    int GetId();

    /**
        Returns the text associated with the menu item including any accelerator
        characters that were passed to the constructor or SetItemLabel.
        
        @sa GetItemLabelText(), GetLabelText()
    */
    wxString GetItemLabel();

    /**
        Returns the text associated with the menu item, without any accelerator
        characters.
        
        @sa GetItemLabel(), GetLabelText()
    */
    wxString GetItemLabelText();

    /**
        Returns the item kind, one of @c wxITEM_SEPARATOR, @c wxITEM_NORMAL, 
        @c wxITEM_CHECK or @c wxITEM_RADIO.
    */
    wxItemKind GetKind();

    /**
        Returns the text associated with the menu item without any accelerator
        characters it might contain.
        
        This function is deprecated in favour of GetItemLabelText().
        
        @sa GetText(), GetLabelFromText()
    */
    wxString GetLabel();

    /**
        Strips all accelerator characters and mnemonics from the given @e text.
        For example,
        will return just @c "Hello".
        
        This function is deprecated; please use GetLabelText() instead.
        
        @sa GetText(), GetLabel()
    */
    static wxString GetLabelFromText(const wxString& text);

    /**
        Strips all accelerator characters and mnemonics from the given @e text.
        For example,
        will return just @c "Hello".
        
        @sa GetItemLabelText(), GetItemLabel()
    */
    static wxString GetLabelText(const wxString& text);

    /**
        Gets the width of the menu item checkmark bitmap (Windows only).
    */
    int GetMarginWidth();

    /**
        Returns the menu this menu item is in, or @NULL if this menu item is not
        attached.
    */
    wxMenu* GetMenu();

    /**
        Returns the text associated with the menu item.
        
        @b NB: this function is deprecated, please use 
        GetItemLabel() or GetItemLabelText() 
        instead.
    */
    wxString GetName();

    /**
        Returns the submenu associated with the menu item, or @NULL if there isn't one.
    */
    wxMenu* GetSubMenu();

    /**
        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.
        
        This function is deprecated in favour of GetItemLabel().
        
        @sa GetLabel(), GetLabelFromText()
    */
    wxString GetText();

    /**
        Returns the text colour associated with the menu item (Windows only).
    */
    wxColour GetTextColour();

    /**
        Returns @true if the item is checkable.
    */
    bool IsCheckable();

    /**
        Returns @true if the item is checked.
    */
    bool IsChecked();

    /**
        Returns @true if the item is enabled.
    */
    bool IsEnabled();

    /**
        Returns @true if the item is a separator.
    */
    bool IsSeparator();

    /**
        Returns @true if the item is a submenu.
    */
    bool IsSubMenu();

    /**
        Sets the background colour associated with the menu item (Windows only).
    */
    void SetBackgroundColour(const wxColour& colour);

    /**
        Sets the bitmap for the menu item (Windows and GTK+ only). It is
        equivalent to wxMenuItem::SetBitmaps(bmp, wxNullBitmap).
    */
    void SetBitmap(const wxBitmap& bmp);

    /**
        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.
    */
    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.
    */
    void SetItemLabel(const wxString& label);

    /**
        Sets the width of the menu item checkmark bitmap (Windows only).
    */
    void SetMarginWidth(int width);

    /**
        Sets the parent menu which will contain this menu item.
    */
    void SetMenu(const wxMenu* menu);

    /**
        Sets the submenu of this menu item.
    */
    void SetSubMenu(const wxMenu* menu);

    /**
        Sets the text associated with the menu item.
        
        This function is deprecated in favour of SetItemLabel().
    */
    void SetText(const wxString& text);

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