// 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(int flags);
+ void SetFlags(unsigned int flags);
/**
Called to specify the frame or window which is to be managed by wxAuiManager.
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);
//@}
/**
SetFlag() turns the property given by flag on or off with the option_state
parameter.
*/
- wxAuiPaneInfo& SetFlag(unsigned int flag, bool option_state);
+ wxAuiPaneInfo& SetFlag(int flag, bool option_state);
/**
Show() indicates that a pane should be shown.
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