1 ///////////////////////////////////////////////////////////////////////////////
3 // Purpose: wxMenu and wxMenuBar classes
4 // Author: Vadim Zeitlin
8 // Copyright: (c) wxWindows team
9 // Licence: wxWindows license
10 ///////////////////////////////////////////////////////////////////////////////
12 #ifndef _WX_MENU_H_BASE_
13 #define _WX_MENU_H_BASE_
16 #pragma interface "menubase.h"
21 // ----------------------------------------------------------------------------
23 // ----------------------------------------------------------------------------
25 #include "wx/list.h" // for "template" list classes
26 #include "wx/window.h" // base class for wxMenuBar
28 // also include this one to ensure compatibility with old code which only
30 #include "wx/menuitem.h"
32 class WXDLLEXPORT wxMenu
;
33 class WXDLLEXPORT wxMenuBarBase
;
34 class WXDLLEXPORT wxMenuBar
;
35 class WXDLLEXPORT wxMenuItem
;
37 // pseudo template list classes
38 WX_DECLARE_EXPORTED_LIST(wxMenu
, wxMenuList
);
39 WX_DECLARE_EXPORTED_LIST(wxMenuItem
, wxMenuItemList
);
41 // ----------------------------------------------------------------------------
42 // conditional compilation
43 // ----------------------------------------------------------------------------
45 // having callbacks in menus is a wxWin 1.6x feature which should be replaced
46 // with event tables in wxWin 2.xx code - however provide it because many
47 // people like it a lot by default
48 #ifndef wxUSE_MENU_CALLBACK
49 #if WXWIN_COMPATIBILITY_2
50 #define wxUSE_MENU_CALLBACK 1
52 #define wxUSE_MENU_CALLBACK 0
53 #endif // WXWIN_COMPATIBILITY_2
54 #endif // !defined(wxUSE_MENU_CALLBACK)
56 // ----------------------------------------------------------------------------
58 // ----------------------------------------------------------------------------
60 class WXDLLEXPORT wxMenuBase
: public wxEvtHandler
64 static wxMenu
*New(const wxString
& title
= wxEmptyString
, long style
= 0);
67 wxMenuBase(const wxString
& title
, long style
= 0) : m_title(title
)
69 wxMenuBase(long style
= 0)
72 // dtor deletes all the menu items we own
73 virtual ~wxMenuBase();
78 // append any kind of item (normal/check/radio/separator)
81 const wxString
& help
= wxEmptyString
,
82 wxItemKind kind
= wxItem_Normal
)
84 DoAppend(wxMenuItem::New((wxMenu
*)this, id
, text
, help
, kind
));
87 // append a separator to the menu
88 void AppendSeparator() { Append(wxID_SEPARATOR
, wxEmptyString
); }
90 // append a check item
91 void AppendCheckItem(int id
,
93 const wxString
& help
= wxEmptyString
)
95 Append(id
, text
, help
, wxItem_Check
);
98 // append a radio item
99 void AppendRadioItem(int id
,
100 const wxString
& text
,
101 const wxString
& help
= wxEmptyString
)
103 Append(id
, text
, help
, wxItem_Radio
);
108 const wxString
& text
,
110 const wxString
& help
= wxEmptyString
)
112 DoAppend(wxMenuItem::New((wxMenu
*)this, id
, text
, help
, FALSE
, submenu
));
115 // the most generic form of Append() - append anything
116 void Append(wxMenuItem
*item
) { DoAppend(item
); }
118 // insert a break in the menu (only works when appending the items, not
120 virtual void Break() { }
122 // insert an item before given position
123 bool Insert(size_t pos
, wxMenuItem
*item
);
125 // insert an item before given position
126 void Insert(size_t pos
,
128 const wxString
& text
,
129 const wxString
& help
= wxEmptyString
,
130 wxItemKind kind
= wxItem_Normal
)
132 Insert(pos
, wxMenuItem::New((wxMenu
*)this, id
, text
, help
, kind
));
135 // insert a separator
136 void InsertSeparator(size_t pos
)
138 Insert(pos
, wxMenuItem::New((wxMenu
*)this));
141 // insert a check item
142 void InsertCheckItem(size_t pos
,
144 const wxString
& text
,
145 const wxString
& help
= wxEmptyString
)
147 Insert(pos
, id
, text
, help
, wxItem_Check
);
150 // insert a radio item
151 void InsertRadioItem(size_t pos
,
153 const wxString
& text
,
154 const wxString
& help
= wxEmptyString
)
156 Insert(pos
, id
, text
, help
, wxItem_Radio
);
160 void Insert(size_t pos
,
162 const wxString
& text
,
164 const wxString
& help
= wxEmptyString
)
166 Insert(pos
, wxMenuItem::New((wxMenu
*)this, id
, text
, help
, FALSE
, submenu
));
169 // prepend an item to the menu
170 void Prepend(wxMenuItem
*item
)
175 // prepend any item to the menu
177 const wxString
& text
,
178 const wxString
& help
= wxEmptyString
,
179 wxItemKind kind
= wxItem_Normal
)
181 Insert(0u, id
, text
, help
, kind
);
184 // prepend a separator
185 void PrependSeparator()
190 // prepend a check item
191 void PrependCheckItem(int id
,
192 const wxString
& text
,
193 const wxString
& help
= wxEmptyString
)
195 InsertCheckItem(0u, id
, text
, help
);
198 // prepend a radio item
199 void PrependRadioItem(int id
,
200 const wxString
& text
,
201 const wxString
& help
= wxEmptyString
)
203 InsertRadioItem(0u, id
, text
, help
);
208 const wxString
& text
,
210 const wxString
& help
= wxEmptyString
)
212 Insert(0u, id
, text
, submenu
, help
);
215 // detach an item from the menu, but don't delete it so that it can be
216 // added back later (but if it's not, the caller is responsible for
218 wxMenuItem
*Remove(int id
) { return Remove(FindChildItem(id
)); }
219 wxMenuItem
*Remove(wxMenuItem
*item
);
221 // delete an item from the menu (submenus are not destroyed by this
222 // function, see Destroy)
223 bool Delete(int id
) { return Delete(FindChildItem(id
)); }
224 bool Delete(wxMenuItem
*item
);
226 // delete the item from menu and destroy it (if it's a submenu)
227 bool Destroy(int id
) { return Destroy(FindChildItem(id
)); }
228 bool Destroy(wxMenuItem
*item
);
234 size_t GetMenuItemCount() const { return m_items
.GetCount(); }
236 const wxMenuItemList
& GetMenuItems() const { return m_items
; }
237 wxMenuItemList
& GetMenuItems() { return m_items
; }
240 virtual int FindItem(const wxString
& item
) const;
241 wxMenuItem
* FindItem(int id
, wxMenu
**menu
= NULL
) const;
243 // get/set items attributes
244 void Enable(int id
, bool enable
);
245 bool IsEnabled(int id
) const;
247 void Check(int id
, bool check
);
248 bool IsChecked(int id
) const;
250 void SetLabel(int id
, const wxString
& label
);
251 wxString
GetLabel(int id
) const;
253 virtual void SetHelpString(int id
, const wxString
& helpString
);
254 virtual wxString
GetHelpString(int id
) const;
260 virtual void SetTitle(const wxString
& title
) { m_title
= title
; }
261 const wxString
GetTitle() const { return m_title
; }
264 void SetEventHandler(wxEvtHandler
*handler
) { m_eventHandler
= handler
; }
265 wxEvtHandler
*GetEventHandler() const { return m_eventHandler
; }
268 void SetInvokingWindow(wxWindow
*win
) { m_invokingWindow
= win
; }
269 wxWindow
*GetInvokingWindow() const { return m_invokingWindow
; }
272 long GetStyle() const { return m_style
; }
274 // implementation helpers
275 // ----------------------
277 // Updates the UI for a menu and all submenus recursively. source is the
278 // object that has the update event handlers defined for it. If NULL, the
279 // menu or associated window will be used.
280 void UpdateUI(wxEvtHandler
* source
= (wxEvtHandler
*)NULL
);
282 // get the menu bar this menu is attached to (may be NULL, always NULL for
284 wxMenuBar
*GetMenuBar() const { return m_menuBar
; }
286 // called when the menu is attached/detached to/from a menu bar
287 virtual void Attach(wxMenuBarBase
*menubar
);
288 virtual void Detach();
290 // is the menu attached to a menu bar (or is it a popup one)?
291 bool IsAttached() const { return m_menuBar
!= NULL
; }
293 // set/get the parent of this menu
294 void SetParent(wxMenu
*parent
) { m_menuParent
= parent
; }
295 wxMenu
*GetParent() const { return m_menuParent
; }
297 // implementation only from now on
298 // -------------------------------
300 // unlike FindItem(), this function doesn't recurse but only looks through
301 // our direct children and also may return the index of the found child if
303 wxMenuItem
*FindChildItem(int id
, size_t *pos
= NULL
) const;
305 // called to generate a wxCommandEvent, return TRUE if it was processed,
308 // the checked parameter may have boolean value or -1 for uncheckable items
309 bool SendEvent(int id
, int checked
= -1);
311 // compatibility: these functions are deprecated, use the new ones instead
312 // -----------------------------------------------------------------------
314 // use the versions taking wxItem_XXX now instead, they're more readable
315 // and allow adding the radio items as well
317 const wxString
& text
,
318 const wxString
& help
,
321 Append(id
, text
, help
, isCheckable
? wxItem_Check
: wxItem_Normal
);
324 void Insert(size_t pos
,
326 const wxString
& text
,
327 const wxString
& help
,
330 Insert(pos
, id
, text
, help
, isCheckable
? wxItem_Check
: wxItem_Normal
);
334 const wxString
& text
,
335 const wxString
& help
,
338 Insert(0u, id
, text
, help
, isCheckable
);
341 #if WXWIN_COMPATIBILITY
342 bool Enabled(int id
) const { return IsEnabled(id
); }
343 bool Checked(int id
) const { return IsChecked(id
); }
345 wxMenuItem
* FindItemForId(int itemId
, wxMenu
**itemMenu
) const
346 { return FindItem(itemId
, itemMenu
); }
348 wxList
& GetItems() const { return (wxList
&)m_items
; }
349 #endif // WXWIN_COMPATIBILITY
351 #if wxUSE_MENU_CALLBACK || defined(__WXMOTIF__)
352 // wxWin 1.6x compatible menu event handling
353 wxFunction
GetCallback() const { return m_callback
; }
354 void Callback(const wxFunction func
) { m_callback
= func
; }
356 wxFunction m_callback
;
357 #endif // wxUSE_MENU_CALLBACK
360 // virtuals to override in derived classes
361 // ---------------------------------------
363 virtual bool DoAppend(wxMenuItem
*item
);
364 virtual bool DoInsert(size_t pos
, wxMenuItem
*item
);
366 virtual wxMenuItem
*DoRemove(wxMenuItem
*item
);
367 virtual bool DoDelete(wxMenuItem
*item
);
368 virtual bool DoDestroy(wxMenuItem
*item
);
373 // common part of all ctors
374 void Init(long style
);
376 // associate the submenu with this menu
377 void AddSubMenu(wxMenu
*submenu
);
379 wxMenuBar
*m_menuBar
; // menubar we belong to or NULL
380 wxMenu
*m_menuParent
; // parent menu or NULL
382 wxString m_title
; // the menu title or label
383 wxMenuItemList m_items
; // the list of menu items
385 wxWindow
*m_invokingWindow
; // for popup menus
387 long m_style
; // combination of wxMENU_XXX flags
389 wxEvtHandler
*m_eventHandler
; // a pluggable in event handler
392 // ----------------------------------------------------------------------------
394 // ----------------------------------------------------------------------------
396 class WXDLLEXPORT wxMenuBarBase
: public wxWindow
402 // dtor will delete all menus we own
403 virtual ~wxMenuBarBase();
405 // menu bar construction
406 // ---------------------
408 // append a menu to the end of menubar, return TRUE if ok
409 virtual bool Append(wxMenu
*menu
, const wxString
& title
);
411 // insert a menu before the given position into the menubar, return TRUE
413 virtual bool Insert(size_t pos
, wxMenu
*menu
, const wxString
& title
);
415 // menu bar items access
416 // ---------------------
418 // get the number of menus in the menu bar
419 size_t GetMenuCount() const { return m_menus
.GetCount(); }
421 // get the menu at given position
422 wxMenu
*GetMenu(size_t pos
) const;
424 // replace the menu at given position with another one, returns the
425 // previous menu (which should be deleted by the caller)
426 virtual wxMenu
*Replace(size_t pos
, wxMenu
*menu
, const wxString
& title
);
428 // delete the menu at given position from the menu bar, return the pointer
429 // to the menu (which should be deleted by the caller)
430 virtual wxMenu
*Remove(size_t pos
);
432 // enable or disable a submenu
433 virtual void EnableTop(size_t pos
, bool enable
) = 0;
435 // is the menu enabled?
436 virtual bool IsEnabledTop(size_t WXUNUSED(pos
)) const { return TRUE
; }
438 // get or change the label of the menu at given position
439 virtual void SetLabelTop(size_t pos
, const wxString
& label
) = 0;
440 virtual wxString
GetLabelTop(size_t pos
) const = 0;
445 // by menu and item names, returns wxNOT_FOUND if not found or id of the
447 virtual int FindMenuItem(const wxString
& menu
, const wxString
& item
) const;
449 // find item by id (in any menu), returns NULL if not found
451 // if menu is !NULL, it will be filled with wxMenu this item belongs to
452 virtual wxMenuItem
* FindItem(int id
, wxMenu
**menu
= NULL
) const;
454 // find menu by its caption, return wxNOT_FOUND on failure
455 int FindMenu(const wxString
& title
) const;
460 // all these functions just use FindItem() and then call an appropriate
463 // NB: under MSW, these methods can only be used after the menubar had
464 // been attached to the frame
466 void Enable(int id
, bool enable
);
467 void Check(int id
, bool check
);
468 bool IsChecked(int id
) const;
469 bool IsEnabled(int id
) const;
471 void SetLabel(int id
, const wxString
&label
);
472 wxString
GetLabel(int id
) const;
474 void SetHelpString(int id
, const wxString
& helpString
);
475 wxString
GetHelpString(int id
) const;
477 // implementation helpers
479 // get the frame we are attached to (may return NULL)
480 wxFrame
*GetFrame() const { return m_menuBarFrame
; }
482 // returns TRUE if we're attached to a frame
483 bool IsAttached() const { return GetFrame() != NULL
; }
485 // associate the menubar with the frame
486 virtual void Attach(wxFrame
*frame
);
488 // called before deleting the menubar normally
489 virtual void Detach();
491 // need to override these ones to avoid virtual function hiding
492 virtual bool Enable(bool enable
= TRUE
) { return wxWindow::Enable(enable
); }
493 virtual void SetLabel(const wxString
& s
) { wxWindow::SetLabel(s
); }
494 virtual wxString
GetLabel() const { return wxWindow::GetLabel(); }
496 // don't want menu bars to accept the focus by tabbing to them
497 virtual bool AcceptsFocusFromKeyboard() const { return FALSE
; }
499 // compatibility only: these functions are deprecated, use the new ones
501 #if WXWIN_COMPATIBILITY
502 bool Enabled(int id
) const { return IsEnabled(id
); }
503 bool Checked(int id
) const { return IsChecked(id
); }
505 wxMenuItem
* FindMenuItemById(int id
) const
506 { return FindItem(id
); }
507 wxMenuItem
* FindItemForId(int id
, wxMenu
**menu
= NULL
) const
508 { return FindItem(id
, menu
); }
509 #endif // WXWIN_COMPATIBILITY
512 // the list of all our menus
515 // the frame we are attached to (may be NULL)
516 wxFrame
*m_menuBarFrame
;
519 // ----------------------------------------------------------------------------
520 // include the real class declaration
521 // ----------------------------------------------------------------------------
523 #ifdef wxUSE_BASE_CLASSES_ONLY
524 #define wxMenuItem wxMenuItemBase
525 #else // !wxUSE_BASE_CLASSES_ONLY
526 #if defined(__WXUNIVERSAL__)
527 #include "wx/univ/menu.h"
528 #elif defined(__WXMSW__)
529 #include "wx/msw/menu.h"
530 #elif defined(__WXMOTIF__)
531 #include "wx/motif/menu.h"
532 #elif defined(__WXGTK__)
533 #include "wx/gtk/menu.h"
534 #elif defined(__WXMAC__)
535 #include "wx/mac/menu.h"
536 #elif defined(__WXPM__)
537 #include "wx/os2/menu.h"
538 #elif defined(__WXSTUBS__)
539 #include "wx/stubs/menu.h"
541 #endif // wxUSE_BASE_CLASSES_ONLY/!wxUSE_BASE_CLASSES_ONLY
543 #endif // wxUSE_MENUS