]> git.saurik.com Git - wxWidgets.git/blame - interface/wx/ribbon/buttonbar.h
Use wxString::t_str() in calls to Windows API functions in wxMSW.
[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 /**
8cddee2d 23 Button is small (the interpretation of small is dependent upon the art
3c3ead1d
PC
24 provider, but it will be smaller than medium).
25 */
26 wxRIBBON_BUTTONBAR_BUTTON_SMALL = 0 << 0,
27
28 /**
8cddee2d 29 Button is medium sized (the interpretation of medium is dependent upon
3c3ead1d
PC
30 the art provider, but it will be between small and large).
31 */
32 wxRIBBON_BUTTONBAR_BUTTON_MEDIUM = 1 << 0,
33
34 /**
8cddee2d 35 Button is large (the interpretation of large is dependent upon the art
3c3ead1d
PC
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,
c9069ea3 174 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);
3c3ead1d
PC
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,
c9069ea3 251 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
3c3ead1d
PC
252 const wxString& help_string = wxEmptyString,
253 wxObject* client_data = NULL);
254
ff4cb916
VZ
255 /**
256 Inserts a button to the button bar (simple version) at the given position.
257
258 @see AddButton()
259
260 @since 2.9.4
261 */
262 virtual wxRibbonButtonBarButtonBase* InsertButton(
263 size_t pos,
264 int button_id,
265 const wxString& label,
266 const wxBitmap& bitmap,
267 const wxString& help_string,
c9069ea3 268 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);
ff4cb916
VZ
269
270 /**
271 Inserts a dropdown button to the button bar (simple version) at the
272 given position.
273
274 @see InsertButton()
275 @see AddDropdownButton()
276 @see AddButton()
277
278 @since 2.9.4
279 */
280 virtual wxRibbonButtonBarButtonBase* InsertDropdownButton(
281 size_t pos,
282 int button_id,
283 const wxString& label,
284 const wxBitmap& bitmap,
285 const wxString& help_string = wxEmptyString);
286
287 /**
288 Inserts a hybrid button to the button bar (simple version) at the given
289 position.
290
291 @see InsertButton()
292 @see AddHybridButton()
293 @see AddButton()
294
295 @since 2.9.4
296 */
297 virtual wxRibbonButtonBarButtonBase* InsertHybridButton(
298 size_t pos,
299 int button_id,
300 const wxString& label,
301 const wxBitmap& bitmap,
302 const wxString& help_string = wxEmptyString);
303
304 /**
305 Inserts a toggle button to the button bar (simple version) at the given
306 position.
307
308 @see InsertButton()
309 @see AddToggleButton()
310 @see AddButton()
311
312 @since 2.9.4
313 */
314 virtual wxRibbonButtonBarButtonBase* InsertToggleButton(
315 size_t pos,
316 int button_id,
317 const wxString& label,
318 const wxBitmap& bitmap,
319 const wxString& help_string = wxEmptyString);
320
321 /**
322 Insert a button to the button bar at the given position.
323
324 @param pos
325 Position of the new button in the button bar.
326 @param button_id
327 ID of the new button (used for event callbacks).
328 @param label
329 Label of the new button.
330 @param bitmap
331 Large bitmap of the new button. Must be the same size as all other
332 large bitmaps used on the button bar.
333 @param bitmap_small
334 Small bitmap of the new button. If left as null, then a small
335 bitmap will be automatically generated. Must be the same size as
336 all other small bitmaps used on the button bar.
337 @param bitmap_disabled
338 Large bitmap of the new button when it is disabled. If left as
339 null, then a bitmap will be automatically generated from @a bitmap.
340 @param bitmap_small_disabled
341 Small bitmap of the new button when it is disabled. If left as
342 null, then a bitmap will be automatically generated from @a
343 bitmap_small.
344 @param kind
345 The kind of button to add.
346 @param help_string
347 The UI help string to associate with the new button.
348 @param client_data
349 Client data to associate with the new button.
350
351 @return An opaque pointer which can be used only with other button bar
352 methods.
353
354 @see InsertDropdownButton()
355 @see InsertHybridButton()
356 @see InsertToggleButton()
357 @see AddButton()
358
359 @since 2.9.4
360 */
361 virtual wxRibbonButtonBarButtonBase* InsertButton(
362 size_t pos,
363 int button_id,
364 const wxString& label,
365 const wxBitmap& bitmap,
366 const wxBitmap& bitmap_small = wxNullBitmap,
367 const wxBitmap& bitmap_disabled = wxNullBitmap,
368 const wxBitmap& bitmap_small_disabled = wxNullBitmap,
c9069ea3 369 wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
ff4cb916
VZ
370 const wxString& help_string = wxEmptyString,
371 wxObject* client_data = NULL);
372
373 /**
374 Returns the number of buttons in this button bar.
375
376 @since 2.9.4
377 */
378 virtual size_t GetButtonCount() const;
379
3c3ead1d
PC
380 /**
381 Calculate button layouts and positions.
382
383 Must be called after buttons are added to the button bar, as otherwise
384 the newly added buttons will not be displayed. In normal situations, it
385 will be called automatically when wxRibbonBar::Realize() is called.
386 */
387 virtual bool Realize();
388
389 /**
390 Delete all buttons from the button bar.
391
392 @see DeleteButton()
393 */
394 virtual void ClearButtons();
395
396 /**
397 Delete a single button from the button bar.
398
399 @see ClearButtons()
400 */
401 virtual bool DeleteButton(int button_id);
402
403 /**
404 Enable or disable a single button on the bar.
405
406 @param button_id
407 ID of the button to enable or disable.
408 @param enable
409 @true to enable the button, @false to disable it.
410 */
411 virtual void EnableButton(int button_id, bool enable = true);
955bad41
PC
412
413 /**
414 Set a toggle button to the checked or unchecked state.
415
416 @param button_id
417 ID of the toggle button to manipulate.
418 @param checked
419 @true to set the button to the toggled/pressed/checked state,
420 @false to set it to the untoggled/unpressed/unchecked state.
421 */
422 virtual void ToggleButton(int button_id, bool checked);
3c3ead1d
PC
423};
424
425/**
426 @class wxRibbonButtonBarEvent
427
428 Event used to indicate various actions relating to a button on a
955bad41
PC
429 wxRibbonButtonBar. For toggle buttons, IsChecked() can be used to test
430 the state of the button.
3c3ead1d
PC
431
432 See wxRibbonButtonBar for available event types.
433
434 @library{wxribbon}
435 @category{events,ribbon}
436
437 @see wxRibbonBar
438*/
439class wxRibbonButtonBarEvent : public wxCommandEvent
440{
441public:
442 /**
443 Constructor.
444 */
445 wxRibbonButtonBarEvent(wxEventType command_type = wxEVT_NULL,
446 int win_id = 0,
447 wxRibbonButtonBar* bar = NULL);
448
449 /**
450 Returns the bar which contains the button which the event relates to.
451 */
452 wxRibbonButtonBar* GetBar();
453
454 /**
455 Sets the button bar relating to this event.
456 */
457 void SetBar(wxRibbonButtonBar* bar);
458
459 /**
460 Display a popup menu as a result of this (dropdown clicked) event.
461 */
462 bool PopupMenu(wxMenu* menu);
463};