]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/ribbon/buttonbar.h
No changes, just merge some strings in wxSVGFileDC.
[wxWidgets.git] / interface / wx / ribbon / buttonbar.h
CommitLineData
3c3ead1d
PC
1///////////////////////////////////////////////////////////////////////////////
2// Name: ribbon/buttonbar.h
3// Purpose: interface of wxRibbonButtonBar
4// Author: Peter Cawley
5// RCS-ID: $Id$
6// Licence: wxWindows licence
7///////////////////////////////////////////////////////////////////////////////
8
9/**
10 Flags for button bar button size and state.
11
12 Buttons on a ribbon button bar can each come in three sizes: small, medium,
13 and large. In some places this is called the size class, and the term size
14 used for the pixel width and height associated with a particular size
15 class.
16
17 A button can also be in zero or more hovered or active states, or in the
18 disabled state.
19*/
20enum wxRibbonButtonBarButtonState
21{
22 /**
23 Button is small (the interpretation of small is dependant upon the art
24 provider, but it will be smaller than medium).
25 */
26 wxRIBBON_BUTTONBAR_BUTTON_SMALL = 0 << 0,
27
28 /**
29 Button is medium sized (the interpretation of medium is dependant upon
30 the art provider, but it will be between small and large).
31 */
32 wxRIBBON_BUTTONBAR_BUTTON_MEDIUM = 1 << 0,
33
34 /**
35 Button is large (the interpretation of large is dependant upon the art
36 provider, but it will be larger than medium).
37 */
38 wxRIBBON_BUTTONBAR_BUTTON_LARGE = 2 << 0,
39
40 /**
41 A mask to extract button size from a combination of flags.
42 */
43 wxRIBBON_BUTTONBAR_BUTTON_SIZE_MASK = 3 << 0,
44
45 /**
46 The normal (non-dropdown) region of the button is being hovered over by
47 the mouse cursor. Only applicable to normal and hybrid buttons.
48 */
49 wxRIBBON_BUTTONBAR_BUTTON_NORMAL_HOVERED = 1 << 3,
50
51 /**
52 The dropdown region of the button is being hovered over by the mouse
53 cursor. Only applicable to dropdown and hybrid buttons.
54 */
55 wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_HOVERED = 1 << 4,
56
57 /**
58 A mask to extract button hover state from a combination of flags.
59 */
60 wxRIBBON_BUTTONBAR_BUTTON_HOVER_MASK = wxRIBBON_BUTTONBAR_BUTTON_NORMAL_HOVERED | wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_HOVERED,
61
62 /**
63 The normal (non-dropdown) region of the button is being pressed.
64 Only applicable to normal and hybrid buttons.
65 */
66 wxRIBBON_BUTTONBAR_BUTTON_NORMAL_ACTIVE = 1 << 5,
67
68 /**
69 The dropdown region of the button is being pressed.
70 Only applicable to dropdown and hybrid buttons.
71 */
72 wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_ACTIVE = 1 << 6,
73
74 /**
75 The button is disabled. Hover flags may still be set when a button
76 is disabled, but should be ignored during drawing if the button is
77 disabled.
78 */
79 wxRIBBON_BUTTONBAR_BUTTON_DISABLED = 1 << 7,
80
955bad41
PC
81 /**
82 The button is a toggle button which is currently in the toggled state.
83 */
84 wxRIBBON_BUTTONBAR_BUTTON_TOGGLED = 1 << 8,
85
3c3ead1d
PC
86 /**
87 A mask to extract button state from a combination of flags.
88 */
955bad41 89 wxRIBBON_BUTTONBAR_BUTTON_STATE_MASK = 0x1F8,
3c3ead1d
PC
90};
91
92/**
93 @class wxRibbonButtonBar
94
95 A ribbon button bar is similar to a traditional toolbar. It contains one or
96 more buttons (button bar buttons, not wxButtons), each of which has a label
97 and an icon. It differs from a wxRibbonToolBar in several ways:
98 @li Individual buttons can grow and contract.
99 @li Buttons have labels as well as bitmaps.
100 @li Bitmaps are typically larger (at least 32x32 pixels) on a button bar
101 compared to a tool bar (which typically has 16x15).
102 @li There is no grouping of buttons on a button bar
103 @li A button bar typically has a border around each individual button,
104 whereas a tool bar typically has a border around each group of buttons.
105
106 @beginEventEmissionTable{wxRibbonButtonBarEvent}
107 @event{EVT_RIBBONBUTTONBAR_CLICKED(id, func)}
108 Triggered when the normal (non-dropdown) region of a button on the
109 button bar is clicked.
110 @event{EVT_RIBBONBUTTONBAR_DROPDOWN_CLICKED(id, func)}
111 Triggered when the dropdown region of a button on the button bar is
112 clicked. wxRibbonButtonBarEvent::PopupMenu() should be called by the
113 event handler if it wants to display a popup menu (which is what most
114 dropdown buttons should be doing).
115 @endEventTable
116
117 @library{wxribbon}
118 @category{ribbon}
119*/
120class wxRibbonButtonBar : public wxRibbonControl
121{
122public:
123 /**
124 Default constructor.
125 With this constructor, Create() should be called in order to create
126 the button bar.
127 */
128 wxRibbonButtonBar();
129
130 /**
131 Construct a ribbon button bar with the given parameters.
69aa257b 132
3c3ead1d
PC
133 @param parent
134 Parent window for the button bar (typically a wxRibbonPanel).
69aa257b
FM
135 @param id
136 An identifier for the button bar. @c wxID_ANY is taken to mean a default.
3c3ead1d
PC
137 @param pos
138 Initial position of the button bar.
139 @param size
140 Initial size of the button bar.
141 @param style
142 Button bar style, currently unused.
143 */
144 wxRibbonButtonBar(wxWindow* parent,
145 wxWindowID id = wxID_ANY,
146 const wxPoint& pos = wxDefaultPosition,
147 const wxSize& size = wxDefaultSize,
148 long style = 0);
149
150 /**
151 Destructor.
152 */
153 virtual ~wxRibbonButtonBar();
154
155 /**
156 Create a button bar in two-step button bar construction.
157 Should only be called when the default constructor is used, and
158 arguments have the same meaning as in the full constructor.
159 */
160 bool Create(wxWindow* parent,
161 wxWindowID id = wxID_ANY,
162 const wxPoint& pos = wxDefaultPosition,
163 const wxSize& size = wxDefaultSize,
164 long style = 0);
165
166 /**
167 Add a button to the button bar (simple version).
168 */
169 virtual wxRibbonButtonBarButtonBase* AddButton(
170 int button_id,
171 const wxString& label,
172 const wxBitmap& bitmap,
173 const wxString& help_string,
174 wxRibbonButtonBarButtonKind kind = wxRIBBON_BUTTONBAR_BUTTON_NORMAL);
175
176 /**
177 Add a dropdown button to the button bar (simple version).
178
179 @see AddButton()
180 */
181 virtual wxRibbonButtonBarButtonBase* AddDropdownButton(
182 int button_id,
183 const wxString& label,
184 const wxBitmap& bitmap,
185 const wxString& help_string = wxEmptyString);
186
187 /**
188 Add a hybrid button to the button bar (simple version).
189
190 @see AddButton()
191 */
192 virtual wxRibbonButtonBarButtonBase* AddHybridButton(
193 int button_id,
194 const wxString& label,
195 const wxBitmap& bitmap,
196 const wxString& help_string = wxEmptyString);
197
955bad41
PC
198 /**
199 Add a toggle button to the button bar (simple version).
200
201 @see AddButton()
202 */
203 virtual wxRibbonButtonBarButtonBase* AddToggleButton(
204 int button_id,
205 const wxString& label,
206 const wxBitmap& bitmap,
207 const wxString& help_string = wxEmptyString);
208
3c3ead1d
PC
209 /**
210 Add a button to the button bar.
211
212 @param button_id
213 ID of the new button (used for event callbacks).
214 @param label
215 Label of the new button.
216 @param bitmap
217 Large bitmap of the new button. Must be the same size as all other
218 large bitmaps used on the button bar.
219 @param bitmap_small
220 Small bitmap of the new button. If left as null, then a small
221 bitmap will be automatically generated. Must be the same size as
222 all other small bitmaps used on the button bar.
223 @param bitmap_disabled
224 Large bitmap of the new button when it is disabled. If left as
225 null, then a bitmap will be automatically generated from @a bitmap.
226 @param bitmap_small_disabled
227 Small bitmap of the new button when it is disabled. If left as
228 null, then a bitmap will be automatically generated from @a
229 bitmap_small.
230 @param kind
231 The kind of button to add.
232 @param help_string
233 The UI help string to associate with the new button.
234 @param client_data
235 Client data to associate with the new button.
236
237 @return An opaque pointer which can be used only with other button bar
238 methods.
239
240 @see AddDropdownButton()
241 @see AddHybridButton()
955bad41 242 @see AddToggleButton()
3c3ead1d
PC
243 */
244 virtual wxRibbonButtonBarButtonBase* AddButton(
245 int button_id,
246 const wxString& label,
247 const wxBitmap& bitmap,
248 const wxBitmap& bitmap_small = wxNullBitmap,
249 const wxBitmap& bitmap_disabled = wxNullBitmap,
250 const wxBitmap& bitmap_small_disabled = wxNullBitmap,
251 wxRibbonButtonBarButtonKind kind = wxRIBBON_BUTTONBAR_BUTTON_NORMAL,
252 const wxString& help_string = wxEmptyString,
253 wxObject* client_data = NULL);
254
255 /**
256 Calculate button layouts and positions.
257
258 Must be called after buttons are added to the button bar, as otherwise
259 the newly added buttons will not be displayed. In normal situations, it
260 will be called automatically when wxRibbonBar::Realize() is called.
261 */
262 virtual bool Realize();
263
264 /**
265 Delete all buttons from the button bar.
266
267 @see DeleteButton()
268 */
269 virtual void ClearButtons();
270
271 /**
272 Delete a single button from the button bar.
273
274 @see ClearButtons()
275 */
276 virtual bool DeleteButton(int button_id);
277
278 /**
279 Enable or disable a single button on the bar.
280
281 @param button_id
282 ID of the button to enable or disable.
283 @param enable
284 @true to enable the button, @false to disable it.
285 */
286 virtual void EnableButton(int button_id, bool enable = true);
955bad41
PC
287
288 /**
289 Set a toggle button to the checked or unchecked state.
290
291 @param button_id
292 ID of the toggle button to manipulate.
293 @param checked
294 @true to set the button to the toggled/pressed/checked state,
295 @false to set it to the untoggled/unpressed/unchecked state.
296 */
297 virtual void ToggleButton(int button_id, bool checked);
3c3ead1d
PC
298};
299
300/**
301 @class wxRibbonButtonBarEvent
302
303 Event used to indicate various actions relating to a button on a
955bad41
PC
304 wxRibbonButtonBar. For toggle buttons, IsChecked() can be used to test
305 the state of the button.
3c3ead1d
PC
306
307 See wxRibbonButtonBar for available event types.
308
309 @library{wxribbon}
310 @category{events,ribbon}
311
312 @see wxRibbonBar
313*/
314class wxRibbonButtonBarEvent : public wxCommandEvent
315{
316public:
317 /**
318 Constructor.
319 */
320 wxRibbonButtonBarEvent(wxEventType command_type = wxEVT_NULL,
321 int win_id = 0,
322 wxRibbonButtonBar* bar = NULL);
323
324 /**
325 Returns the bar which contains the button which the event relates to.
326 */
327 wxRibbonButtonBar* GetBar();
328
329 /**
330 Sets the button bar relating to this event.
331 */
332 void SetBar(wxRibbonButtonBar* bar);
333
334 /**
335 Display a popup menu as a result of this (dropdown clicked) event.
336 */
337 bool PopupMenu(wxMenu* menu);
338};