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