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