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 wxFrame
;
31 class WXDLLIMPEXP_FWD_CORE wxMenu
;
32 class WXDLLIMPEXP_FWD_CORE wxMenuBarBase
;
33 class WXDLLIMPEXP_FWD_CORE wxMenuBar
;
34 class WXDLLIMPEXP_FWD_CORE wxMenuItem
;
36 // pseudo template list classes
37 WX_DECLARE_EXPORTED_LIST(wxMenu
, wxMenuList
);
38 WX_DECLARE_EXPORTED_LIST(wxMenuItem
, wxMenuItemList
);
40 // ----------------------------------------------------------------------------
42 // ----------------------------------------------------------------------------
44 class WXDLLIMPEXP_CORE wxMenuBase
: public wxEvtHandler
48 static wxMenu
*New(const wxString
& title
= wxEmptyString
, long style
= 0);
51 wxMenuBase(const wxString
& title
, long style
= 0) : m_title(title
)
53 wxMenuBase(long style
= 0)
56 // dtor deletes all the menu items we own
57 virtual ~wxMenuBase();
62 // append any kind of item (normal/check/radio/separator)
63 wxMenuItem
* Append(int itemid
,
64 const wxString
& text
= wxEmptyString
,
65 const wxString
& help
= wxEmptyString
,
66 wxItemKind kind
= wxITEM_NORMAL
)
68 return DoAppend(wxMenuItem::New((wxMenu
*)this, itemid
, text
, help
, kind
));
71 // append a separator to the menu
72 wxMenuItem
* AppendSeparator() { return Append(wxID_SEPARATOR
); }
74 // append a check item
75 wxMenuItem
* AppendCheckItem(int itemid
,
77 const wxString
& help
= wxEmptyString
)
79 return Append(itemid
, text
, help
, wxITEM_CHECK
);
82 // append a radio item
83 wxMenuItem
* AppendRadioItem(int itemid
,
85 const wxString
& help
= wxEmptyString
)
87 return Append(itemid
, text
, help
, wxITEM_RADIO
);
91 wxMenuItem
* AppendSubMenu(wxMenu
*submenu
,
93 const wxString
& help
= wxEmptyString
)
95 return DoAppend(wxMenuItem::New((wxMenu
*)this, wxID_ANY
, text
, help
,
96 wxITEM_NORMAL
, submenu
));
99 // the most generic form of Append() - append anything
100 wxMenuItem
* Append(wxMenuItem
*item
) { return DoAppend(item
); }
102 // insert a break in the menu (only works when appending the items, not
104 virtual void Break() { }
106 // insert an item before given position
107 wxMenuItem
* Insert(size_t pos
, wxMenuItem
*item
);
109 // insert an item before given position
110 wxMenuItem
* Insert(size_t pos
,
112 const wxString
& text
= wxEmptyString
,
113 const wxString
& help
= wxEmptyString
,
114 wxItemKind kind
= wxITEM_NORMAL
)
116 return Insert(pos
, wxMenuItem::New((wxMenu
*)this, itemid
, text
, help
, kind
));
119 // insert a separator
120 wxMenuItem
* InsertSeparator(size_t pos
)
122 return Insert(pos
, wxMenuItem::New((wxMenu
*)this, wxID_SEPARATOR
));
125 // insert a check item
126 wxMenuItem
* InsertCheckItem(size_t pos
,
128 const wxString
& text
,
129 const wxString
& help
= wxEmptyString
)
131 return Insert(pos
, itemid
, text
, help
, wxITEM_CHECK
);
134 // insert a radio item
135 wxMenuItem
* InsertRadioItem(size_t pos
,
137 const wxString
& text
,
138 const wxString
& help
= wxEmptyString
)
140 return Insert(pos
, itemid
, text
, help
, wxITEM_RADIO
);
144 wxMenuItem
* Insert(size_t pos
,
146 const wxString
& text
,
148 const wxString
& help
= wxEmptyString
)
150 return Insert(pos
, wxMenuItem::New((wxMenu
*)this, itemid
, text
, help
,
151 wxITEM_NORMAL
, submenu
));
154 // prepend an item to the menu
155 wxMenuItem
* Prepend(wxMenuItem
*item
)
157 return Insert(0u, item
);
160 // prepend any item to the menu
161 wxMenuItem
* Prepend(int itemid
,
162 const wxString
& text
= wxEmptyString
,
163 const wxString
& help
= wxEmptyString
,
164 wxItemKind kind
= wxITEM_NORMAL
)
166 return Insert(0u, itemid
, text
, help
, kind
);
169 // prepend a separator
170 wxMenuItem
* PrependSeparator()
172 return InsertSeparator(0u);
175 // prepend a check item
176 wxMenuItem
* PrependCheckItem(int itemid
,
177 const wxString
& text
,
178 const wxString
& help
= wxEmptyString
)
180 return InsertCheckItem(0u, itemid
, text
, help
);
183 // prepend a radio item
184 wxMenuItem
* PrependRadioItem(int itemid
,
185 const wxString
& text
,
186 const wxString
& help
= wxEmptyString
)
188 return InsertRadioItem(0u, itemid
, text
, help
);
192 wxMenuItem
* Prepend(int itemid
,
193 const wxString
& text
,
195 const wxString
& help
= wxEmptyString
)
197 return Insert(0u, itemid
, text
, submenu
, help
);
200 // detach an item from the menu, but don't delete it so that it can be
201 // added back later (but if it's not, the caller is responsible for
203 wxMenuItem
*Remove(int itemid
) { return Remove(FindChildItem(itemid
)); }
204 wxMenuItem
*Remove(wxMenuItem
*item
);
206 // delete an item from the menu (submenus are not destroyed by this
207 // function, see Destroy)
208 bool Delete(int itemid
) { return Delete(FindChildItem(itemid
)); }
209 bool Delete(wxMenuItem
*item
);
211 // delete the item from menu and destroy it (if it's a submenu)
212 bool Destroy(int itemid
) { return Destroy(FindChildItem(itemid
)); }
213 bool Destroy(wxMenuItem
*item
);
219 size_t GetMenuItemCount() const { return m_items
.GetCount(); }
221 const wxMenuItemList
& GetMenuItems() const { return m_items
; }
222 wxMenuItemList
& GetMenuItems() { return m_items
; }
225 virtual int FindItem(const wxString
& item
) const;
226 wxMenuItem
* FindItem(int itemid
, wxMenu
**menu
= NULL
) const;
229 wxMenuItem
* FindItemByPosition(size_t position
) const;
231 // get/set items attributes
232 void Enable(int itemid
, bool enable
);
233 bool IsEnabled(int itemid
) const;
235 void Check(int itemid
, bool check
);
236 bool IsChecked(int itemid
) const;
238 void SetLabel(int itemid
, const wxString
& label
);
239 wxString
GetLabel(int itemid
) const;
241 // Returns the stripped label
242 wxString
GetLabelText(int itemid
) const { return wxMenuItem::GetLabelText(GetLabel(itemid
)); }
244 virtual void SetHelpString(int itemid
, const wxString
& helpString
);
245 virtual wxString
GetHelpString(int itemid
) const;
251 virtual void SetTitle(const wxString
& title
) { m_title
= title
; }
252 const wxString
& GetTitle() const { return m_title
; }
255 void SetEventHandler(wxEvtHandler
*handler
) { m_eventHandler
= handler
; }
256 wxEvtHandler
*GetEventHandler() const { return m_eventHandler
; }
258 // Invoking window: this is set by wxWindow::PopupMenu() before showing a
259 // popup menu and reset after it's hidden. Notice that you probably want to
260 // use GetWindow() below instead of GetInvokingWindow() as the latter only
261 // returns non-NULL for the top level menus
263 // NB: avoid calling SetInvokingWindow() directly if possible, use
264 // wxMenuInvokingWindowSetter class below instead
265 void SetInvokingWindow(wxWindow
*win
);
266 wxWindow
*GetInvokingWindow() const { return m_invokingWindow
; }
268 // the window associated with this menu: this is the invoking window for
269 // popup menus or the top level window to which the menu bar is attached
270 // for menus which are part of a menu bar
271 wxWindow
*GetWindow() const;
274 long GetStyle() const { return m_style
; }
276 // implementation helpers
277 // ----------------------
279 // Updates the UI for a menu and all submenus recursively. source is the
280 // object that has the update event handlers defined for it. If NULL, the
281 // menu or associated window will be used.
282 void UpdateUI(wxEvtHandler
* source
= NULL
);
284 // get the menu bar this menu is attached to (may be NULL, always NULL for
285 // popup menus). Traverse up the menu hierarchy to find it.
286 wxMenuBar
*GetMenuBar() const;
288 // called when the menu is attached/detached to/from a menu bar
289 virtual void Attach(wxMenuBarBase
*menubar
);
290 virtual void Detach();
292 // is the menu attached to a menu bar (or is it a popup one)?
293 bool IsAttached() const { return GetMenuBar() != NULL
; }
295 // set/get the parent of this menu
296 void SetParent(wxMenu
*parent
) { m_menuParent
= parent
; }
297 wxMenu
*GetParent() const { return m_menuParent
; }
299 // implementation only from now on
300 // -------------------------------
302 // unlike FindItem(), this function doesn't recurse but only looks through
303 // our direct children and also may return the index of the found child if
305 wxMenuItem
*FindChildItem(int itemid
, size_t *pos
= NULL
) const;
307 // called to generate a wxCommandEvent, return true if it was processed,
310 // the checked parameter may have boolean value or -1 for uncheckable items
311 bool SendEvent(int itemid
, int checked
= -1);
313 // compatibility: these functions are deprecated, use the new ones instead
314 // -----------------------------------------------------------------------
316 // use the versions taking wxItem_XXX now instead, they're more readable
317 // and allow adding the radio items as well
318 void Append(int itemid
,
319 const wxString
& text
,
320 const wxString
& help
,
323 Append(itemid
, text
, help
, isCheckable
? wxITEM_CHECK
: wxITEM_NORMAL
);
326 // use more readable and not requiring unused itemid AppendSubMenu() instead
327 wxMenuItem
* Append(int itemid
,
328 const wxString
& text
,
330 const wxString
& help
= wxEmptyString
)
332 return DoAppend(wxMenuItem::New((wxMenu
*)this, itemid
, text
, help
,
333 wxITEM_NORMAL
, submenu
));
336 void Insert(size_t pos
,
338 const wxString
& text
,
339 const wxString
& help
,
342 Insert(pos
, itemid
, text
, help
, isCheckable
? wxITEM_CHECK
: wxITEM_NORMAL
);
345 void Prepend(int itemid
,
346 const wxString
& text
,
347 const wxString
& help
,
350 Insert(0u, itemid
, text
, help
, isCheckable
);
353 static void LockAccels(bool locked
)
359 // virtuals to override in derived classes
360 // ---------------------------------------
362 virtual wxMenuItem
* DoAppend(wxMenuItem
*item
);
363 virtual wxMenuItem
* DoInsert(size_t pos
, wxMenuItem
*item
);
365 virtual wxMenuItem
*DoRemove(wxMenuItem
*item
);
366 virtual bool DoDelete(wxMenuItem
*item
);
367 virtual bool DoDestroy(wxMenuItem
*item
);
372 // common part of all ctors
373 void Init(long style
);
375 // associate the submenu with this menu
376 void AddSubMenu(wxMenu
*submenu
);
378 wxMenuBar
*m_menuBar
; // menubar we belong to or NULL
379 wxMenu
*m_menuParent
; // parent menu or NULL
381 wxString m_title
; // the menu title or label
382 wxMenuItemList m_items
; // the list of menu items
384 wxWindow
*m_invokingWindow
; // for popup menus
386 long m_style
; // combination of wxMENU_XXX flags
388 wxEvtHandler
*m_eventHandler
; // a pluggable in event handler
390 static bool ms_locked
;
392 wxDECLARE_NO_COPY_CLASS(wxMenuBase
);
395 #if wxUSE_EXTENDED_RTTI
397 // ----------------------------------------------------------------------------
399 // ----------------------------------------------------------------------------
401 class WXDLLEXPORT wxMenuInfoHelper
: public wxObject
404 wxMenuInfoHelper() { m_menu
= NULL
; }
405 virtual ~wxMenuInfoHelper() { }
407 bool Create( wxMenu
*menu
, const wxString
&title
)
414 wxMenu
* GetMenu() const { return m_menu
; }
415 wxString
GetTitle() const { return m_title
; }
421 DECLARE_DYNAMIC_CLASS(wxMenuInfoHelper
)
424 WX_DECLARE_EXPORTED_LIST(wxMenuInfoHelper
, wxMenuInfoHelperList
);
428 // ----------------------------------------------------------------------------
430 // ----------------------------------------------------------------------------
432 class WXDLLIMPEXP_CORE wxMenuBarBase
: public wxWindow
438 // dtor will delete all menus we own
439 virtual ~wxMenuBarBase();
441 // menu bar construction
442 // ---------------------
444 // append a menu to the end of menubar, return true if ok
445 virtual bool Append(wxMenu
*menu
, const wxString
& title
);
447 // insert a menu before the given position into the menubar, return true
449 virtual bool Insert(size_t pos
, wxMenu
*menu
, const wxString
& title
);
451 // menu bar items access
452 // ---------------------
454 // get the number of menus in the menu bar
455 size_t GetMenuCount() const { return m_menus
.GetCount(); }
457 // get the menu at given position
458 wxMenu
*GetMenu(size_t pos
) const;
460 // replace the menu at given position with another one, returns the
461 // previous menu (which should be deleted by the caller)
462 virtual wxMenu
*Replace(size_t pos
, wxMenu
*menu
, const wxString
& title
);
464 // delete the menu at given position from the menu bar, return the pointer
465 // to the menu (which should be deleted by the caller)
466 virtual wxMenu
*Remove(size_t pos
);
468 // enable or disable a submenu
469 virtual void EnableTop(size_t pos
, bool enable
) = 0;
471 // is the menu enabled?
472 virtual bool IsEnabledTop(size_t WXUNUSED(pos
)) const { return true; }
474 // get or change the label of the menu at given position
475 virtual void SetMenuLabel(size_t pos
, const wxString
& label
) = 0;
476 virtual wxString
GetMenuLabel(size_t pos
) const = 0;
478 // get the stripped label of the menu at given position
479 virtual wxString
GetMenuLabelText(size_t pos
) const { return wxMenuItem::GetLabelText(GetMenuLabel(pos
)); }
484 // by menu and item names, returns wxNOT_FOUND if not found or id of the
486 virtual int FindMenuItem(const wxString
& menu
, const wxString
& item
) const;
488 // find item by id (in any menu), returns NULL if not found
490 // if menu is !NULL, it will be filled with wxMenu this item belongs to
491 virtual wxMenuItem
* FindItem(int itemid
, wxMenu
**menu
= NULL
) const;
493 // find menu by its caption, return wxNOT_FOUND on failure
494 int FindMenu(const wxString
& title
) const;
499 // all these functions just use FindItem() and then call an appropriate
502 // NB: under MSW, these methods can only be used after the menubar had
503 // been attached to the frame
505 void Enable(int itemid
, bool enable
);
506 void Check(int itemid
, bool check
);
507 bool IsChecked(int itemid
) const;
508 bool IsEnabled(int itemid
) const;
509 virtual bool IsEnabled() const { return wxWindow::IsEnabled(); }
511 void SetLabel(int itemid
, const wxString
&label
);
512 wxString
GetLabel(int itemid
) const;
514 void SetHelpString(int itemid
, const wxString
& helpString
);
515 wxString
GetHelpString(int itemid
) const;
517 // implementation helpers
519 // get the frame we are attached to (may return NULL)
520 wxFrame
*GetFrame() const { return m_menuBarFrame
; }
522 // returns true if we're attached to a frame
523 bool IsAttached() const { return GetFrame() != NULL
; }
525 // associate the menubar with the frame
526 virtual void Attach(wxFrame
*frame
);
528 // called before deleting the menubar normally
529 virtual void Detach();
531 // need to override these ones to avoid virtual function hiding
532 virtual bool Enable(bool enable
= true) { return wxWindow::Enable(enable
); }
533 virtual void SetLabel(const wxString
& s
) { wxWindow::SetLabel(s
); }
534 virtual wxString
GetLabel() const { return wxWindow::GetLabel(); }
536 // don't want menu bars to accept the focus by tabbing to them
537 virtual bool AcceptsFocusFromKeyboard() const { return false; }
539 // update all menu item states in all menus
540 virtual void UpdateMenus();
542 virtual bool CanBeOutsideClientArea() const { return true; }
544 #if wxUSE_EXTENDED_RTTI
546 bool AppendMenuInfo( const wxMenuInfoHelper
*info
)
547 { return Append( info
->GetMenu(), info
->GetTitle() ); }
548 const wxMenuInfoHelperList
& GetMenuInfos() const;
551 #if WXWIN_COMPATIBILITY_2_8
552 // get or change the label of the menu at given position
553 // Deprecated in favour of SetMenuLabel
554 wxDEPRECATED( void SetLabelTop(size_t pos
, const wxString
& label
) );
555 // Deprecated in favour of GetMenuLabelText
556 wxDEPRECATED( wxString
GetLabelTop(size_t pos
) const );
560 // the list of all our menus
563 #if wxUSE_EXTENDED_RTTI
565 wxMenuInfoHelperList m_menuInfos
;
568 // the frame we are attached to (may be NULL)
569 wxFrame
*m_menuBarFrame
;
571 wxDECLARE_NO_COPY_CLASS(wxMenuBarBase
);
574 // ----------------------------------------------------------------------------
575 // include the real class declaration
576 // ----------------------------------------------------------------------------
578 #ifdef wxUSE_BASE_CLASSES_ONLY
579 #define wxMenuItem wxMenuItemBase
580 #else // !wxUSE_BASE_CLASSES_ONLY
581 #if defined(__WXUNIVERSAL__)
582 #include "wx/univ/menu.h"
583 #elif defined(__WXMSW__)
584 #include "wx/msw/menu.h"
585 #elif defined(__WXMOTIF__)
586 #include "wx/motif/menu.h"
587 #elif defined(__WXGTK20__)
588 #include "wx/gtk/menu.h"
589 #elif defined(__WXGTK__)
590 #include "wx/gtk1/menu.h"
591 #elif defined(__WXMAC__)
592 #include "wx/osx/menu.h"
593 #elif defined(__WXCOCOA__)
594 #include "wx/cocoa/menu.h"
595 #elif defined(__WXPM__)
596 #include "wx/os2/menu.h"
598 #endif // wxUSE_BASE_CLASSES_ONLY/!wxUSE_BASE_CLASSES_ONLY
600 // ----------------------------------------------------------------------------
601 // Helper class used in the implementation only: sets the invoking window of
602 // the given menu in its ctor and resets it in dtor.
603 // ----------------------------------------------------------------------------
605 class wxMenuInvokingWindowSetter
608 // Ctor sets the invoking window for the given menu.
610 // The menu lifetime must be greater than that of this class.
611 wxMenuInvokingWindowSetter(wxMenu
& menu
, wxWindow
*win
)
614 menu
.SetInvokingWindow(win
);
617 // Dtor resets the invoking window.
618 ~wxMenuInvokingWindowSetter()
620 m_menu
.SetInvokingWindow(NULL
);
626 wxDECLARE_NO_COPY_CLASS(wxMenuInvokingWindowSetter
);
629 #endif // wxUSE_MENUS
631 #endif // _WX_MENU_H_BASE_