X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/3a74a290a9fcfafd93fd1a23e6857ad60836cb9d..7344108e8a129a3f9b4df5ab0f98a1713db03b89:/interface/wx/aui/framemanager.h diff --git a/interface/wx/aui/framemanager.h b/interface/wx/aui/framemanager.h index 6e6d5ad581..6b36b17878 100644 --- a/interface/wx/aui/framemanager.h +++ b/interface/wx/aui/framemanager.h @@ -3,12 +3,12 @@ // 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 { @@ -23,19 +23,31 @@ 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 | @@ -46,16 +58,15 @@ enum wxAuiManagerOption @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 @@ -69,8 +80,8 @@ enum wxAuiManagerOption @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 @@ -85,41 +96,92 @@ enum wxAuiManagerOption @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); @@ -171,7 +233,7 @@ public: void GetDockSizeConstraint(double* widthpct, double* heightpct) const; /** - Returns the current manager's flags. + Returns the current ::wxAuiManagerOption's flags. */ unsigned int GetFlags() const; @@ -202,8 +264,8 @@ public: 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); //@} /** @@ -227,7 +289,7 @@ public: 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(). */ @@ -281,8 +343,8 @@ public: 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); @@ -365,8 +427,8 @@ public: 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); //@} /** @@ -399,8 +461,8 @@ public: 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(); //@} //@{ @@ -410,8 +472,8 @@ public: 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(); //@} /** @@ -425,7 +487,7 @@ public: 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. @@ -478,16 +540,16 @@ public: /** 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); //@} /** @@ -516,10 +578,10 @@ public: bool HasCloseButton() const; /** - HasFlag() returns @true if the the property specified by flag is active for the - pane. + HasFlag() returns @true if the property specified by flag is active for + the pane. */ - bool HasFlag(unsigned int flag) const; + bool HasFlag(int flag) const; /** HasGripper() returns @true if the pane displays a gripper. @@ -553,14 +615,36 @@ public: */ 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; @@ -583,6 +667,8 @@ public: /** IsLeftDockable() returns @true if the pane can be docked on the left of the managed frame. + + @see IsDockable() */ bool IsLeftDockable() const; @@ -606,6 +692,8 @@ public: /** IsRightDockable() returns @true if the pane can be docked on the right of the managed frame. + + @see IsDockable() */ bool IsRightDockable() const; @@ -622,6 +710,8 @@ public: /** IsTopDockable() returns @true if the pane can be docked at the top of the managed frame. + + @see IsDockable() */ bool IsTopDockable() const; @@ -648,8 +738,8 @@ public: /** 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); //@} /** @@ -662,8 +752,8 @@ public: 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); //@} /** @@ -730,7 +820,7 @@ public: 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. @@ -767,3 +857,107 @@ public: 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); +}; +