// Purpose: interface of wxAuiManager
// Author: wxWidgets team
// RCS-ID: $Id$
-// Licence: wxWindows license
+// Licence: wxWindows licence
/////////////////////////////////////////////////////////////////////////////
/**
- @todo TOWRITE
+ @todo wxAuiPaneInfo dock direction types used with wxAuiManager.
*/
enum wxAuiManagerDock
{
/**
- @todo TOWRITE
+ wxAuiManager behaviour and visual effects style flags.
*/
enum wxAuiManagerOption
{
+ /// Allow a pane to be undocked to take the form of a wxMiniFrame.
wxAUI_MGR_ALLOW_FLOATING = 1 << 0,
+ /// Change the color of the title bar of the pane when it is activated.
wxAUI_MGR_ALLOW_ACTIVE_PANE = 1 << 1,
+ /// Make the pane transparent during its movement.
wxAUI_MGR_TRANSPARENT_DRAG = 1 << 2,
+ /// The possible location for docking is indicated by a translucent area.
wxAUI_MGR_TRANSPARENT_HINT = 1 << 3,
+ /// The possible location for docking is indicated by a gradually appearing
+ /// partially transparent area.
wxAUI_MGR_VENETIAN_BLINDS_HINT = 1 << 4,
+ /// The possible location for docking is indicated by a rectangular outline.
wxAUI_MGR_RECTANGLE_HINT = 1 << 5,
+ /// The translucent area where the pane could be docked appears gradually.
wxAUI_MGR_HINT_FADE = 1 << 6,
+ /// Used in complement of wxAUI_MGR_VENETIAN_BLINDS_HINT to show the hint immediately.
wxAUI_MGR_NO_VENETIAN_BLINDS_FADE = 1 << 7,
+ /// When a docked pane is resized, its content is refreshed in live (instead of moving
+ /// the border alone and refreshing the content at the end).
wxAUI_MGR_LIVE_RESIZE = 1 << 8,
-
+ /// Default behavior.
wxAUI_MGR_DEFAULT = wxAUI_MGR_ALLOW_FLOATING |
wxAUI_MGR_TRANSPARENT_HINT |
wxAUI_MGR_HINT_FADE |
@class wxAuiManager
wxAuiManager is the central class of the wxAUI class framework.
- See also @ref overview_aui.
wxAuiManager manages the panes associated with it for a particular wxFrame,
using a pane's wxAuiPaneInfo information to determine each pane's docking
- and floating behavior.
+ and floating behaviour.
- wxAuiManager uses wxWidgets' 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.
+ wxAuiManager uses wxWidgets' 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.
wxAuiManager works as follows: the programmer adds panes to the class,
or makes changes to existing pane properties (dock position, floating
@code
wxTextCtrl* text1 = new wxTextCtrl(this, -1);
wxTextCtrl* text2 = new wxTextCtrl(this, -1);
- m_mgr.AddPane(text1, wxLEFT, wxT("Pane Caption"));
- m_mgr.AddPane(text2, wxBOTTOM, wxT("Pane Caption"));
+ m_mgr.AddPane(text1, wxLEFT, "Pane Caption");
+ m_mgr.AddPane(text2, wxBOTTOM, "Pane Caption");
m_mgr.Update();
@endcode
@section auimanager_layers Layers, Rows and Directions, Positions
Inside wxAUI, the docking layout is figured out by checking several pane
- parameters. Four of these are important for determining where a pane will end up:
-
- @li 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.
- @li 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 its 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
+ parameters. Four of these are important for determining where a pane will
+ end up:
+
+ @li 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.
+ @li 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 its 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.
- @li 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 row 0, and the second row 1. Rows can also be
- used on vertically docked panes.
- @li 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 wxAUI sample.
-
+ @li 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 row 0, and the
+ second row 1. Rows can also be used on vertically docked panes.
+ @li 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 wxAUI sample.
+
+ @beginStyleTable
+ @style{wxAUI_MGR_ALLOW_FLOATING}
+ Allow a pane to be undocked to take the form of a wxMiniFrame.
+ @style{wxAUI_MGR_ALLOW_ACTIVE_PANE}
+ Change the color of the title bar of the pane when it is activated.
+ @style{wxAUI_MGR_TRANSPARENT_DRAG}
+ Make the pane transparent during its movement.
+ @style{wxAUI_MGR_TRANSPARENT_HINT}
+ The possible location for docking is indicated by a translucent area.
+ @style{wxAUI_MGR_VENETIAN_BLINDS_HINT}
+ The possible location for docking is indicated by gradually
+ appearing partially transparent hint.
+ @style{wxAUI_MGR_RECTANGLE_HINT}
+ The possible location for docking is indicated by a rectangular
+ outline.
+ @style{wxAUI_MGR_HINT_FADE}
+ The translucent area where the pane could be docked appears gradually.
+ @style{wxAUI_MGR_NO_VENETIAN_BLINDS_FADE}
+ Used in complement of wxAUI_MGR_VENETIAN_BLINDS_HINT to show the
+ docking hint immediately.
+ @style{wxAUI_MGR_LIVE_RESIZE}
+ When a docked pane is resized, its content is refreshed in live (instead of moving
+ the border alone and refreshing the content at the end).
+ @style{wxAUI_MGR_DEFAULT}
+ Default behavior, combines: wxAUI_MGR_ALLOW_FLOATING | wxAUI_MGR_TRANSPARENT_HINT |
+ wxAUI_MGR_HINT_FADE | wxAUI_MGR_NO_VENETIAN_BLINDS_FADE.
+ @endStyleTable
+
+ @beginEventEmissionTable{wxAuiManagerEvent}
+ @event{EVT_AUI_PANE_BUTTON(func)}
+ Triggered when any button is pressed for any docked panes.
+ @event{EVT_AUI_PANE_CLOSE(func)}
+ Triggered when a docked or floating pane is closed.
+ @event{EVT_AUI_PANE_MAXIMIZE(func)}
+ Triggered when a pane is maximized.
+ @event{EVT_AUI_PANE_RESTORE(func)}
+ Triggered when a pane is restored.
+ @event{EVT_AUI_PANE_ACTIVATED(func)}
+ Triggered when a pane is made 'active'. This event is new since
+ wxWidgets 2.9.4.
+ @event{EVT_AUI_RENDER(func)}
+ This event can be caught to override the default renderer in order to
+ custom draw your wxAuiManager window (not recommended).
+ @endEventTable
@library{wxbase}
@category{aui}
- @see wxAuiPaneInfo, wxAuiDockArt
+ @see @ref overview_aui, wxAuiNotebook, wxAuiDockArt, wxAuiPaneInfo
*/
class wxAuiManager : public wxEvtHandler
{
public:
/**
- Constructor. @a managed_wnd specifies the wxFrame which should be managed.
- @a flags specifies options which allow the frame management behavior
- to be modified.
+ Constructor.
+
+ @param managed_wnd
+ Specifies the wxFrame which should be managed.
+ @param flags
+ Specifies the frame management behaviour and visual effects
+ with the ::wxAuiManagerOption's style flags.
*/
wxAuiManager(wxWindow* managed_wnd = NULL,
unsigned int flags = wxAUI_MGR_DEFAULT);
void GetDockSizeConstraint(double* widthpct, double* heightpct) const;
/**
- Returns the current manager's flags.
+ Returns the current ::wxAuiManagerOption's flags.
*/
unsigned int GetFlags() const;
interface. If the lookup failed (meaning the pane could not be found in the
manager), a call to the returned wxAuiPaneInfo's IsOk() method will return @false.
*/
- wxAuiPaneInfo GetPane(wxWindow* window);
- wxAuiPaneInfo GetPane(const wxString& name);
+ wxAuiPaneInfo& GetPane(wxWindow* window);
+ wxAuiPaneInfo& GetPane(const wxString& name);
//@}
/**
int insert_level = wxAUI_INSERT_PANE);
/**
- LoadPaneInfo() is similar to to LoadPerspective, with the exception that it
+ LoadPaneInfo() is similar to LoadPerspective, with the exception that it
only loads information about a single pane. It is used in combination with
SavePaneInfo().
*/
void SetDockSizeConstraint(double widthpct, double heightpct);
/**
- This method is used to specify wxAuiManager's settings flags. @a flags
- specifies options which allow the frame management behavior to be modified.
+ This method is used to specify ::wxAuiManagerOption's flags. @a flags
+ specifies options which allow the frame management behaviour to be modified.
*/
void SetFlags(unsigned int flags);
BestSize() sets the ideal size for the pane. The docking manager will attempt
to use this size as much as possible when docking or floating the pane.
*/
- wxAuiPaneInfo BestSize(const wxSize& size);
- wxAuiPaneInfo BestSize(int x, int y);
+ wxAuiPaneInfo& BestSize(const wxSize& size);
+ wxAuiPaneInfo& BestSize(int x, int y);
//@}
/**
right, bottom) are subtracted from the layout.
This is the same thing as calling Direction(wxAUI_DOCK_CENTRE).
*/
- wxAuiPaneInfo Centre();
- wxAuiPaneInfo Center();
+ wxAuiPaneInfo& Centre();
+ wxAuiPaneInfo& Center();
//@}
//@{
This function provides an easy way of preparing a pane to be displayed in
the center dock position.
*/
- wxAuiPaneInfo CentrePane();
- wxAuiPaneInfo CenterPane();
+ wxAuiPaneInfo& CentrePane();
+ wxAuiPaneInfo& CenterPane();
//@}
/**
wxAuiPaneInfo& DefaultPane();
/**
- DestroyOnClose() indicates whether a pane should be detroyed when it is closed.
+ DestroyOnClose() indicates whether a pane should be destroyed when it is closed.
Normally a pane is simply hidden when the close button is clicked.
Setting DestroyOnClose to @true will cause the window to be destroyed when
the user clicks the pane's close button.
/**
FloatingPosition() sets the position of the floating pane.
*/
- wxAuiPaneInfo FloatingPosition(const wxPoint& pos);
- wxAuiPaneInfo FloatingPosition(int x, int y);
+ wxAuiPaneInfo& FloatingPosition(const wxPoint& pos);
+ wxAuiPaneInfo& FloatingPosition(int x, int y);
//@}
//@{
/**
FloatingSize() sets the size of the floating pane.
*/
- wxAuiPaneInfo FloatingSize(const wxSize& size);
- wxAuiPaneInfo FloatingSize(int x, int y);
+ wxAuiPaneInfo& FloatingSize(const wxSize& size);
+ wxAuiPaneInfo& FloatingSize(int x, int y);
//@}
/**
*/
wxAuiPaneInfo& Hide();
+ /**
+ Icon() sets the icon of the pane.
+
+ Notice that the height of the icon should be smaller than the value
+ returned by wxAuiDockArt::GetMetric(wxAUI_DOCKART_CAPTION_SIZE) to
+ ensure that it appears correctly.
+
+ @since 2.9.2
+ */
+ wxAuiPaneInfo& Icon(const wxBitmap& b);
+
/**
IsBottomDockable() returns @true if the pane can be docked at the bottom of the
managed frame.
+
+ @see IsDockable()
*/
bool IsBottomDockable() const;
/**
- IsDocked() returns @true if the pane is docked.
+ Returns @true if the pane can be docked at any side.
+
+ @see IsTopDockable(), IsBottomDockable(), IsLeftDockable(), IsRightDockable()
+
+ @since 2.9.2
+ */
+ bool IsDockable() const;
+
+ /**
+ IsDocked() returns @true if the pane is currently docked.
*/
bool IsDocked() const;
/**
IsLeftDockable() returns @true if the pane can be docked on the left of the
managed frame.
+
+ @see IsDockable()
*/
bool IsLeftDockable() const;
/**
IsRightDockable() returns @true if the pane can be docked on the right of the
managed frame.
+
+ @see IsDockable()
*/
bool IsRightDockable() const;
/**
IsTopDockable() returns @true if the pane can be docked at the top of the
managed frame.
+
+ @see IsDockable()
*/
bool IsTopDockable() const;
/**
MaxSize() sets the maximum size of the pane.
*/
- wxAuiPaneInfo MaxSize(const wxSize& size);
- wxAuiPaneInfo MaxSize(int x, int y);
+ wxAuiPaneInfo& MaxSize(const wxSize& size);
+ wxAuiPaneInfo& MaxSize(int x, int y);
//@}
/**
MinSize() sets the minimum size of the pane. Please note that this is only
partially supported as of this writing.
*/
- wxAuiPaneInfo MinSize(const wxSize& size);
- wxAuiPaneInfo MinSize(int x, int y);
+ wxAuiPaneInfo& MinSize(const wxSize& size);
+ wxAuiPaneInfo& MinSize(int x, int y);
//@}
/**
wxAuiPaneInfo& operator=(const wxAuiPaneInfo& c);
};
+
+
+/**
+ @class wxAuiManagerEvent
+
+ Event used to indicate various actions taken with wxAuiManager.
+
+ See wxAuiManager for available event types.
+
+ @beginEventTable{wxAuiManagerEvent}
+ @event{EVT_AUI_PANE_BUTTON(func)}
+ Triggered when any button is pressed for any docked panes.
+ @event{EVT_AUI_PANE_CLOSE(func)}
+ Triggered when a docked or floating pane is closed.
+ @event{EVT_AUI_PANE_MAXIMIZE(func)}
+ Triggered when a pane is maximized.
+ @event{EVT_AUI_PANE_RESTORE(func)}
+ Triggered when a pane is restored.
+ @event{EVT_AUI_PANE_ACTIVATED(func)}
+ Triggered when a pane is made 'active'. This event is new since
+ wxWidgets 2.9.4.
+ @event{EVT_AUI_RENDER(func)}
+ This event can be caught to override the default renderer in order to
+ custom draw your wxAuiManager window (not recommended).
+ @endEventTable
+
+ @library{wxaui}
+ @category{events,aui}
+
+ @see wxAuiManager, wxAuiPaneInfo
+*/
+class wxAuiManagerEvent : public wxEvent
+{
+public:
+ /**
+ Constructor.
+ */
+ wxAuiManagerEvent(wxEventType type = wxEVT_NULL);
+
+ /**
+ @return @true if this event can be vetoed.
+
+ @see Veto()
+ */
+ bool CanVeto();
+
+ /**
+ @return The ID of the button that was clicked.
+ */
+ int GetButton();
+
+ /**
+ @todo What is this?
+ */
+ wxDC* GetDC();
+
+ /**
+ @return @true if this event was vetoed.
+
+ @see Veto()
+ */
+ bool GetVeto();
+
+ /**
+ @return The wxAuiManager this event is associated with.
+ */
+ wxAuiManager* GetManager();
+
+ /**
+ @return The pane this event is associated with.
+ */
+ wxAuiPaneInfo* GetPane();
+
+ /**
+ Sets the ID of the button clicked that triggered this event.
+ */
+ void SetButton(int button);
+
+ /**
+ Sets whether or not this event can be vetoed.
+ */
+ void SetCanVeto(bool can_veto);
+
+ /**
+ @todo What is this?
+ */
+ void SetDC(wxDC* pdc);
+
+ /**
+ Sets the wxAuiManager this event is associated with.
+ */
+ void SetManager(wxAuiManager* manager);
+
+ /**
+ Sets the pane this event is associated with.
+ */
+ void SetPane(wxAuiPaneInfo* pane);
+
+ /**
+ Cancels the action indicated by this event if CanVeto() is @true.
+ */
+ void Veto(bool veto = true);
+};
+
projects / wxWidgets.git / blobdiff