wxPython/src/_menu.i

   1 /////////////////////////////////////////////////////////////////////////////
   2 // Name:        _menu.i
   3 // Purpose:     SWIG interface defs for wxMenuBar, wxMenu and wxMenuItem
   4 //
   5 // Author:      Robin Dunn
   6 //
   7 // Created:     24-June-1997
   8 // RCS-ID:      $Id$
   9 // Copyright:   (c) 2003 by Total Control Software
  10 // Licence:     wxWindows license
  11 /////////////////////////////////////////////////////////////////////////////
  12
  13 // Not a %module
  14
  15
  16 //---------------------------------------------------------------------------
  17 %newgroup
  18
  19 wxLIST_WRAPPER(wxMenuItemList, wxMenuItem);
  20
  21
  22
  23 MustHaveApp(wxMenu);
  24
  25 class wxMenu : public wxEvtHandler
  26 {
  27 public:
  28     %pythonAppend wxMenu         "self._setOORInfo(self)"
  29     %typemap(out) wxMenu*;    // turn off this typemap
  30
  31     wxMenu(const wxString& title = wxPyEmptyString, long style = 0);
  32
  33     // Turn it back on again
  34     %typemap(out) wxMenu* { $result = wxPyMake_wxObject($1, $owner); }
  35
  36
  37     // append any kind of item (normal/check/radio/separator)
  38     wxMenuItem* Append(int id,
  39                        const wxString& text = wxPyEmptyString,
  40                        const wxString& help = wxPyEmptyString,
  41                        wxItemKind kind = wxITEM_NORMAL);
  42
  43     // append a separator to the menu
  44     wxMenuItem* AppendSeparator();
  45
  46     // append a check item
  47     wxMenuItem* AppendCheckItem(int id,
  48                                 const wxString& text,
  49                                 const wxString& help = wxPyEmptyString);
  50
  51     // append a radio item
  52     wxMenuItem* AppendRadioItem(int id,
  53                                 const wxString& text,
  54                                 const wxString& help = wxPyEmptyString);
  55     // append a submenu
  56     %Rename(AppendMenu, wxMenuItem*, Append(int id,
  57                                            const wxString& text,
  58                                            wxMenu *submenu,
  59                                            const wxString& help = wxPyEmptyString));
  60
  61     wxMenuItem* AppendSubMenu(wxMenu *submenu,
  62                               const wxString& text,
  63                               const wxString& help = wxPyEmptyString);
  64
  65     %disownarg(wxMenuItem*);
  66     // the most generic form of Append() - append anything
  67     %Rename(AppendItem, wxMenuItem*, Append(wxMenuItem *item));
  68     // insert an item before given position
  69     %Rename(InsertItem, wxMenuItem*, Insert(size_t pos, wxMenuItem *item));
  70     // prepend an item to the menu
  71     %Rename(PrependItem,  wxMenuItem*, Prepend(wxMenuItem *item));
  72     %cleardisown(wxMenuItem*);
  73
  74
  75     // insert a break in the menu (only works when appending the items, not
  76     // inserting them)
  77     virtual void Break();
  78
  79     // insert an item before given position
  80     wxMenuItem* Insert(size_t pos,
  81                        int id,
  82                        const wxString& text = wxPyEmptyString,
  83                        const wxString& help = wxPyEmptyString,
  84                        wxItemKind kind = wxITEM_NORMAL);
  85
  86     // insert a separator
  87     wxMenuItem* InsertSeparator(size_t pos);
  88
  89     // insert a check item
  90     wxMenuItem* InsertCheckItem(size_t pos,
  91                                 int id,
  92                                 const wxString& text,
  93                                 const wxString& help = wxPyEmptyString);
  94
  95     // insert a radio item
  96     wxMenuItem* InsertRadioItem(size_t pos,
  97                                 int id,
  98                                 const wxString& text,
  99                                 const wxString& help = wxPyEmptyString);
 100
 101     // insert a submenu
 102     %Rename(InsertMenu, wxMenuItem*, Insert(size_t pos,
 103                                          int id,
 104                                          const wxString& text,
 105                                          wxMenu *submenu,
 106                                          const wxString& help = wxPyEmptyString));
 107
 108     // prepend any item to the menu
 109     wxMenuItem* Prepend(int id,
 110                         const wxString& text = wxPyEmptyString,
 111                         const wxString& help = wxPyEmptyString,
 112                         wxItemKind kind = wxITEM_NORMAL);
 113
 114     // prepend a separator
 115     wxMenuItem*  PrependSeparator();
 116
 117     // prepend a check item
 118     wxMenuItem* PrependCheckItem(int id,
 119                                  const wxString& text,
 120                                  const wxString& help = wxPyEmptyString);
 121
 122     // prepend a radio item
 123     wxMenuItem*  PrependRadioItem(int id,
 124                                   const wxString& text,
 125                                   const wxString& help = wxPyEmptyString);
 126
 127     // prepend a submenu
 128     %Rename(PrependMenu,  wxMenuItem*, Prepend(int id,
 129                                            const wxString& text,
 130                                            wxMenu *submenu,
 131                                            const wxString& help = wxPyEmptyString));
 132
 133
 134     // detach an item from the menu, but don't delete it so that it can be
 135     // added back later (but if it's not, the caller is responsible for
 136     // deleting it!)
 137     %newobject Remove;
 138     wxMenuItem *Remove(int id);
 139
 140     %feature("shadow") Remove(wxMenuItem *item) %{
 141         def RemoveItem(self, item):
 142             """RemoveItem(self, MenuItem item) -> MenuItem"""
 143             #// The return object is always the parameter, so return that
 144             #// proxy instead of the new one
 145             val = _core_.Menu_RemoveItem(self, item)
 146             item.this.own(val.this.own())
 147             val.this.disown()
 148             return item
 149     %}
 150     %Rename(RemoveItem,  wxMenuItem*, Remove(wxMenuItem *item));
 151
 152     // delete an item from the menu (submenus are not destroyed by this
 153     // function, see Destroy)
 154     bool Delete(int id);
 155     %Rename(DeleteItem,  bool, Delete(wxMenuItem *item));
 156
 157     %pythonPrepend Destroy "args[0].this.own(False)"
 158     %extend { void Destroy() { delete self; } }
 159
 160     // delete the item from menu and destroy it (if it's a submenu)
 161     %pythonPrepend Destroy "";
 162     DocDeclStrName(
 163         bool , Destroy(int id),
 164         "", "",
 165         DestroyId);
 166
 167     DocDeclStrName(
 168         bool , Destroy(wxMenuItem *item),
 169         "", "",
 170         DestroyItem);
 171
 172
 173     // get the items
 174     size_t GetMenuItemCount() const;
 175     wxMenuItemList& GetMenuItems();
 176
 177     // search
 178     int FindItem(const wxString& item) const;
 179     %Rename(FindItemById, wxMenuItem*, FindItem(int id /*, wxMenu **menu = NULL*/) const);
 180
 181     // find by position
 182     wxMenuItem* FindItemByPosition(size_t position) const;
 183
 184     // get/set items attributes
 185     void Enable(int id, bool enable);
 186     bool IsEnabled(int id) const;
 187
 188     void Check(int id, bool check);
 189     bool IsChecked(int id) const;
 190
 191     void SetLabel(int id, const wxString& label);
 192     wxString GetLabel(int id) const;
 193
 194     virtual void SetHelpString(int id, const wxString& helpString);
 195     virtual wxString GetHelpString(int id) const;
 196
 197
 198     // the title
 199     virtual void SetTitle(const wxString& title);
 200     const wxString GetTitle() const;
 201
 202     // event handler
 203     void SetEventHandler(wxEvtHandler *handler);
 204     wxEvtHandler *GetEventHandler() const;
 205
 206     // invoking window
 207     void SetInvokingWindow(wxWindow *win);
 208     wxWindow *GetInvokingWindow() const;
 209
 210     // style
 211     long GetStyle() const { return m_style; }
 212
 213
 214     // Updates the UI for a menu and all submenus recursively. source is the
 215     // object that has the update event handlers defined for it. If NULL, the
 216     // menu or associated window will be used.
 217     void UpdateUI(wxEvtHandler* source = NULL);
 218
 219     // get the menu bar this menu is attached to (may be NULL, always NULL for
 220     // popup menus)
 221     wxMenuBar *GetMenuBar() const;
 222
 223 // TODO:  Should these be exposed?
 224     // called when the menu is attached/detached to/from a menu bar
 225     virtual void Attach(wxMenuBarBase *menubar);
 226     virtual void Detach();
 227
 228     // is the menu attached to a menu bar (or is it a popup one)?
 229     bool IsAttached() const;
 230
 231     // set/get the parent of this menu
 232     void SetParent(wxMenu *parent);
 233     wxMenu *GetParent() const;
 234
 235     %property(EventHandler, GetEventHandler, SetEventHandler, doc="See `GetEventHandler` and `SetEventHandler`");
 236     %property(HelpString, GetHelpString, SetHelpString, doc="See `GetHelpString` and `SetHelpString`");
 237     %property(InvokingWindow, GetInvokingWindow, SetInvokingWindow, doc="See `GetInvokingWindow` and `SetInvokingWindow`");
 238     %property(MenuBar, GetMenuBar, doc="See `GetMenuBar`");
 239     %property(MenuItemCount, GetMenuItemCount, doc="See `GetMenuItemCount`");
 240     %property(MenuItems, GetMenuItems, doc="See `GetMenuItems`");
 241     %property(Parent, GetParent, SetParent, doc="See `GetParent` and `SetParent`");
 242     %property(Style, GetStyle, doc="See `GetStyle`");
 243     %property(Title, GetTitle, SetTitle, doc="See `GetTitle` and `SetTitle`");
 244
 245 };
 246
 247 //---------------------------------------------------------------------------
 248 %newgroup
 249
 250 MustHaveApp(wxMenuBar);
 251
 252 class wxMenuBar : public wxWindow
 253 {
 254 public:
 255     %pythonAppend wxMenuBar         "self._setOORInfo(self)"
 256     %typemap(out) wxMenuBar*;    // turn off this typemap
 257
 258     wxMenuBar(long style = 0);
 259
 260     // Turn it back on again
 261     %typemap(out) wxMenuBar* { $result = wxPyMake_wxObject($1, $owner); }
 262
 263     // append a menu to the end of menubar, return True if ok
 264     virtual bool Append(wxMenu *menu, const wxString& title);
 265
 266     // insert a menu before the given position into the menubar, return True
 267     // if inserted ok
 268     virtual bool Insert(size_t pos, wxMenu *menu, const wxString& title);
 269
 270
 271     // get the number of menus in the menu bar
 272     size_t GetMenuCount() const;
 273
 274     // get the menu at given position
 275     wxMenu *GetMenu(size_t pos) const;
 276
 277     // replace the menu at given position with another one, returns the
 278     // previous menu (which should be deleted by the caller)
 279     virtual wxMenu *Replace(size_t pos, wxMenu *menu, const wxString& title);
 280
 281     // delete the menu at given position from the menu bar, return the pointer
 282     // to the menu (which should be  deleted by the caller)
 283     virtual wxMenu *Remove(size_t pos);
 284
 285     // enable or disable a submenu
 286     virtual void EnableTop(size_t pos, bool enable);
 287
 288     // is the menu enabled?
 289     virtual bool IsEnabledTop(size_t pos) const;
 290
 291     // get or change the label of the menu at given position
 292     virtual void SetLabelTop(size_t pos, const wxString& label);
 293     virtual wxString GetLabelTop(size_t pos) const;
 294
 295
 296     // by menu and item names, returns wxNOT_FOUND if not found or id of the
 297     // found item
 298     virtual int FindMenuItem(const wxString& menu, const wxString& item) const;
 299
 300     // find item by id (in any menu), returns NULL if not found
 301     //
 302     // if menu is !NULL, it will be filled with wxMenu this item belongs to
 303     %Rename(FindItemById, virtual wxMenuItem*, FindItem(int id /*, wxMenu **menu = NULL*/) const);
 304
 305     // find menu by its caption, return wxNOT_FOUND on failure
 306     int FindMenu(const wxString& title);
 307
 308
 309     // all these functions just use FindItem() and then call an appropriate
 310     // method on it
 311     //
 312     // NB: under MSW, these methods can only be used after the menubar had
 313     //     been attached to the frame
 314
 315     void Enable(int id, bool enable);
 316     void Check(int id, bool check);
 317     bool IsChecked(int id) const;
 318     bool IsEnabled(int id) const;
 319     // TODO: bool IsEnabled() const;
 320
 321     void SetLabel(int id, const wxString &label);
 322     wxString GetLabel(int id) const;
 323
 324     void SetHelpString(int id, const wxString& helpString);
 325     wxString GetHelpString(int id) const;
 326
 327
 328     // get the frame we are attached to (may return NULL)
 329     wxFrame *GetFrame() const;
 330
 331     // returns True if we're attached to a frame
 332     bool IsAttached() const;
 333
 334     // associate the menubar with the frame
 335     virtual void Attach(wxFrame *frame);
 336
 337     // called before deleting the menubar normally
 338     virtual void Detach();
 339
 340     // update all menu item states in all menus
 341     virtual void UpdateMenus();
 342
 343 #ifdef __WXMAC__
 344     static void SetAutoWindowMenu( bool enable );
 345     static bool GetAutoWindowMenu();
 346 #else
 347     %extend {
 348         static void SetAutoWindowMenu( bool enable ) {}
 349         static bool GetAutoWindowMenu() { return false; }
 350     }
 351 #endif
 352
 353     %pythoncode {
 354         def GetMenus(self):
 355             """Return a list of (menu, label) items for the menus in the MenuBar. """
 356             return [(self.GetMenu(i), self.GetLabelTop(i))
 357                     for i in range(self.GetMenuCount())]
 358
 359         def SetMenus(self, items):
 360             """Clear and add new menus to the MenuBar from a list of (menu, label) items. """
 361             for i in range(self.GetMenuCount()-1, -1, -1):
 362                 self.Remove(i)
 363             for m, l in items:
 364                 self.Append(m, l)
 365     }
 366
 367     %property(Frame, GetFrame, doc="See `GetFrame`");
 368     %property(MenuCount, GetMenuCount, doc="See `GetMenuCount`");
 369     %property(Menus, GetMenus, SetMenus, doc="See `GetMenus` and `SetMenus`");
 370 };
 371
 372 //---------------------------------------------------------------------------
 373 %newgroup
 374
 375 class wxMenuItem : public wxObject {
 376 public:
 377     // turn off this typemap
 378     %typemap(out) wxMenuItem*;
 379
 380     wxMenuItem(wxMenu* parentMenu=NULL, int id=wxID_SEPARATOR,
 381                const wxString& text = wxPyEmptyString,
 382                const wxString& help = wxPyEmptyString,
 383                wxItemKind kind = wxITEM_NORMAL,
 384                wxMenu* subMenu = NULL);
 385     ~wxMenuItem();
 386
 387     // Turn it back on again
 388     %typemap(out) wxMenuItem* { $result = wxPyMake_wxObject($1, $owner); }
 389
 390     // Make Destroy a NOP.  The destruction will be handled by SWIG.
 391     %pythoncode { def Destroy(self): pass }
 392
 393
 394     // the menu we're in
 395     wxMenu *GetMenu() const;
 396     void SetMenu(wxMenu* menu);
 397
 398     // get/set id
 399     void SetId(int id);
 400     int  GetId() const;
 401     bool IsSeparator() const;
 402
 403     // the item's text (or name)
 404     //
 405     // NB: the item's text includes the accelerators and mnemonics info (if
 406     //     any), i.e. it may contain '&' or '_' or "\t..." and thus is
 407     //     different from the item's label which only contains the text shown
 408     //     in the menu
 409     virtual void SetText(const wxString& str);
 410     wxString GetLabel() const;
 411     const wxString& GetText() const;
 412
 413     // get the label from text
 414     static wxString GetLabelFromText(const wxString& text);
 415
 416     // what kind of menu item we are
 417     wxItemKind GetKind() const;
 418     void SetKind(wxItemKind kind);
 419
 420     virtual void SetCheckable(bool checkable);
 421     bool IsCheckable() const;
 422
 423     bool IsSubMenu() const;
 424     void SetSubMenu(wxMenu *menu);
 425     wxMenu *GetSubMenu() const;
 426
 427     // state
 428     virtual void Enable(bool enable = true);
 429     virtual bool IsEnabled() const;
 430
 431     virtual void Check(bool check = true);
 432     virtual bool IsChecked() const;
 433     void Toggle();
 434
 435     // help string (displayed in the status bar by default)
 436     void SetHelp(const wxString& str);
 437     const wxString& GetHelp() const;
 438
 439     // get our accelerator or NULL (caller must delete the pointer)
 440     virtual wxAcceleratorEntry *GetAccel() const;
 441
 442     // set the accel for this item - this may also be done indirectly with
 443     // SetText()
 444     virtual void SetAccel(wxAcceleratorEntry *accel);
 445
 446     void SetBitmap(const wxBitmap& bitmap);
 447     const wxBitmap& GetBitmap();
 448
 449     // wxOwnerDrawn methods
 450 #ifdef __WXMSW__
 451     void SetFont(const wxFont& font);
 452     wxFont GetFont();
 453     void SetTextColour(const wxColour& colText);
 454     wxColour GetTextColour();
 455     void SetBackgroundColour(const wxColour& colBack);
 456     wxColour GetBackgroundColour();
 457     void SetBitmaps(const wxBitmap& bmpChecked,
 458                     const wxBitmap& bmpUnchecked = wxNullBitmap);
 459
 460     void SetDisabledBitmap( const wxBitmap& bmpDisabled );
 461     const wxBitmap& GetDisabledBitmap() const;
 462
 463     void SetMarginWidth(int nWidth);
 464     int GetMarginWidth();
 465     static int GetDefaultMarginWidth();
 466     bool IsOwnerDrawn();
 467
 468     // switch on/off owner-drawing the item
 469     void SetOwnerDrawn(bool ownerDrawn = true);
 470     void ResetOwnerDrawn();
 471 #else
 472     %extend {
 473         void SetFont(const wxFont& font) {}
 474         wxFont GetFont() { return wxNullFont; }
 475         void SetTextColour(const wxColour& colText) {}
 476         wxColour GetTextColour() { return wxNullColour; }
 477         void SetBackgroundColour(const wxColour& colBack) {}
 478         wxColour GetBackgroundColour() { return wxNullColour; }
 479
 480         void SetBitmaps(const wxBitmap& bmpChecked,
 481                         const wxBitmap& bmpUnchecked = wxNullBitmap)
 482             { self->SetBitmap( bmpChecked ); }
 483
 484         void SetDisabledBitmap( const wxBitmap& bmpDisabled ) {}
 485         const wxBitmap& GetDisabledBitmap() const { return wxNullBitmap; }
 486
 487         void SetMarginWidth(int nWidth) {}
 488         int GetMarginWidth() { return 0; }
 489         static int GetDefaultMarginWidth() { return 0; }
 490         bool IsOwnerDrawn() { return false; }
 491         void SetOwnerDrawn(bool ownerDrawn = true) {}
 492         void ResetOwnerDrawn() {}
 493     }
 494 #endif
 495
 496     %property(Accel, GetAccel, SetAccel, doc="See `GetAccel` and `SetAccel`");
 497     %property(BackgroundColour, GetBackgroundColour, SetBackgroundColour, doc="See `GetBackgroundColour` and `SetBackgroundColour`");
 498     %property(Bitmap, GetBitmap, SetBitmap, doc="See `GetBitmap` and `SetBitmap`");
 499     %property(DisabledBitmap, GetDisabledBitmap, SetDisabledBitmap, doc="See `GetDisabledBitmap` and `SetDisabledBitmap`");
 500     %property(Font, GetFont, SetFont, doc="See `GetFont` and `SetFont`");
 501     %property(Help, GetHelp, SetHelp, doc="See `GetHelp` and `SetHelp`");
 502     %property(Id, GetId, SetId, doc="See `GetId` and `SetId`");
 503     %property(Kind, GetKind, SetKind, doc="See `GetKind` and `SetKind`");
 504     %property(Label, GetLabel, doc="See `GetLabel`");
 505     %property(MarginWidth, GetMarginWidth, SetMarginWidth, doc="See `GetMarginWidth` and `SetMarginWidth`");
 506     %property(Menu, GetMenu, SetMenu, doc="See `GetMenu` and `SetMenu`");
 507     %property(SubMenu, GetSubMenu, SetSubMenu, doc="See `GetSubMenu` and `SetSubMenu`");
 508     %property(Text, GetText, SetText, doc="See `GetText` and `SetText`");
 509     %property(TextColour, GetTextColour, SetTextColour, doc="See `GetTextColour` and `SetTextColour`");
 510
 511 };
 512
 513 //---------------------------------------------------------------------------
 514 //---------------------------------------------------------------------------