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