Navigation

Phoenix Logo

phoenix_title wx.lib.agw.aui.framemanager

Description

framemanager.py is the central module of the AUI class framework.

AuiManager manages the panes associated with it for a particular wx.Frame, using a pane’s AuiPaneInfo information to determine each pane’s docking and floating behavior. AuiManager uses wxPython’ sizer mechanism to plan the layout of each frame. It uses a replaceable dock art class to do all drawing, so all drawing is localized in one area, and may be customized depending on an application’s specific needs.

AuiManager works as follows: the programmer adds panes to the class, or makes changes to existing pane properties (dock position, floating state, show state, etc...). To apply these changes, AuiManager’s AuiManager.Update() function is called. This batch processing can be used to avoid flicker, by modifying more than one pane at a time, and then “committing” all of the changes at once by calling Update().

Panes can be added quite easily:

text1 = wx.TextCtrl(self, -1)
text2 = wx.TextCtrl(self, -1)
self._mgr.AddPane(text1, AuiPaneInfo().Left().Caption("Pane Number One"))
self._mgr.AddPane(text2, AuiPaneInfo().Bottom().Caption("Pane Number Two"))

self._mgr.Update()

Later on, the positions can be modified easily. The following will float an existing pane in a tool window:

self._mgr.GetPane(text1).Float()

Layers, Rows and Directions, Positions

Inside AUI, the docking layout is figured out by checking several pane parameters. Four of these are important for determining where a pane will end up.

Direction - Each docked pane has a direction, Top, Bottom, Left, Right, or Center. This is fairly self-explanatory. The pane will be placed in the location specified by this variable.

Position - More than one pane can be placed inside of a “dock”. Imagine two panes being docked on the left side of a window. One pane can be placed over another. In proportionally managed docks, the pane position indicates it’s sequential position, starting with zero. So, in our scenario with two panes docked on the left side, the top pane in the dock would have position 0, and the second one would occupy position 1.

Row - A row can allow for two docks to be placed next to each other. One of the most common places for this to happen is in the toolbar. Multiple toolbar rows are allowed, the first row being in row 0, and the second in row 1. Rows can also be used on vertically docked panes.

Layer - A layer is akin to an onion. Layer 0 is the very center of the managed pane. Thus, if a pane is in layer 0, it will be closest to the center window (also sometimes known as the “content window”). Increasing layers “swallow up” all layers of a lower value. This can look very similar to multiple rows, but is different because all panes in a lower level yield to panes in higher levels. The best way to understand layers is by running the AUI sample (AUI.py).

function_summary Functions Summary

AuiManager_HasLiveResize Static function which returns if the input manager should have “live resize”
AuiManager_UseNativeMiniframes Static function which returns if the input manager should use native MiniFrame as
CheckEdgeDrop Checks on which edge of a window the drop action has taken place.
CheckOutOfWindow Checks if a point is outside the window rectangle.
CopyDocksAndPanes This utility function creates shallow copies of
CopyDocksAndPanes2 This utility function creates full copies of
DoInsertDockLayer This is an internal function that inserts a new dock
DoInsertDockRow This is an internal function that inserts a new dock
DoInsertPane This is an internal function that inserts a new pane
DrawResizeHint Draws a resize hint while a sash is dragged.
EscapeDelimiters Changes ; into \ and | into \| in the input string.
FindDocks This is an internal function that returns a list of docks which meet
FindOppositeDocks This is an internal function that returns a list of docks
FindPaneInDock This method looks up a specified window pointer inside a dock.
GetInternalFrameRect Returns the window rectangle excluding toolbars.
GetManager This function will return the aui manager for a given window.
GetMaxLayer This is an internal function which returns
GetMaxRow This is an internal function which returns
GetNotebookRoot Returns the AuiNotebook which has the specified notebook_id.
GetToolBarDockOffsets Returns the toolbar dock offsets (top-left and bottom-right).
IsDifferentDockingPosition Returns whether pane1 and pane2 are in a different docking position
PaneSortFunc This function is used to sort panes by dock position.
RefreshDockingGuides Refreshes the docking guide windows.
RemovePaneFromDocks Removes a pane window from all docks
RenumberDockRows Takes a dock and assigns sequential numbers
SetActivePane Sets the active pane, as well as cycles through
ShowDockingGuides Shows or hide the docking guide windows.

