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