.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc

.. module:: wx.lib.agw.aui.framemanager

.. currentmodule:: wx.lib.agw.aui.framemanager

.. highlight:: python



.. _wx.lib.agw.aui.framemanager:

==========================================================================================================================================
|phoenix_title|  **wx.lib.agw.aui.framemanager**
==========================================================================================================================================

Description
===========

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

:class:`AuiManager` manages the panes associated with it for a particular :class:`wx.Frame`, using
a pane's :class:`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 :meth:`AuiManager.Update() <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
====================================

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


|


|class_summary| Classes Summary
===============================

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


|


.. toctree::
   :maxdepth: 1
   :hidden:

   wx.lib.agw.aui.framemanager.AuiCenterDockingGuide
   wx.lib.agw.aui.framemanager.AuiDockInfo
   wx.lib.agw.aui.framemanager.AuiDockingGuide
   wx.lib.agw.aui.framemanager.AuiDockingGuideInfo
   wx.lib.agw.aui.framemanager.AuiDockingGuideWindow
   wx.lib.agw.aui.framemanager.AuiDockingHintWindow
   wx.lib.agw.aui.framemanager.AuiDockUIPart
   wx.lib.agw.aui.framemanager.AuiFloatingFrame
   wx.lib.agw.aui.framemanager.AuiManager
   wx.lib.agw.aui.framemanager.AuiManager_DCP
   wx.lib.agw.aui.framemanager.AuiManagerEvent
   wx.lib.agw.aui.framemanager.AuiPaneButton
   wx.lib.agw.aui.framemanager.AuiPaneInfo
   wx.lib.agw.aui.framemanager.AuiSingleDockingGuide





Functions
------------

.. function:: AuiManager_HasLiveResize(manager)

   Static function which returns if the input `manager` should have "live resize"
   behaviour.
   
   :param `manager`: an instance of :class:`AuiManager`.
   
   .. note::
   
      This method always returns ``True`` on wxMAC as this platform doesn't have
      the ability to use :class:`ScreenDC` to draw sashes.


.. function:: AuiManager_UseNativeMiniframes(manager)

   Static function which returns if the input `manager` should use native :class:`MiniFrame` as
   floating panes.
   
   :param `manager`: an instance of :class:`AuiManager`.
   
   .. note::
   
      This method always returns ``True`` on wxMAC as this platform doesn't have
      the ability to use custom drawn miniframes.


.. function:: CheckEdgeDrop(window, docks, pt)

   Checks on which edge of a window the drop action has taken place.
   
   :param `window`: a :class:`wx.Window` derived window;
   :param `docks`: a list of :class:`AuiDockInfo` structures;
   :param `pt`: a :class:`wx.Point` object.


.. function:: CheckOutOfWindow(window, pt)

   Checks if a point is outside the window rectangle.
   
   :param `window`: a :class:`wx.Window` derived window;
   :param `pt`: a :class:`wx.Point` object.


.. function:: CopyDocksAndPanes(src_docks, src_panes)

   This utility function creates shallow copies of
   the dock and pane info. :class:`AuiManager` usually contain pointers
   to :class:`AuiPaneInfo` classes, thus this function is necessary to reliably
   reconstruct that relationship in the new dock info and pane info arrays.
   
   :param `src_docks`: a list of :class:`AuiDockInfo` classes;
   :param `src_panes`: a list of :class:`AuiPaneInfo` classes.


.. function:: CopyDocksAndPanes2(src_docks, src_panes)

   This utility function creates full copies of
   the dock and pane info. :class:`AuiManager` usually contain pointers
   to :class:`AuiPaneInfo` classes, thus this function is necessary to reliably
   reconstruct that relationship in the new dock info and pane info arrays.
   
   :param `src_docks`: a list of :class:`AuiDockInfo` classes;
   :param `src_panes`: a list of :class:`AuiPaneInfo` classes.


.. function:: 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.
   
   :param `panes`: a list of :class:`AuiPaneInfo`;
   :param integer `dock_direction`: the :class:`AuiDockInfo` docking direction to analyze;
   :param integer `dock_layer`: the :class:`AuiDockInfo` layer to analyze.


.. function:: 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.
   
   :param `panes`: a list of :class:`AuiPaneInfo`;
   :param integer `dock_direction`: the :class:`AuiDockInfo` docking direction to analyze;
   :param integer `dock_layer`: the :class:`AuiDockInfo` layer to analyze;
   :param integer `dock_row`: the :class:`AuiDockInfo` row to analyze.


.. function:: 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.
   
   :param `panes`: a list of :class:`AuiPaneInfo`;
   :param integer `dock_direction`: the :class:`AuiDockInfo` docking direction to analyze;
   :param integer `dock_layer`: the :class:`AuiDockInfo` layer to analyze.
   :param integer `dock_row`: the :class:`AuiDockInfo` row to analyze;
   :param integer `dock_pos`: the :class:`AuiDockInfo` position to analyze.


