interface/wx/ribbon/panel.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        ribbon/panel.h
   3 // Purpose:     interface of wxRibbonPage
   4 // Author:      Peter Cawley
   5 // RCS-ID:      $Id$
   6 // Licence:     wxWindows licence
   7 ///////////////////////////////////////////////////////////////////////////////
   8
   9 /**
  10     @class wxRibbonPanel
  11
  12     Serves as a container for a group of (ribbon) controls. A wxRibbonPage will
  13     typically have panels for children, with the controls for that page placed
  14     on the panels.
  15
  16     A panel adds a border and label to a group of controls, and can be
  17     minimised (either automatically to conserve space, or manually by the user).
  18
  19     Non ribbon controls can be placed on a panel using wxSizers to manage
  20     layout. Panel size is governed by the sizer's minimum calculated size and
  21     the parent wxRibbonPage's dimensions. For functional and aesthetic reasons
  22     it is recommended that ribbon and non ribbon controls are not mixed in one
  23     panel.
  24
  25     @sa wxRibbonPage
  26
  27     @beginStyleTable
  28     @style{wxRIBBON_PANEL_DEFAULT_STYLE}
  29         Defined as no other flags set.
  30     @style{wxRIBBON_PANEL_NO_AUTO_MINIMISE}
  31         Prevents the panel from automatically minimising to conserve screen
  32         space.
  33     @style{wxRIBBON_PANEL_EXT_BUTTON}
  34         Causes an extension button to be shown in the panel's chrome (if the
  35         bar in which it is contained has wxRIBBON_BAR_SHOW_PANEL_EXT_BUTTONS
  36         set). The behaviour of this button is application controlled, but
  37         typically will show an extended drop-down menu relating to the
  38         panel.
  39     @style{wxRIBBON_PANEL_MINIMISE_BUTTON}
  40         Causes a (de)minimise button to be shown in the panel's chrome (if
  41         the bar in which it is contained has the
  42         wxRIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS style set). This flag is
  43         typically combined with wxRIBBON_PANEL_NO_AUTO_MINIMISE to make a
  44         panel which the user always has manual control over when it
  45         minimises.
  46     @style{wxRIBBON_PANEL_STRETCH}
  47         Stretches a single panel to fit the parent page.
  48     @style{wxRIBBON_PANEL_FLEXIBLE}
  49         Allows the panel to size in both directions; currently only useful
  50         when a single wxRibbonToolBar is the child of the panel, particularly
  51         in vertical orientation where the number of rows is dependent on the
  52         amount of horizontal space available. Set the minimum and maximum
  53         toolbar rows to take full advantage of this wrapping behaviour.
  54     @endStyleTable
  55
  56     @library{wxribbon}
  57     @category{ribbon}
  58 */
  59 class wxRibbonPanel : public wxRibbonControl
  60 {
  61 public:
  62     /**
  63         Default constructor.
  64         With this constructor, Create() should be called in order to create
  65         the ribbon panel.
  66     */
  67     wxRibbonPanel();
  68
  69     /**
  70         Constructs a ribbon panel.
  71
  72         @param parent
  73             Pointer to a parent window, which is typically a wxRibbonPage,
  74             though it can be any window.
  75         @param id
  76             Window identifier.
  77         @param label
  78             Label to be used in the wxRibbonPanel's chrome.
  79         @param minimised_icon
  80             Icon to be used in place of the panel's children when the panel
  81             is minimised.
  82         @param pos
  83             The initial position of the panel. Not relevant when the parent is
  84             a ribbon page, as the position and size of the panel will be
  85             dictated by the page.
  86         @param size
  87             The initial size of the panel. Not relevant when the parent is a
  88             ribbon page, as the position and size of the panel will be
  89             dictated by the page.
  90         @param style
  91             Style flags for the panel.
  92     */
  93     wxRibbonPanel(wxWindow* parent,
  94                   wxWindowID id = wxID_ANY,
  95                   const wxString& label = wxEmptyString,
  96                   const wxBitmap& minimised_icon = wxNullBitmap,
  97                   const wxPoint& pos = wxDefaultPosition,
  98                   const wxSize& size = wxDefaultSize,
  99                   long style = wxRIBBON_PANEL_DEFAULT_STYLE);
 100
 101     /**
 102         Create a ribbon panel in two-step ribbon panel construction.
 103         Should only be called when the default constructor is used, and
 104         arguments have the same meaning as in the full constructor.
 105     */
 106     bool Create(wxWindow* parent,
 107                 wxWindowID id = wxID_ANY,
 108                 const wxString& label = wxEmptyString,
 109                 const wxBitmap& icon = wxNullBitmap,
 110                 const wxPoint& pos = wxDefaultPosition,
 111                 const wxSize& size = wxDefaultSize,
 112                 long style = wxRIBBON_PANEL_DEFAULT_STYLE);
 113
 114     /**
 115         Destructor.
 116     */
 117     virtual ~wxRibbonPanel();
 118
 119     /**
 120         Get the bitmap to be used in place of the panel children when it is
 121         minimised.
 122     */
 123     wxBitmap& GetMinimisedIcon();
 124     const wxBitmap& GetMinimisedIcon() const;
 125
 126     /**
 127         Query if the panel is currently minimised.
 128     */
 129     bool IsMinimised() const;
 130
 131     /**
 132         Query if the panel would be minimised at a given size.
 133     */
 134     bool IsMinimised(wxSize at_size) const;
 135
 136     /**
 137         Query is the mouse is currently hovered over the panel.
 138         @return @true if the cursor is within the bounds of the panel (i.e.
 139             hovered over the panel or one of its children), @false otherwise.
 140     */
 141     bool IsHovered() const;
 142
 143     /**
 144         Query if the panel can automatically minimise itself at small sizes.
 145     */
 146     bool CanAutoMinimise() const;
 147
 148     /**
 149         Show the panel externally expanded.
 150
 151         When a panel is minimised, it can be shown full-size in a pop-out
 152         window, which is referred to as being (externally) expanded. Note that
 153         when a panel is expanded, there exist two panels - the original panel
 154         (which is referred to as the dummy panel) and the expanded panel. The
 155         original is termed a dummy as it sits in the ribbon bar doing nothing,
 156         while the expanded panel holds the panel children.
 157
 158         @return @true if the panel was expanded, @false if it was not (possibly
 159             due to it not being minimised, or already being expanded).
 160
 161         @see HideExpanded()
 162         @see GetExpandedPanel()
 163     */
 164     bool ShowExpanded();
 165
 166     /**
 167         Hide the panel's external expansion.
 168
 169         @return @true if the panel was un-expanded, @false if it was not
 170             (normally due to it not being expanded in the first place).
 171
 172         @see HideExpanded()
 173         @see GetExpandedPanel()
 174     */
 175     bool HideExpanded();
 176
 177     /**
 178         Set the art provider to be used. Normally called automatically by
 179         wxRibbonPage when the panel is created, or the art provider changed on the
 180         page.
 181
 182         The new art provider will be propagated to the children of the panel.
 183     */
 184     void SetArtProvider(wxRibbonArtProvider* art);
 185
 186     /**
 187         Realize all children of the panel.
 188     */
 189     bool Realize();
 190
 191     /**
 192         Get the dummy panel of an expanded panel.
 193
 194         Note that this should be called on an expanded panel to get the dummy
 195         associated with it - it will return NULL when called on the dummy
 196         itself.
 197
 198         @see ShowExpanded()
 199         @see GetExpandedPanel()
 200     */
 201     wxRibbonPanel* GetExpandedDummy();
 202
 203     /**
 204         Get the expanded panel of a dummy panel.
 205
 206         Note that this should be called on a dummy panel to get the expanded
 207         panel associated with it - it will return NULL when called on the
 208         expanded panel itself.
 209
 210         @see ShowExpanded()
 211         @see GetExpandedDummy()
 212     */
 213     wxRibbonPanel* GetExpandedPanel();
 214 };