interface/wx/ribbon/panel.h

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