1 ///////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxMenu and wxMenuBar classes
4 // Author: Vadim Zeitlin
8 // Copyright: (c) wxWidgets team
9 // Licence: wxWindows licence
10 ///////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_MENU_H_BASE_
13 #define _WX_MENU_H_BASE_
19 // ----------------------------------------------------------------------------
21 // ----------------------------------------------------------------------------
23 #include "wx/list.h" // for "template" list classes
24 #include "wx/window.h" // base class for wxMenuBar
26 // also include this one to ensure compatibility with old code which only
28 #include "wx/menuitem.h"
30 class WXDLLIMPEXP_FWD_CORE wxMenu
;
31 class WXDLLIMPEXP_FWD_CORE wxMenuBarBase
;
32 class WXDLLIMPEXP_FWD_CORE wxMenuBar
;
33 class WXDLLIMPEXP_FWD_CORE wxMenuItem
;
35 // pseudo template list classes
36 WX_DECLARE_EXPORTED_LIST(wxMenu
, wxMenuList
);
37 WX_DECLARE_EXPORTED_LIST(wxMenuItem
, wxMenuItemList
);
39 // ----------------------------------------------------------------------------
41 // ----------------------------------------------------------------------------
43 class WXDLLIMPEXP_CORE wxMenuBase
: public wxEvtHandler
47 static wxMenu
*New(const wxString
& title
= wxEmptyString
, long style
= 0);
50 wxMenuBase(const wxString
& title
, long style
= 0) : m_title(title
)
52 wxMenuBase(long style
= 0)
55 // dtor deletes all the menu items we own
56 virtual ~wxMenuBase();
61 // append any kind of item (normal/check/radio/separator)
62 wxMenuItem
* Append(int itemid
,
63 const wxString
& text
= wxEmptyString
,
64 const wxString
& help
= wxEmptyString
,
65 wxItemKind kind
= wxITEM_NORMAL
)
67 return DoAppend(wxMenuItem::New((wxMenu
*)this, itemid
, text
, help
, kind
));
70 // append a separator to the menu
71 wxMenuItem
* AppendSeparator() { return Append(wxID_SEPARATOR
); }
73 // append a check item
74 wxMenuItem
* AppendCheckItem(int itemid
,
76 const wxString
& help
= wxEmptyString
)
78 return Append(itemid
, text
, help
, wxITEM_CHECK
);
81 // append a radio item
82 wxMenuItem
* AppendRadioItem(int itemid
,
84 const wxString
& help
= wxEmptyString
)
86 return Append(itemid
, text
, help
, wxITEM_RADIO
);
90 wxMenuItem
* AppendSubMenu(wxMenu
*submenu
,
92 const wxString
& help
= wxEmptyString
)
94 return DoAppend(wxMenuItem::New((wxMenu
*)this, wxID_ANY
, text
, help
,
95 wxITEM_NORMAL
, submenu
));
98 // the most generic form of Append() - append anything
99 wxMenuItem
* Append(wxMenuItem
*item
) { return DoAppend(item
); }
101 // insert a break in the menu (only works when appending the items, not
103 virtual void Break() { }
105 // insert an item before given position
106 wxMenuItem
* Insert(size_t pos
, wxMenuItem
*item
);
108 // insert an item before given position
109 wxMenuItem
* Insert(size_t pos
,
111 const wxString
& text
= wxEmptyString
,
112 const wxString
& help
= wxEmptyString
,
113 wxItemKind kind
= wxITEM_NORMAL
)
115 return Insert(pos
, wxMenuItem::New((wxMenu
*)this, itemid
, text
, help
, kind
));
118 // insert a separator
119 wxMenuItem
* InsertSeparator(size_t pos
)
121 return Insert(pos
, wxMenuItem::New((wxMenu
*)this, wxID_SEPARATOR
));
124 // insert a check item
125 wxMenuItem
* InsertCheckItem(size_t pos
,
127 const wxString
& text
,
128 const wxString
& help
= wxEmptyString
)
130 return Insert(pos
, itemid
, text
, help
, wxITEM_CHECK
);
133 // insert a radio item
134 wxMenuItem
* InsertRadioItem(size_t pos
,
136 const wxString
& text
,
137 const wxString
& help
= wxEmptyString
)
139 return Insert(pos
, itemid
, text
, help
, wxITEM_RADIO
);
143 wxMenuItem
* Insert(size_t pos
,
145 const wxString
& text
,
147 const wxString
& help
= wxEmptyString
)
149 return Insert(pos
, wxMenuItem::New((wxMenu
*)this, itemid
, text
, help
,
150 wxITEM_NORMAL
, submenu
));
153 // prepend an item to the menu
154 wxMenuItem
* Prepend(wxMenuItem
*item
)
156 return Insert(0u, item
);
159 // prepend any item to the menu
160 wxMenuItem
* Prepend(int itemid
,
161 const wxString
& text
= wxEmptyString
,
162 const wxString
& help
= wxEmptyString
,
163 wxItemKind kind
= wxITEM_NORMAL
)
165 return Insert(0u, itemid
, text
, help
, kind
);
168 // prepend a separator
169 wxMenuItem
* PrependSeparator()
171 return InsertSeparator(0u);
174 // prepend a check item
175 wxMenuItem
* PrependCheckItem(int itemid
,
176 const wxString
& text
,
177 const wxString
& help
= wxEmptyString
)
179 return InsertCheckItem(0u, itemid
, text
, help
);
182 // prepend a radio item
183 wxMenuItem
* PrependRadioItem(int itemid
,
184 const wxString
& text
,
185 const wxString
& help
= wxEmptyString
)
187 return InsertRadioItem(0u, itemid
, text
, help
);
191 wxMenuItem
* Prepend(int itemid
,
192 const wxString
& text
,
194 const wxString
& help
= wxEmptyString
)
196 return Insert(0u, itemid
, text
, submenu
, help
);
199 // detach an item from the menu, but don't delete it so that it can be
200 // added back later (but if it's not, the caller is responsible for
202 wxMenuItem
*Remove(int itemid
) { return Remove(FindChildItem(itemid
)); }
203 wxMenuItem
*Remove(wxMenuItem
*item
);
205 // delete an item from the menu (submenus are not destroyed by this
206 // function, see Destroy)
207 bool Delete(int itemid
) { return Delete(FindChildItem(itemid
)); }
208 bool Delete(wxMenuItem
*item
);
210 // delete the item from menu and destroy it (if it's a submenu)
211 bool Destroy(int itemid
) { return Destroy(FindChildItem(itemid
)); }
212 bool Destroy(wxMenuItem
*item
);
218 size_t GetMenuItemCount() const { return m_items
.GetCount(); }
220 const wxMenuItemList
& GetMenuItems() const { return m_items
; }
221 wxMenuItemList
& GetMenuItems() { return m_items
; }
224 virtual int FindItem(const wxString
& item
) const;
225 wxMenuItem
* FindItem(int itemid
, wxMenu
**menu
= NULL
) const;
228 wxMenuItem
* FindItemByPosition(size_t position
) const;
230 // get/set items attributes
231 void Enable(int itemid
, bool enable
);
232 bool IsEnabled(int itemid
) const;
234 void Check(int itemid
, bool check
);
235 bool IsChecked(int itemid
) const;
237 void SetLabel(int itemid
, const wxString
& label
);
238 wxString
GetLabel(int itemid
) const;
240 // Returns the stripped label
241 wxString
GetLabelText(int itemid
) const { return wxMenuItem::GetLabelText(GetLabel(itemid
)); }
243 virtual void SetHelpString(int itemid
, const wxString
& helpString
);
244 virtual wxString
GetHelpString(int itemid
) const;
250 virtual void SetTitle(const wxString
& title
) { m_title
= title
; }
251 const wxString
& GetTitle() const { return m_title
; }
254 void SetEventHandler(wxEvtHandler
*handler
) { m_eventHandler
= handler
; }
255 wxEvtHandler
*GetEventHandler() const { return m_eventHandler
; }
257 // Invoking window: this is set by wxWindow::PopupMenu() before showing a
258 // popup menu and reset after it's hidden. Notice that GetInvokingWindow()
259 // recurses upwards and will return the invoking window for any submenu of
260 // a popup menu as well as the menu itself.
261 void SetInvokingWindow(wxWindow
*win
);
262 wxWindow
*GetInvokingWindow() const;
265 long GetStyle() const { return m_style
; }
267 // implementation helpers
268 // ----------------------
270 // Updates the UI for a menu and all submenus recursively. source is the
271 // object that has the update event handlers defined for it. If NULL, the
272 // menu or associated window will be used.
273 void UpdateUI(wxEvtHandler
* source
= NULL
);
275 // get the menu bar this menu is attached to (may be NULL, always NULL for
276 // popup menus). Traverse up the menu hierarchy to find it.
277 wxMenuBar
*GetMenuBar() const;
279 // called when the menu is attached/detached to/from a menu bar
280 virtual void Attach(wxMenuBarBase
*menubar
);
281 virtual void Detach();
283 // is the menu attached to a menu bar (or is it a popup one)?
284 bool IsAttached() const { return GetMenuBar() != NULL
; }
286 // set/get the parent of this menu
287 void SetParent(wxMenu
*parent
) { m_menuParent
= parent
; }
288 wxMenu
*GetParent() const { return m_menuParent
; }
290 // implementation only from now on
291 // -------------------------------
293 // unlike FindItem(), this function doesn't recurse but only looks through
294 // our direct children and also may return the index of the found child if
296 wxMenuItem
*FindChildItem(int itemid
, size_t *pos
= NULL
) const;
298 // called to generate a wxCommandEvent, return true if it was processed,
301 // the checked parameter may have boolean value or -1 for uncheckable items
302 bool SendEvent(int itemid
, int checked
= -1);
304 // compatibility: these functions are deprecated, use the new ones instead
305 // -----------------------------------------------------------------------
307 // use the versions taking wxItem_XXX now instead, they're more readable
308 // and allow adding the radio items as well
309 void Append(int itemid
,
310 const wxString
& text
,
311 const wxString
& help
,
314 Append(itemid
, text
, help
, isCheckable
? wxITEM_CHECK
: wxITEM_NORMAL
);
317 // use more readable and not requiring unused itemid AppendSubMenu() instead
318 wxMenuItem
* Append(int itemid
,
319 const wxString
& text
,
321 const wxString
& help
= wxEmptyString
)
323 return DoAppend(wxMenuItem::New((wxMenu
*)this, itemid
, text
, help
,
324 wxITEM_NORMAL
, submenu
));
327 void Insert(size_t pos
,
329 const wxString
& text
,
330 const wxString
& help
,
333 Insert(pos
, itemid
, text
, help
, isCheckable
? wxITEM_CHECK
: wxITEM_NORMAL
);
336 void Prepend(int itemid
,
337 const wxString
& text
,
338 const wxString
& help
,
341 Insert(0u, itemid
, text
, help
, isCheckable
);
344 static void LockAccels(bool locked
)
350 // virtuals to override in derived classes
351 // ---------------------------------------
353 virtual wxMenuItem
* DoAppend(wxMenuItem
*item
);
354 virtual wxMenuItem
* DoInsert(size_t pos
, wxMenuItem
*item
);
356 virtual wxMenuItem
*DoRemove(wxMenuItem
*item
);
357 virtual bool DoDelete(wxMenuItem
*item
);
358 virtual bool DoDestroy(wxMenuItem
*item
);
363 // common part of all ctors
364 void Init(long style
);
366 // associate the submenu with this menu
367 void AddSubMenu(wxMenu
*submenu
);
369 wxMenuBar
*m_menuBar
; // menubar we belong to or NULL
370 wxMenu
*m_menuParent
; // parent menu or NULL
372 wxString m_title
; // the menu title or label
373 wxMenuItemList m_items
; // the list of menu items
375 wxWindow
*m_invokingWindow
; // for popup menus
377 long m_style
; // combination of wxMENU_XXX flags
379 wxEvtHandler
*m_eventHandler
; // a pluggable in event handler
381 static bool ms_locked
;
383 wxDECLARE_NO_COPY_CLASS(wxMenuBase
);
386 // ----------------------------------------------------------------------------
388 // ----------------------------------------------------------------------------
390 class WXDLLIMPEXP_CORE wxMenuBarBase
: public wxWindow
396 // dtor will delete all menus we own
397 virtual ~wxMenuBarBase();
399 // menu bar construction
400 // ---------------------
402 // append a menu to the end of menubar, return true if ok
403 virtual bool Append(wxMenu
*menu
, const wxString
& title
);
405 // insert a menu before the given position into the menubar, return true
407 virtual bool Insert(size_t pos
, wxMenu
*menu
, const wxString
& title
);
409 // menu bar items access
410 // ---------------------
412 // get the number of menus in the menu bar
413 size_t GetMenuCount() const { return m_menus
.GetCount(); }
415 // get the menu at given position
416 wxMenu
*GetMenu(size_t pos
) const;
418 // replace the menu at given position with another one, returns the
419 // previous menu (which should be deleted by the caller)
420 virtual wxMenu
*Replace(size_t pos
, wxMenu
*menu
, const wxString
& title
);
422 // delete the menu at given position from the menu bar, return the pointer
423 // to the menu (which should be deleted by the caller)
424 virtual wxMenu
*Remove(size_t pos
);
426 // enable or disable a submenu
427 virtual void EnableTop(size_t pos
, bool enable
) = 0;
429 // is the menu enabled?
430 virtual bool IsEnabledTop(size_t WXUNUSED(pos
)) const { return true; }
432 // get or change the label of the menu at given position
433 virtual void SetMenuLabel(size_t pos
, const wxString
& label
) = 0;
434 virtual wxString
GetMenuLabel(size_t pos
) const = 0;
436 // get the stripped label of the menu at given position
437 virtual wxString
GetMenuLabelText(size_t pos
) const { return wxMenuItem::GetLabelText(GetMenuLabel(pos
)); }
442 // by menu and item names, returns wxNOT_FOUND if not found or id of the
444 virtual int FindMenuItem(const wxString
& menu
, const wxString
& item
) const;
446 // find item by id (in any menu), returns NULL if not found
448 // if menu is !NULL, it will be filled with wxMenu this item belongs to
449 virtual wxMenuItem
* FindItem(int itemid
, wxMenu
**menu
= NULL
) const;
451 // find menu by its caption, return wxNOT_FOUND on failure
452 int FindMenu(const wxString
& title
) const;
457 // all these functions just use FindItem() and then call an appropriate
460 // NB: under MSW, these methods can only be used after the menubar had
461 // been attached to the frame
463 void Enable(int itemid
, bool enable
);
464 void Check(int itemid
, bool check
);
465 bool IsChecked(int itemid
) const;
466 bool IsEnabled(int itemid
) const;
467 virtual bool IsEnabled() const { return wxWindow::IsEnabled(); }
469 void SetLabel(int itemid
, const wxString
&label
);
470 wxString
GetLabel(int itemid
) const;
472 void SetHelpString(int itemid
, const wxString
& helpString
);
473 wxString
GetHelpString(int itemid
) const;
475 // implementation helpers
477 // get the frame we are attached to (may return NULL)
478 wxFrame
*GetFrame() const { return m_menuBarFrame
; }
480 // returns true if we're attached to a frame
481 bool IsAttached() const { return GetFrame() != NULL
; }
483 // associate the menubar with the frame
484 virtual void Attach(wxFrame
*frame
);
486 // called before deleting the menubar normally
487 virtual void Detach();
489 // need to override these ones to avoid virtual function hiding
490 virtual bool Enable(bool enable
= true) { return wxWindow::Enable(enable
); }
491 virtual void SetLabel(const wxString
& s
) { wxWindow::SetLabel(s
); }
492 virtual wxString
GetLabel() const { return wxWindow::GetLabel(); }
494 // don't want menu bars to accept the focus by tabbing to them
495 virtual bool AcceptsFocusFromKeyboard() const { return false; }
497 // update all menu item states in all menus
498 virtual void UpdateMenus();
500 virtual bool CanBeOutsideClientArea() const { return true; }
502 #if WXWIN_COMPATIBILITY_2_8
503 // get or change the label of the menu at given position
504 // Deprecated in favour of SetMenuLabel
505 wxDEPRECATED( void SetLabelTop(size_t pos
, const wxString
& label
) );
506 // Deprecated in favour of GetMenuLabelText
507 wxDEPRECATED( wxString
GetLabelTop(size_t pos
) const );
511 // the list of all our menus
514 // the frame we are attached to (may be NULL)
515 wxFrame
*m_menuBarFrame
;
517 wxDECLARE_NO_COPY_CLASS(wxMenuBarBase
);
520 // ----------------------------------------------------------------------------
521 // include the real class declaration
522 // ----------------------------------------------------------------------------
524 #ifdef wxUSE_BASE_CLASSES_ONLY
525 #define wxMenuItem wxMenuItemBase
526 #else // !wxUSE_BASE_CLASSES_ONLY
527 #if defined(__WXUNIVERSAL__)
528 #include "wx/univ/menu.h"
529 #elif defined(__WXPALMOS__)
530 #include "wx/palmos/menu.h"
531 #elif defined(__WXMSW__)
532 #include "wx/msw/menu.h"
533 #elif defined(__WXMOTIF__)
534 #include "wx/motif/menu.h"
535 #elif defined(__WXGTK20__)
536 #include "wx/gtk/menu.h"
537 #elif defined(__WXGTK__)
538 #include "wx/gtk1/menu.h"
539 #elif defined(__WXMAC__)
540 #include "wx/osx/menu.h"
541 #elif defined(__WXCOCOA__)
542 #include "wx/cocoa/menu.h"
543 #elif defined(__WXPM__)
544 #include "wx/os2/menu.h"
546 #endif // wxUSE_BASE_CLASSES_ONLY/!wxUSE_BASE_CLASSES_ONLY
548 #endif // wxUSE_MENUS