]>
Commit | Line | Data |
---|---|---|
3c3ead1d PC |
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 | }; |