1 /////////////////////////////////////////////////////////////////////////////
3 // Purpose: Wrappers for the wxAUI classes.
7 // Created: 5-July-2006
9 // Copyright: (c) 2006 by Total Control Software
10 // Licence: wxWindows license
11 /////////////////////////////////////////////////////////////////////////////
14 "The wx.aui moduleis an Advanced User Interface library that aims to
15 implement \"cutting-edge\" interface usability and design features so
16 developers can quickly and easily create beautiful and usable
17 application interfaces.
19 **Vision and Design Principles**
21 wx.aui attempts to encapsulate the following aspects of the user
24 * Frame Management: Frame management provides the means to open,
25 move and hide common controls that are needed to interact with the
26 document, and allow these configurations to be saved into
27 different perspectives and loaded at a later time.
29 * Toolbars: Toolbars are a specialized subset of the frame
30 management system and should behave similarly to other docked
31 components. However, they also require additional functionality,
32 such as \"spring-loaded\" rebar support, \"chevron\" buttons and
33 end-user customizability.
35 * Modeless Controls: Modeless controls expose a tool palette or set
36 of options that float above the application content while allowing
37 it to be accessed. Usually accessed by the toolbar, these controls
38 disappear when an option is selected, but may also be \"torn off\"
39 the toolbar into a floating frame of their own.
41 * Look and Feel: Look and feel encompasses the way controls are
42 drawn, both when shown statically as well as when they are being
43 moved. This aspect of user interface design incorporates \"special
44 effects\" such as transparent window dragging as well as frame
47 **wx.aui adheres to the following principles**
49 - Use native floating frames to obtain a native look and feel for
52 - Use existing wxPython code where possible, such as sizer
53 implementation for frame management;
55 - Use standard wxPython coding conventions.
60 The following example shows a simple implementation that utilizes
61 `wx.aui.FrameManager` to manage three text controls in a frame window::
66 class MyFrame(wx.Frame):
68 def __init__(self, parent, id=-1, title='wx.aui Test',
69 size=(800, 600), style=wx.DEFAULT_FRAME_STYLE):
70 wx.Frame.__init__(self, parent, id, title, pos, size, style)
72 self._mgr = wx.aui.AuiManager(self)
74 # create several text controls
75 text1 = wx.TextCtrl(self, -1, 'Pane 1 - sample text',
76 wx.DefaultPosition, wx.Size(200,150),
77 wx.NO_BORDER | wx.TE_MULTILINE)
79 text2 = wx.TextCtrl(self, -1, 'Pane 2 - sample text',
80 wx.DefaultPosition, wx.Size(200,150),
81 wx.NO_BORDER | wx.TE_MULTILINE)
83 text3 = wx.TextCtrl(self, -1, 'Main content window',
84 wx.DefaultPosition, wx.Size(200,150),
85 wx.NO_BORDER | wx.TE_MULTILINE)
87 # add the panes to the manager
88 self._mgr.AddPane(text1, wx.LEFT, 'Pane Number One')
89 self._mgr.AddPane(text2, wx.BOTTOM, 'Pane Number Two')
90 self._mgr.AddPane(text3, wx.CENTER)
92 # tell the manager to 'commit' all the changes just made
95 self.Bind(wx.EVT_CLOSE, self.OnClose)
98 def OnClose(self, event):
99 # deinitialize the frame manager
106 frame = MyFrame(None)
114 %module(package="wx", docstring=DOCSTRING) aui
117 #include "wx/wxPython/wxPython.h"
118 #include "wx/wxPython/pyclasses.h"
119 #include <wx/aui/aui.h>
122 //---------------------------------------------------------------------------
127 %pythoncode { wx = _core }
128 %pythoncode { __docfilter__ = wx.__DocFilter(globals()) }
131 %include _aui_docstrings.i
133 //---------------------------------------------------------------------------
137 #define WXDLLIMPEXP_AUI
139 #define wxDEPRECATED(decl)
142 // We'll skip making wrappers for these, they have overloads that take a
144 %ignore wxAuiPaneInfo::MaxSize(int x, int y);
145 %ignore wxAuiPaneInfo::MinSize(int x, int y);
146 %ignore wxAuiPaneInfo::BestSize(int x, int y);
147 %ignore wxAuiPaneInfo::FloatingPosition(int x, int y);
148 %ignore wxAuiPaneInfo::FloatingSize(int x, int y);
150 // But for these we will do the overloading (see %pythoncode below) so let's
151 // rename the C++ versions
152 %rename(_GetPaneByWidget) wxAuiManager::GetPane(wxWindow* window);
153 %rename(_GetPaneByName) wxAuiManager::GetPane(const wxString& name);
155 %rename(_AddPane1) wxAuiManager::AddPane(wxWindow* window, const wxAuiPaneInfo& pane_info);
156 %rename(_AddPane2) wxAuiManager::AddPane(wxWindow* window, int direction = wxLEFT,
157 const wxString& caption = wxEmptyString);
159 %rename(AddPaneAtPos) wxAuiManager::AddPane(wxWindow* window,
160 const wxPaneInfo& pane_info,
161 const wxPoint& drop_pos);
163 // A typemap for the return value of wxFrameManager::GetAllPanes
164 %typemap(out) wxAuiPaneInfoArray& {
165 $result = PyList_New(0);
166 for (size_t i=0; i < $1->GetCount(); i++) {
167 PyObject* pane_obj = SWIG_NewPointerObj((void*)(&$1->Item(i)), SWIGTYPE_p_wxAuiPaneInfo, 0);
168 PyList_Append($result, pane_obj);
173 %nokwargs wxAuiTabContainer::SetActivePage;
175 %pythonAppend wxAuiTabCtrl::wxAuiTabCtrl "self._setOORInfo(self)";
177 %pythonAppend wxAuiNotebook::wxAuiNotebook "self._setOORInfo(self)";
178 %pythonAppend wxAuiNotebook::wxAuiNotebook() "self._setOORInfo(self)";
179 %ignore wxAuiiNotebook::~wxAuiNotebook;
180 %rename(PreAuiNotebook) wxAuiNotebook::wxAuiNotebook();
182 //---------------------------------------------------------------------------
183 // Get all our defs from the REAL header files.
184 %include framemanager.h
189 //---------------------------------------------------------------------------
190 // Methods to inject into the FrameManager class that will sort out calls to
191 // the overloaded versions of GetPane and AddPane
193 %extend wxAuiManager {
195 def GetPane(self, item):
197 GetPane(self, window_or_info item) -> PaneInfo
199 GetPane is used to search for a `PaneInfo` object either by
200 widget reference or by pane name, which acts as a unique id
201 for a window pane. The returned `PaneInfo` object may then be
202 modified to change a pane's look, state or position. After one
203 or more modifications to the `PaneInfo`, `FrameManager.Update`
204 should be called to realize the changes to the user interface.
206 If the lookup failed (meaning the pane could not be found in
207 the manager) GetPane returns an empty `PaneInfo`, a condition
208 which can be checked by calling `PaneInfo.IsOk`.
210 if isinstance(item, wx.Window):
211 return self._GetPaneByWidget(item)
213 return self._GetPaneByName(item)
215 def AddPane(self, window, info=None, caption=None):
217 AddPane(self, window, info=None, caption=None) -> bool
219 AddPane tells the frame manager to start managing a child
220 window. There are two versions of this function. The first
221 verison accepts a `PaneInfo` object for the ``info`` parameter
222 and allows the full spectrum of pane parameter
223 possibilities. (Say that 3 times fast!)
225 The second version is used for simpler user interfaces which
226 do not require as much configuration. In this case the
227 ``info`` parameter specifies the direction property of the
228 pane info, and defaults to ``wx.LEFT``. The pane caption may
229 also be specified as an extra parameter in this form.
231 if type(info) == AuiPaneInfo:
232 return self._AddPane1(window, info)
239 return self._AddPane2(window, info, caption)
242 // For backwards compatibility
244 SetFrame = wx._deprecated(SetManagedWindow,
245 "SetFrame is deprecated, use `SetManagedWindow` instead.")
246 GetFrame = wx._deprecated(GetManagedWindow,
247 "GetFrame is deprecated, use `GetManagedWindow` instead.")
251 %extend wxAuiDockInfo {
255 %extend wxAuiDockUIPart {
256 ~wxAuiDockUIPart() {}
259 %extend wxAuiPaneButton {
260 ~wxAuiPaneButton() {}
263 //---------------------------------------------------------------------------
266 // A wxDocArt class that knows how to forward virtuals to Python methods
267 class wxPyAuiDockArt : public wxAuiDefaultDockArt
269 wxPyAuiDockArt() : wxAuiDefaultDockArt() {}
271 DEC_PYCALLBACK_INT_INT(GetMetric);
272 DEC_PYCALLBACK_VOID_INTINT(SetMetric);
273 DEC_PYCALLBACK__INTFONT(SetFont);
274 DEC_PYCALLBACK_FONT_INT(GetFont);
275 DEC_PYCALLBACK_COLOUR_INT(GetColour);
276 DEC_PYCALLBACK__INTCOLOUR(SetColour);
278 virtual void DrawSash(wxDC& dc,
284 wxPyBlock_t blocked = wxPyBeginBlockThreads();
285 if ((found = wxPyCBH_findCallback(m_myInst, "DrawSash"))) {
286 PyObject* odc = wxPyMake_wxObject(&dc, false);
287 PyObject* owin = wxPyMake_wxObject(window, false);
288 PyObject* orect = wxPyConstructObject((void*)&rect, wxT("wxRect"), 0);
289 wxPyCBH_callCallback(m_myInst, Py_BuildValue("(OOiO)",
290 odc, owin, orientation, orect));
295 wxPyEndBlockThreads(blocked);
297 wxAuiDefaultDockArt::DrawSash(dc, window, orientation, rect);
300 virtual void DrawBackground(wxDC& dc,
306 wxPyBlock_t blocked = wxPyBeginBlockThreads();
307 if ((found = wxPyCBH_findCallback(m_myInst, "DrawBackground"))) {
308 PyObject* odc = wxPyMake_wxObject(&dc, false);
309 PyObject* owin = wxPyMake_wxObject(window, false);
310 PyObject* orect = wxPyConstructObject((void*)&rect, wxT("wxRect"), 0);
311 wxPyCBH_callCallback(m_myInst, Py_BuildValue("(OOiO)",
312 odc, owin, orientation, orect));
317 wxPyEndBlockThreads(blocked);
319 wxAuiDefaultDockArt::DrawBackground(dc, window, orientation, rect);
322 virtual void DrawCaption(wxDC& dc,
324 const wxString& text,
329 wxPyBlock_t blocked = wxPyBeginBlockThreads();
330 if ((found = wxPyCBH_findCallback(m_myInst, "DrawCaption"))) {
331 PyObject* odc = wxPyMake_wxObject(&dc, false);
332 PyObject* owin = wxPyMake_wxObject(window, false);
333 PyObject* otext = wx2PyString(text);
334 PyObject* orect = wxPyConstructObject((void*)&rect, wxT("wxRect"), 0);
335 PyObject* opane = wxPyConstructObject((void*)&pane, wxT("wxAuiPaneInfo"), 0);
336 wxPyCBH_callCallback(m_myInst, Py_BuildValue("(OOOOO)",
337 odc, owin, otext, orect, opane));
344 wxPyEndBlockThreads(blocked);
346 wxAuiDefaultDockArt::DrawCaption(dc, window, text, rect, pane);
349 virtual void DrawGripper(wxDC& dc,
355 wxPyBlock_t blocked = wxPyBeginBlockThreads();
356 if ((found = wxPyCBH_findCallback(m_myInst, "DrawGripper"))) {
357 PyObject* odc = wxPyMake_wxObject(&dc, false);
358 PyObject* owin = wxPyMake_wxObject(window, false);
359 PyObject* orect = wxPyConstructObject((void*)&rect, wxT("wxRect"), 0);
360 PyObject* opane = wxPyConstructObject((void*)&pane, wxT("wxAuiPaneInfo"), 0);
361 wxPyCBH_callCallback(m_myInst, Py_BuildValue("(OOOO)", odc, owin, orect, opane));
366 wxPyEndBlockThreads(blocked);
368 wxAuiDefaultDockArt::DrawGripper(dc, window, rect, pane);
371 virtual void DrawBorder(wxDC& dc,
377 wxPyBlock_t blocked = wxPyBeginBlockThreads();
378 if ((found = wxPyCBH_findCallback(m_myInst, "DrawBorder"))) {
379 PyObject* odc = wxPyMake_wxObject(&dc, false);
380 PyObject* owin = wxPyMake_wxObject(window, false);
381 PyObject* orect = wxPyConstructObject((void*)&rect, wxT("wxRect"), 0);
382 PyObject* opane = wxPyConstructObject((void*)&pane, wxT("wxAuiPaneInfo"), 0);
383 wxPyCBH_callCallback(m_myInst, Py_BuildValue("(OOO)", odc, orect, opane));
389 wxPyEndBlockThreads(blocked);
391 wxAuiDefaultDockArt::DrawBorder(dc, window, rect, pane);
394 virtual void DrawPaneButton(wxDC& dc,
402 wxPyBlock_t blocked = wxPyBeginBlockThreads();
403 if ((found = wxPyCBH_findCallback(m_myInst, "DrawPaneButton"))) {
404 PyObject* odc = wxPyMake_wxObject(&dc, false);
405 PyObject* owin = wxPyMake_wxObject(window, false);
406 PyObject* orect = wxPyConstructObject((void*)&rect, wxT("wxRect"), 0);
407 PyObject* opane = wxPyConstructObject((void*)&pane, wxT("wxAuiPaneInfo"), 0);
408 wxPyCBH_callCallback(m_myInst, Py_BuildValue("(OOiIOO)",
409 odc, owin, button, button_state,
416 wxPyEndBlockThreads(blocked);
418 wxAuiDefaultDockArt::DrawPaneButton(dc, window, button, button_state, rect, pane);
425 IMP_PYCALLBACK_INT_INT(wxPyAuiDockArt, wxAuiDefaultDockArt, GetMetric);
426 IMP_PYCALLBACK_VOID_INTINT(wxPyAuiDockArt, wxAuiDefaultDockArt, SetMetric);
427 IMP_PYCALLBACK__INTFONT(wxPyAuiDockArt, wxAuiDefaultDockArt, SetFont);
428 IMP_PYCALLBACK_FONT_INT(wxPyAuiDockArt, wxAuiDefaultDockArt, GetFont);
429 IMP_PYCALLBACK_COLOUR_INT(wxPyAuiDockArt, wxAuiDefaultDockArt, GetColour);
430 IMP_PYCALLBACK__INTCOLOUR(wxPyAuiDockArt, wxAuiDefaultDockArt, SetColour);
435 DocStr(wxPyAuiDockArt,
436 "This version of the `AuiDockArt` class has been instrumented to be
437 subclassable in Python and to reflect all calls to the C++ base class
438 methods to the Python methods implemented in the derived class.", "");
440 class wxPyAuiDockArt : public wxAuiDefaultDockArt
442 %pythonAppend wxPyAuiDockArt "self._setCallbackInfo(self, PyAuiDockArt)"
448 //---------------------------------------------------------------------------
450 %extend wxAuiNotebook {
451 %property(PageCount, GetPageCount, doc="See `GetPageCount`");
452 %property(Selection, GetSelection, SetSelection, doc="See `GetSelection` and `SetSelection`");
456 %extend wxAuiNotebookEvent {
457 %property(OldSelection, GetOldSelection, SetOldSelection, doc="See `GetOldSelection` and `SetOldSelection`");
458 %property(Selection, GetSelection, SetSelection, doc="See `GetSelection` and `SetSelection`");
462 %extend wxAuiTabContainer {
463 %property(ActivePage, GetActivePage, SetActivePage, doc="See `GetActivePage` and `SetActivePage`");
464 %property(PageCount, GetPageCount, doc="See `GetPageCount`");
465 %property(Pages, GetPages, doc="See `GetPages`");
469 %extend wxAuiManager {
470 %property(AllPanes, GetAllPanes, doc="See `GetAllPanes`");
471 %property(ArtProvider, GetArtProvider, SetArtProvider, doc="See `GetArtProvider` and `SetArtProvider`");
472 %property(Flags, GetFlags, SetFlags, doc="See `GetFlags` and `SetFlags`");
473 %property(ManagedWindow, GetManagedWindow, SetManagedWindow, doc="See `GetManagedWindow` and `SetManagedWindow`");
477 %extend wxAuiManagerEvent {
478 %property(Button, GetButton, SetButton, doc="See `GetButton` and `SetButton`");
479 %property(DC, GetDC, SetDC, doc="See `GetDC` and `SetDC`");
480 %property(Pane, GetPane, SetPane, doc="See `GetPane` and `SetPane`");
484 //---------------------------------------------------------------------------
487 // A wxTabArt class that knows how to forward virtuals to Python methods
488 class wxPyAuiTabArt : public wxAuiDefaultTabArt
490 wxPyAuiTabArt() : wxAuiDefaultTabArt() {}
493 virtual void DrawBackground( wxDC* dc,
497 wxPyBlock_t blocked = wxPyBeginBlockThreads();
498 if ((found = wxPyCBH_findCallback(m_myInst, "DrawBackground"))) {
499 PyObject* odc = wxPyMake_wxObject(dc, false);
500 PyObject* orect = wxPyConstructObject((void*)&rect, wxT("wxRect"), 0);
501 wxPyCBH_callCallback(m_myInst, Py_BuildValue("(OO)", odc, orect));
505 wxPyEndBlockThreads(blocked);
507 wxAuiDefaultTabArt::DrawBackground(dc, rect);
510 virtual void DrawTab( wxDC* dc,
511 const wxRect& in_rect,
512 const wxString& caption,
514 bool with_close_button,
519 const char* errmsg = "DrawTab should return a sequence containing (out_rect, x_extent)";
520 wxPyBlock_t blocked = wxPyBeginBlockThreads();
521 if ((found = wxPyCBH_findCallback(m_myInst, "DrawTab"))) {
522 PyObject* odc = wxPyMake_wxObject(dc, false);
523 PyObject* orect = wxPyConstructObject((void*)&in_rect, wxT("wxRect"), 0);
524 PyObject* otext = wx2PyString(caption);
526 ro = wxPyCBH_callCallbackObj(m_myInst, Py_BuildValue(
529 (int)active, (int)with_close_button));
531 if (PySequence_Check(ro) && PyObject_Length(ro) == 2) {
532 PyObject* o1 = PySequence_GetItem(ro, 0);
533 PyObject* o2 = PySequence_GetItem(ro, 1);
534 if (!wxRect_helper(o1, &out_rect))
535 PyErr_SetString(PyExc_TypeError, errmsg);
536 else if (!PyInt_Check(o2))
537 PyErr_SetString(PyExc_TypeError, errmsg);
539 *x_extent = PyInt_AsLong(o2);
545 PyErr_SetString(PyExc_TypeError, errmsg);
554 wxPyEndBlockThreads(blocked);
556 wxAuiDefaultTabArt::DrawTab(dc, in_rect, caption, active, with_close_button, out_rect, x_extent);
560 virtual void DrawButton( wxDC* dc,
561 const wxRect& in_rect,
565 const wxBitmap& bitmap_override,
569 const char* errmsg = "DrawButton should return a wxRect";
570 wxPyBlock_t blocked = wxPyBeginBlockThreads();
571 if ((found = wxPyCBH_findCallback(m_myInst, "DrawButton"))) {
572 PyObject* odc = wxPyMake_wxObject(dc, false);
573 PyObject* orect = wxPyConstructObject((void*)&in_rect, wxT("wxRect"), 0);
574 PyObject* obmp = wxPyConstructObject((void*)&bitmap_override, wxT("wxBitmap"), 0);
576 ro = wxPyCBH_callCallbackObj(m_myInst, Py_BuildValue("(OOiiiO)", odc, orect,
577 bitmap_id, button_state, orientation,
580 if (!wxRect_helper(ro, &out_rect))
581 PyErr_SetString(PyExc_TypeError, errmsg);
589 wxPyEndBlockThreads(blocked);
591 wxAuiDefaultTabArt::DrawButton(dc, in_rect, bitmap_id, button_state, orientation, bitmap_override, out_rect);
595 virtual wxSize GetTabSize( wxDC* dc,
596 const wxString& caption,
598 bool with_close_button,
602 wxSize rv, *prv = &rv;
603 const char* errmsg = "GetTabSize should return a sequence containing (size, x_extent)";
604 wxPyBlock_t blocked = wxPyBeginBlockThreads();
605 if ((found = wxPyCBH_findCallback(m_myInst, "GetTabSize"))) {
606 PyObject* odc = wxPyMake_wxObject(dc, false);
607 PyObject* otext = wx2PyString(caption);
609 ro = wxPyCBH_callCallbackObj(m_myInst, Py_BuildValue(
610 "(OOi)", odc, otext, (int)active, (int)with_close_button));
612 if (PySequence_Check(ro) && PyObject_Length(ro) == 2) {
613 PyObject* o1 = PySequence_GetItem(ro, 0);
614 PyObject* o2 = PySequence_GetItem(ro, 1);
615 if (!wxSize_helper(o1, &prv))
616 PyErr_SetString(PyExc_TypeError, errmsg);
617 else if (!PyInt_Check(o2))
618 PyErr_SetString(PyExc_TypeError, errmsg);
620 *x_extent = PyInt_AsLong(o2);
626 PyErr_SetString(PyExc_TypeError, errmsg);
634 wxPyEndBlockThreads(blocked);
636 rv = wxAuiDefaultTabArt::GetTabSize(dc, caption, active, with_close_button, x_extent);
642 DEC_PYCALLBACK__FONT(SetNormalFont);
643 DEC_PYCALLBACK__FONT(SetSelectedFont);
644 DEC_PYCALLBACK__FONT(SetMeasuringFont);
645 DEC_PYCALLBACK_INT_WIN(GetBestTabCtrlSize);
651 IMP_PYCALLBACK__FONT(wxPyAuiTabArt, wxAuiDefaultTabArt, SetNormalFont);
652 IMP_PYCALLBACK__FONT(wxPyAuiTabArt, wxAuiDefaultTabArt, SetSelectedFont);
653 IMP_PYCALLBACK__FONT(wxPyAuiTabArt, wxAuiDefaultTabArt, SetMeasuringFont);
654 IMP_PYCALLBACK_INT_WIN(wxPyAuiTabArt, wxAuiDefaultTabArt, GetBestTabCtrlSize);
658 DocStr(wxPyAuiTabArt,
659 "This version of the `TabArt` class has been instrumented to be
660 subclassable in Python and to reflect all calls to the C++ base class
661 methods to the Python methods implemented in the derived class.", "");
663 class wxPyAuiTabArt : public wxAuiDefaultTabArt
665 %pythonAppend wxPyAuiTabArt "self._setCallbackInfo(self, PyAuiTabArt)"
671 //---------------------------------------------------------------------------
674 #undef WXDLLIMPEXP_AUI
676 //---------------------------------------------------------------------------