Set svn properties on recently added files.

[wxWidgets.git] / interface / wx / ribbon / panel.h

diff --git a/interface/wx/ribbon/panel.h b/interface/wx/ribbon/panel.h
index 208290141cab8a5fa6d7655a6034ac23f7055391..95fa05078156aa23e2f2fd6e1d8a8190246112df 100644 (file)
--- a/interface/wx/ribbon/panel.h
+++ b/interface/wx/ribbon/panel.h
@@ -6,27 +6,59 @@
 // Licence:     wxWindows licence
 ///////////////////////////////////////////////////////////////////////////////
 
 // 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.
 /**
     @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
     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
     @sa wxRibbonPage

-    
+

     @beginStyleTable
     @style{wxRIBBON_PANEL_DEFAULT_STYLE}
         Defined as no other flags set.
     @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.
         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
 
     @endStyleTable
 

+    @beginEventEmissionTable{wxRibbonPanelEvent}
+    @event{EVT_RIBBONPANEL_EXTBUTTON_ACTIVATED(id, func)}
+        Triggered when the user activate the panel extension button.
+    @endEventTable
+

     @library{wxribbon}
     @category{ribbon}
 */
     @library{wxribbon}
     @category{ribbon}
 */


@@ -55,7 +100,7 @@ class wxRibbonPanel : public wxRibbonControl
 {
 public:
     /**
 {
 public:
     /**

-        Default constructor. 
+        Default constructor.

         With this constructor, Create() should be called in order to create
         the ribbon panel.
     */
         With this constructor, Create() should be called in order to create
         the ribbon panel.
     */


@@ -63,7 +108,7 @@ public:
 
     /**
         Constructs a ribbon panel.
 
     /**
         Constructs a ribbon panel.

-    
+

         @param parent
             Pointer to a parent window, which is typically a wxRibbonPage,
             though it can be any window.
         @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);
                   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
     /**
         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;
     */
     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 is currently minimised.
     */
     bool IsMinimised() const;

-    
+

     /**
         Query if the panel would be minimised at a given size.
     */
     bool IsMinimised(wxSize at_size) 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 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;
     /**
         Query if the panel can automatically minimise itself at small sizes.
     */
     bool CanAutoMinimise() const;

-    
+

     /**
         Show the panel externally expanded.
     /**
         Show the panel externally expanded.

-        
+

         When a panel is minimised, it can be shown full-size in a pop-out
         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
         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.
         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).
         @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();
         @see HideExpanded()
         @see GetExpandedPanel()
     */
     bool ShowExpanded();

-    
+

     /**
         Hide the panel's external expansion.
     /**
         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).
         @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()
     */
         @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.
         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);
         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();
     /**
         Realize all children of the panel.
     */
     bool Realize();

-    
+

     /**
         Get the dummy panel of an expanded panel.
     /**
         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.
         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();
         @see ShowExpanded()
         @see GetExpandedPanel()
     */
     wxRibbonPanel* GetExpandedDummy();

-    
+

     /**
         Get the expanded panel of a dummy panel.
     /**
         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.
         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()
     */
         @see ShowExpanded()
         @see GetExpandedDummy()
     */