X-Git-Url: https://git.saurik.com/wxWidgets.git/blobdiff_plain/b95d405138e4bcbffe3954d40a3755564ebd6907..ca282726be518ce2f214b890dbaafce736f14e36:/interface/wx/ribbon/panel.h diff --git a/interface/wx/ribbon/panel.h b/interface/wx/ribbon/panel.h index 208290141c..95fa050781 100644 --- a/interface/wx/ribbon/panel.h +++ b/interface/wx/ribbon/panel.h @@ -6,27 +6,59 @@ // Licence: wxWindows licence /////////////////////////////////////////////////////////////////////////////// +/** + @class wxRibbonPanelEvent + + Event used to indicate various actions relating to a wxRibbonPanel. + + See wxRibbonPanel for available event types. + + @since 2.9.4 + + @library{wxribbon} + @category{events,ribbon} + + @see wxRibbonPanel +*/ +class wxRibbonPanelEvent : public wxCommandEvent +{ +public: + /** + Constructor. + */ + wxRibbonPanelEvent(wxEventType command_type = wxEVT_NULL, + int win_id = 0, + wxRibbonPanel* panel = NULL) + + /** + Returns the panel relating to this event. + */ + wxRibbonPanel* GetPanel(); + + /** + Sets the page relating to this event. + */ + void SetPanel(wxRibbonPanel* page); +}; + /** @class wxRibbonPanel Serves as a container for a group of (ribbon) controls. A wxRibbonPage will typically have panels for children, with the controls for that page placed on the panels. - + A panel adds a border and label to a group of controls, and can be minimised (either automatically to conserve space, or manually by the user). Non ribbon controls can be placed on a panel using wxSizers to manage - layout. wxWrapSizer and AddStretchSpacer() are useful for proportional - vertical and horizontal positioning. Note that layout is done within the - constraints of the panel's client area and this is dictated by - wxRibbonArtProvider. - - Mixing ribbon and non-ribbon controls in a RibbonPanel is not supported at - present. - + layout. Panel size is governed by the sizer's minimum calculated size and + the parent wxRibbonPage's dimensions. For functional and aesthetic reasons + it is recommended that ribbon and non ribbon controls are not mixed in one + panel. + @sa wxRibbonPage - + @beginStyleTable @style{wxRIBBON_PANEL_DEFAULT_STYLE} Defined as no other flags set. @@ -46,8 +78,21 @@ typically combined with wxRIBBON_PANEL_NO_AUTO_MINIMISE to make a panel which the user always has manual control over when it minimises. + @style{wxRIBBON_PANEL_STRETCH} + Stretches a single panel to fit the parent page. + @style{wxRIBBON_PANEL_FLEXIBLE} + Allows the panel to size in both directions; currently only useful + when a single wxRibbonToolBar is the child of the panel, particularly + in vertical orientation where the number of rows is dependent on the + amount of horizontal space available. Set the minimum and maximum + toolbar rows to take full advantage of this wrapping behaviour. @endStyleTable + @beginEventEmissionTable{wxRibbonPanelEvent} + @event{EVT_RIBBONPANEL_EXTBUTTON_ACTIVATED(id, func)} + Triggered when the user activate the panel extension button. + @endEventTable + @library{wxribbon} @category{ribbon} */ @@ -55,7 +100,7 @@ class wxRibbonPanel : public wxRibbonControl { public: /** - Default constructor. + Default constructor. With this constructor, Create() should be called in order to create the ribbon panel. */ @@ -63,7 +108,7 @@ public: /** Constructs a ribbon panel. - + @param parent Pointer to a parent window, which is typically a wxRibbonPage, though it can be any window. @@ -92,7 +137,7 @@ public: const wxPoint& pos = wxDefaultPosition, const wxSize& size = wxDefaultSize, long style = wxRIBBON_PANEL_DEFAULT_STYLE); - + /** Create a ribbon panel in two-step ribbon panel construction. Should only be called when the default constructor is used, and @@ -117,53 +162,75 @@ public: */ wxBitmap& GetMinimisedIcon(); const wxBitmap& GetMinimisedIcon() const; - + + /** + Test if the panel has an extension button. + + Such button is shown in the top right corner of the panel if + @c wxRIBBON_PANEL_EXT_BUTTON style is used for it. + + @since 2.9.4 + + @return @true if the panel and its wxRibbonBar allow it in their styles. + */ + virtual bool HasExtButton() const; + /** Query if the panel is currently minimised. */ bool IsMinimised() const; - + /** Query if the panel would be minimised at a given size. */ bool IsMinimised(wxSize at_size) const; - + /** Query is the mouse is currently hovered over the panel. @return @true if the cursor is within the bounds of the panel (i.e. hovered over the panel or one of its children), @false otherwise. */ bool IsHovered() const; - + + /** + Query if the mouse is currently hovered over the extension button. + + Extension button is only shown for panels with @c + wxRIBBON_PANEL_EXT_BUTTON style. + + @since 2.9.4 + */ + bool IsExtButtonHovered() const; + /** Query if the panel can automatically minimise itself at small sizes. */ bool CanAutoMinimise() const; - + /** Show the panel externally expanded. - + When a panel is minimised, it can be shown full-size in a pop-out - window, which is refered to as being (externally) expanded. Note that + window, which is referred to as being (externally) expanded. Note that when a panel is expanded, there exist two panels - the original panel - (which is refered to as the dummy panel) and the expanded panel. The + (which is referred to as the dummy panel) and the expanded panel. The original is termed a dummy as it sits in the ribbon bar doing nothing, while the expanded panel holds the panel children. - + @return @true if the panel was expanded, @false if it was not (possibly due to it not being minimised, or already being expanded). - + @see HideExpanded() @see GetExpandedPanel() */ bool ShowExpanded(); - + /** Hide the panel's external expansion. - + @return @true if the panel was un-expanded, @false if it was not (normally due to it not being expanded in the first place). - + @see HideExpanded() @see GetExpandedPanel() */ @@ -173,35 +240,35 @@ public: Set the art provider to be used. Normally called automatically by wxRibbonPage when the panel is created, or the art provider changed on the page. - + The new art provider will be propagated to the children of the panel. */ void SetArtProvider(wxRibbonArtProvider* art); - + /** Realize all children of the panel. */ bool Realize(); - + /** Get the dummy panel of an expanded panel. - + Note that this should be called on an expanded panel to get the dummy associated with it - it will return NULL when called on the dummy itself. - + @see ShowExpanded() @see GetExpandedPanel() */ wxRibbonPanel* GetExpandedDummy(); - + /** Get the expanded panel of a dummy panel. - + Note that this should be called on a dummy panel to get the expanded panel associated with it - it will return NULL when called on the expanded panel itself. - + @see ShowExpanded() @see GetExpandedDummy() */