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 int close_button_state,
515 wxRect* out_tab_rect,
516 wxRect* out_button_rect,
520 const char* errmsg = "DrawTab should return a sequence containing (tab_rect, button_rect, x_extent)";
521 wxPyBlock_t blocked = wxPyBeginBlockThreads();
522 if ((found = wxPyCBH_findCallback(m_myInst, "DrawTab"))) {
523 PyObject* odc = wxPyMake_wxObject(dc, false);
524 PyObject* orect = wxPyConstructObject((void*)&in_rect, wxT("wxRect"), 0);
525 PyObject* otext = wx2PyString(caption);
527 ro = wxPyCBH_callCallbackObj(m_myInst, Py_BuildValue(
530 (int)active, close_button_state));
532 if (PySequence_Check(ro) && PyObject_Length(ro) == 3) {
533 PyObject* o1 = PySequence_GetItem(ro, 0);
534 PyObject* o2 = PySequence_GetItem(ro, 1);
535 PyObject* o3 = PySequence_GetItem(ro, 2);
536 if (!wxRect_helper(o1, &out_tab_rect))
537 PyErr_SetString(PyExc_TypeError, errmsg);
538 else if (!wxRect_helper(o2, &out_button_rect))
539 PyErr_SetString(PyExc_TypeError, errmsg);
540 else if (!PyInt_Check(o3))
541 PyErr_SetString(PyExc_TypeError, errmsg);
543 *x_extent = PyInt_AsLong(o3);
550 PyErr_SetString(PyExc_TypeError, errmsg);
559 wxPyEndBlockThreads(blocked);
561 wxAuiDefaultTabArt::DrawTab(dc, in_rect, caption, active, close_button_state, out_tab_rect, out_button_rect, x_extent);
565 virtual void DrawButton( wxDC* dc,
566 const wxRect& in_rect,
570 const wxBitmap& bitmap_override,
574 const char* errmsg = "DrawButton should return a wxRect";
575 wxPyBlock_t blocked = wxPyBeginBlockThreads();
576 if ((found = wxPyCBH_findCallback(m_myInst, "DrawButton"))) {
577 PyObject* odc = wxPyMake_wxObject(dc, false);
578 PyObject* orect = wxPyConstructObject((void*)&in_rect, wxT("wxRect"), 0);
579 PyObject* obmp = wxPyConstructObject((void*)&bitmap_override, wxT("wxBitmap"), 0);
581 ro = wxPyCBH_callCallbackObj(m_myInst, Py_BuildValue("(OOiiiO)", odc, orect,
582 bitmap_id, button_state, orientation,
585 if (!wxRect_helper(ro, &out_rect))
586 PyErr_SetString(PyExc_TypeError, errmsg);
594 wxPyEndBlockThreads(blocked);
596 wxAuiDefaultTabArt::DrawButton(dc, in_rect, bitmap_id, button_state, orientation, bitmap_override, out_rect);
600 virtual wxSize GetTabSize( wxDC* dc,
601 const wxString& caption,
603 int close_button_state,
607 wxSize rv, *prv = &rv;
608 const char* errmsg = "GetTabSize should return a sequence containing (size, x_extent)";
609 wxPyBlock_t blocked = wxPyBeginBlockThreads();
610 if ((found = wxPyCBH_findCallback(m_myInst, "GetTabSize"))) {
611 PyObject* odc = wxPyMake_wxObject(dc, false);
612 PyObject* otext = wx2PyString(caption);
614 ro = wxPyCBH_callCallbackObj(m_myInst, Py_BuildValue(
615 "(OOi)", odc, otext, (int)active, close_button_state));
617 if (PySequence_Check(ro) && PyObject_Length(ro) == 2) {
618 PyObject* o1 = PySequence_GetItem(ro, 0);
619 PyObject* o2 = PySequence_GetItem(ro, 1);
620 if (!wxSize_helper(o1, &prv))
621 PyErr_SetString(PyExc_TypeError, errmsg);
622 else if (!PyInt_Check(o2))
623 PyErr_SetString(PyExc_TypeError, errmsg);
625 *x_extent = PyInt_AsLong(o2);
631 PyErr_SetString(PyExc_TypeError, errmsg);
639 wxPyEndBlockThreads(blocked);
641 rv = wxAuiDefaultTabArt::GetTabSize(dc, caption, active, close_button_state, x_extent);
647 DEC_PYCALLBACK__FONT(SetNormalFont);
648 DEC_PYCALLBACK__FONT(SetSelectedFont);
649 DEC_PYCALLBACK__FONT(SetMeasuringFont);
650 DEC_PYCALLBACK_INT_WIN(GetBestTabCtrlSize);
656 IMP_PYCALLBACK__FONT(wxPyAuiTabArt, wxAuiDefaultTabArt, SetNormalFont);
657 IMP_PYCALLBACK__FONT(wxPyAuiTabArt, wxAuiDefaultTabArt, SetSelectedFont);
658 IMP_PYCALLBACK__FONT(wxPyAuiTabArt, wxAuiDefaultTabArt, SetMeasuringFont);
659 IMP_PYCALLBACK_INT_WIN(wxPyAuiTabArt, wxAuiDefaultTabArt, GetBestTabCtrlSize);
663 DocStr(wxPyAuiTabArt,
664 "This version of the `TabArt` class has been instrumented to be
665 subclassable in Python and to reflect all calls to the C++ base class
666 methods to the Python methods implemented in the derived class.", "");
668 class wxPyAuiTabArt : public wxAuiDefaultTabArt
670 %pythonAppend wxPyAuiTabArt "self._setCallbackInfo(self, PyAuiTabArt)"
676 //---------------------------------------------------------------------------
679 #undef WXDLLIMPEXP_AUI
681 //---------------------------------------------------------------------------