class_summary Classes Summary

AuiCenterDockingGuide A docking guide window for multiple docking hint (diamond-shaped HUD).
AuiDockInfo A class to store all properties of a dock.
AuiDockingGuide Base class for AuiSingleDockingGuide and AuiCenterDockingGuide.
AuiDockingGuideInfo A class which holds information about VS2005 docking guide windows.
AuiDockingGuideWindow Target class for AuiDockingGuide and AuiCenterDockingGuide.
AuiDockingHintWindow The original wxAUI docking window hint.
AuiDockUIPart A class which holds attributes for a UI part in the interface.
AuiFloatingFrame AuiFloatingFrame is the frame class that holds floating panes.
AuiManager AuiManager manages the panes associated with it for a particular wx.Frame,
AuiManager_DCP A class similar to AuiManager but with a Dummy Center Pane (DCP).
AuiManagerEvent A specialized command event class for events sent by AuiManager.
AuiPaneButton A simple class which describes the caption pane button attributes.
AuiPaneInfo AuiPaneInfo specifies all the parameters for a pane. These parameters specify where
AuiSingleDockingGuide A docking guide window for single docking hint (not diamond-shaped HUD).

Functions


AuiManager_HasLiveResize(manager)

Static function which returns if the input manager should have “live resize” behaviour.

Parameters:manager – an instance of AuiManager.

Note

This method always returns True on wxMAC as this platform doesn’t have the ability to use ScreenDC to draw sashes.


AuiManager_UseNativeMiniframes(manager)

Static function which returns if the input manager should use native MiniFrame as floating panes.

Parameters:manager – an instance of AuiManager.

Note

This method always returns True on wxMAC as this platform doesn’t have the ability to use custom drawn miniframes.


CheckEdgeDrop(window, docks, pt)

Checks on which edge of a window the drop action has taken place.

Parameters:

CheckOutOfWindow(window, pt)

Checks if a point is outside the window rectangle.

Parameters:

CopyDocksAndPanes(src_docks, src_panes)

This utility function creates shallow copies of the dock and pane info. AuiManager usually contain pointers to AuiPaneInfo classes, thus this function is necessary to reliably reconstruct that relationship in the new dock info and pane info arrays.

Parameters:

CopyDocksAndPanes2(src_docks, src_panes)

This utility function creates full copies of the dock and pane info. AuiManager usually contain pointers to AuiPaneInfo classes, thus this function is necessary to reliably reconstruct that relationship in the new dock info and pane info arrays.

Parameters:

DoInsertDockLayer(panes, dock_direction, dock_layer)

This is an internal function that inserts a new dock layer by incrementing all existing dock layer values by one.

Parameters:
  • panes – a list of AuiPaneInfo;
  • dock_direction (integer) – the AuiDockInfo docking direction to analyze;
  • dock_layer (integer) – the AuiDockInfo layer to analyze.

DoInsertDockRow(panes, dock_direction, dock_layer, dock_row)

This is an internal function that inserts a new dock row by incrementing all existing dock row values by one.

Parameters:
  • panes – a list of AuiPaneInfo;
  • dock_direction (integer) – the AuiDockInfo docking direction to analyze;
  • dock_layer (integer) – the AuiDockInfo layer to analyze;
  • dock_row (integer) – the AuiDockInfo row to analyze.

DoInsertPane(panes, dock_direction, dock_layer, dock_row, dock_pos)

This is an internal function that inserts a new pane by incrementing all existing dock position values by one.

Parameters:
  • panes – a list of AuiPaneInfo;
  • dock_direction (integer) – the AuiDockInfo docking direction to analyze;
  • dock_layer (integer) – the AuiDockInfo layer to analyze.
  • dock_row (integer) – the AuiDockInfo row to analyze;
  • dock_pos (integer) – the AuiDockInfo position to analyze.

DrawResizeHint(dc, rect)

Draws a resize hint while a sash is dragged.

