| 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 | }; |