.. function:: DrawResizeHint(dc, rect)

   Draws a resize hint while a sash is dragged.
   
   :param wx.Rect `rect`: a rectangle which specifies the sash dimensions.


.. function:: EscapeDelimiters(s)

   Changes ``;`` into ``\`` and ``|`` into ``|\`` in the input string.
   
   :param string `s`: the string to be analyzed.
   
   :note: This is an internal functions which is used for saving perspectives.


.. function:: 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).
   
   :param `docks`: a list of :class:`AuiDockInfo`;
   :param integer `dock_direction`: the :class:`AuiDockInfo` docking direction to analyze;
   :param integer `dock_layer`: the :class:`AuiDockInfo` layer to analyze.
   :param integer `dock_row`: the :class:`AuiDockInfo` row to analyze;


.. function:: FindOppositeDocks(docks, dock_direction)

   This is an internal function that returns a list of docks
   which is related to the opposite direction.
   
   :param `docks`: a list of :class:`AuiDockInfo`;
   :param integer `dock_direction`: the :class:`AuiDockInfo` docking direction to analyze;


.. function:: FindPaneInDock(dock, window)

   This method looks up a specified window pointer inside a dock.
   If found, the corresponding :class:`AuiDockInfo` pointer is returned, otherwise ``None``.
   
   :param `dock`: a :class:`AuiDockInfo` structure;
   :param wx.Window `window`: the window associated to the pane we are seeking.


.. function:: GetInternalFrameRect(window, docks)

   Returns the window rectangle excluding toolbars.
   
   :param `window`: a :class:`wx.Window` derived window;
   :param `docks`: a list of :class:`AuiDockInfo` structures.


.. function:: GetManager(window)

   This function will return the aui manager for a given window.
   
   :param wx.Window `window`: this parameter should be any child window or grand-child
    window (and so on) of the frame/window managed by :class:`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.


.. function:: GetMaxLayer(docks, dock_direction)

   This is an internal function which returns
   the highest layer inside the specified dock.
   
   :param `docks`: a list of :class:`AuiDockInfo`;
   :param `dock_direction`: the :class:`AuiDockInfo` docking direction to analyze.


.. function:: GetMaxRow(panes, dock_direction, dock_layer)

   This is an internal function which returns
   the highest layer inside the specified dock.
   
   :param `panes`: a list of :class:`AuiPaneInfo`;
   :param integer `dock_direction`: the :class:`AuiDockInfo` docking direction to analyze;
   :param integer `dock_layer`: the :class:`AuiDockInfo` layer to analyze.


.. function:: GetNotebookRoot(panes, notebook_id)

   Returns the :class:`~wx.lib.agw.aui.auibook.AuiNotebook` which has the specified `notebook_id`.
   
   :param `panes`: a list of :class:`AuiPaneInfo` instances;
   :param integer `notebook_id`: the target notebook id.


.. function:: GetToolBarDockOffsets(docks)

   Returns the toolbar dock offsets (top-left and bottom-right).
   
   :param `docks`: a list of :class:`AuiDockInfo` to analyze.


.. function:: 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.
   
   :param `pane1`: a :class:`AuiPaneInfo` instance;
   :param `pane2`: another :class:`AuiPaneInfo` instance.


.. function:: PaneSortFunc(p1, p2)

   This function is used to sort panes by dock position.
   
   :param `p1`: the first pane instance to compare, an instance of :class:`AuiPaneInfo`;
   :param `p2`: the second pane instance to compare, an instance of :class:`AuiPaneInfo`.


.. function:: RefreshDockingGuides(guides)

   Refreshes the docking guide windows.
   
   :param `guides`: a list of :class:`AuiDockingGuide` classes;


.. function:: RemovePaneFromDocks(docks, pane, exc=None)

   Removes a pane window from all docks
   with a possible exception specified by parameter `exc`.
   
   :param `docks`: a list of :class:`AuiDockInfo` structures;
   :param `pane`: the pane to be removed, an instance of :class:`AuiPaneInfo`;
   :param `exc`: the possible pane exception, an instance of :class:`AuiPaneInfo`.


.. function:: 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.
   
   :param `docks`: a list of :class:`AuiDockInfo` structures.


.. function:: 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.
   
   :param `panes`: a list of :class:`AuiPaneInfo` structures;
   :param `active_pane`: the pane to be made active (if found), an instance of :class:`AuiPaneInfo`.


.. function:: ShowDockingGuides(guides, show)

   Shows or hide the docking guide windows.
   
   :param `guides`: a list of :class:`AuiDockingGuide` classes;
   :param bool `show`: whether to show or hide the docking guide windows.