Parameters:rect (wx.Rect) – a rectangle which specifies the sash dimensions.

EscapeDelimiters(s)

Changes ; into \ and | into \| in the input string.

Parameters:s (string) – the string to be analyzed.

Note

This is an internal functions which is used for saving perspectives.


FindDocks(docks, dock_direction, dock_layer=-1, dock_row=-1, reverse=False)

This is an internal function that returns a list of docks which meet the specified conditions in the parameters and returns a sorted array (sorted by layer and then row).

Parameters:
  • docks – a list of AuiDockInfo;
  • dock_direction (integer) – the AuiDockInfo docking direction to analyze;
  • dock_layer (integer) – the AuiDockInfo layer to analyze.
  • dock_row (integer) – the AuiDockInfo row to analyze;

FindOppositeDocks(docks, dock_direction)

This is an internal function that returns a list of docks which is related to the opposite direction.

Parameters:

FindPaneInDock(dock, window)

This method looks up a specified window pointer inside a dock. If found, the corresponding AuiDockInfo pointer is returned, otherwise None.

Parameters:
  • dock – a AuiDockInfo structure;
  • window (wx.Window) – the window associated to the pane we are seeking.

GetInternalFrameRect(window, docks)

Returns the window rectangle excluding toolbars.

Parameters:

GetManager(window)

This function will return the aui manager for a given window.

Parameters:window (wx.Window) – this parameter should be any child window or grand-child window (and so on) of the frame/window managed by AuiManager. The window does not need to be managed by the manager itself, nor does it even need to be a child or sub-child of a managed window. It must however be inside the window hierarchy underneath the managed window.

GetMaxLayer(docks, dock_direction)

This is an internal function which returns the highest layer inside the specified dock.

Parameters:

GetMaxRow(panes, dock_direction, dock_layer)

This is an internal function which returns the highest layer inside the specified dock.

Parameters:
  • panes – a list of AuiPaneInfo;
  • dock_direction (integer) – the AuiDockInfo docking direction to analyze;
  • dock_layer (integer) – the AuiDockInfo layer to analyze.

GetNotebookRoot(panes, notebook_id)

Returns the AuiNotebook which has the specified notebook_id.

Parameters:
  • panes – a list of AuiPaneInfo instances;
  • notebook_id (integer) – the target notebook id.

GetToolBarDockOffsets(docks)

Returns the toolbar dock offsets (top-left and bottom-right).

Parameters:docks – a list of AuiDockInfo to analyze.

IsDifferentDockingPosition(pane1, pane2)

Returns whether pane1 and pane2 are in a different docking position based on pane status, docking direction, docking layer and docking row.

Parameters:

PaneSortFunc(p1, p2)

This function is used to sort panes by dock position.

Parameters:
  • p1 – the first pane instance to compare, an instance of AuiPaneInfo;
  • p2 – the second pane instance to compare, an instance of AuiPaneInfo.

RefreshDockingGuides(guides)

Refreshes the docking guide windows.

Parameters:guides – a list of AuiDockingGuide classes;

RemovePaneFromDocks(docks, pane, exc=None)

Removes a pane window from all docks with a possible exception specified by parameter exc.

Parameters:
  • docks – a list of AuiDockInfo structures;
  • pane – the pane to be removed, an instance of AuiPaneInfo;
  • exc – the possible pane exception, an instance of AuiPaneInfo.

RenumberDockRows(docks)

Takes a dock and assigns sequential numbers to existing rows. Basically it takes out the gaps so if a dock has rows with numbers 0, 2, 5, they will become 0, 1, 2.

Parameters:docks – a list of AuiDockInfo structures.

SetActivePane(panes, active_pane)

Sets the active pane, as well as cycles through every other pane and makes sure that all others’ active flags are turned off.

Parameters:
  • panes – a list of AuiPaneInfo structures;
  • active_pane – the pane to be made active (if found), an instance of AuiPaneInfo.

ShowDockingGuides(guides, show)

Shows or hide the docking guide windows.

Parameters:
  • guides – a list of AuiDockingGuide classes;
  • show (bool) – whether to show or hide the docking guide windows.