1 ///////////////////////////////////////////////////////////////////////////////
2 // Name: ribbon/gallery.h
3 // Purpose: interface of wxRibbonGallery
4 // Author: Peter Cawley
6 // Licence: wxWindows licence
7 ///////////////////////////////////////////////////////////////////////////////
9 enum wxRibbonGalleryButtonState
11 wxRIBBON_GALLERY_BUTTON_NORMAL
,
12 wxRIBBON_GALLERY_BUTTON_HOVERED
,
13 wxRIBBON_GALLERY_BUTTON_ACTIVE
,
14 wxRIBBON_GALLERY_BUTTON_DISABLED
,
18 @class wxRibbonGallery
20 A ribbon gallery is like a wxListBox, but for bitmaps rather than strings.
21 It displays a collection of bitmaps arranged in a grid and allows the user
22 to choose one. As there are typically more bitmaps in a gallery than can
23 be displayed in the space used for a ribbon, a gallery always has scroll
24 buttons to allow the user to navigate through the entire gallery. It also
25 has an "extension" button, the behaviour of which is outside the scope of
26 the gallery control itself, though it typically displays some kind of
27 dialog related to the gallery.
29 @beginEventEmissionTable{wxRibbonGalleryEvent}
30 @event{EVT_RIBBONGALLERY_SELECTED(id, func)}
31 Triggered when the user selects an item from the gallery. Note that the
32 ID is that of the gallery, not of the item.
33 @event{EVT_RIBBONGALLERY_HOVER_CHANGED(id, func)}
34 Triggered when the item being hovered over by the user changes. The
35 item in the event will be the new item being hovered, or NULL if there
36 is no longer an item being hovered. Note that the ID is that of the
37 gallery, not of the item.
39 @beginEventEmissionTable{wxCommandEvent}
40 @event{EVT_BUTTON(id, func)}
41 Triggered when the "extension" button of the gallery is pressed.
47 class wxRibbonGallery
: public wxRibbonControl
52 With this constructor, Create() should be called in order to create
58 Construct a ribbon gallery with the given parameters.
60 Parent window for the gallery (typically a wxRibbonPanel).
62 An identifier for the gallery. @c wxID_ANY is taken to mean a default.
64 Initial position of the gallery.
66 Initial size of the gallery.
68 Gallery style, currently unused.
70 wxRibbonGallery(wxWindow
* parent
,
71 wxWindowID id
= wxID_ANY
,
72 const wxPoint
& pos
= wxDefaultPosition
,
73 const wxSize
& size
= wxDefaultSize
,
79 virtual ~wxRibbonGallery();
82 Create a gallery in two-step gallery construction.
83 Should only be called when the default constructor is used, and
84 arguments have the same meaning as in the full constructor.
86 bool Create(wxWindow
* parent
,
87 wxWindowID id
= wxID_ANY
,
88 const wxPoint
& pos
= wxDefaultPosition
,
89 const wxSize
& size
= wxDefaultSize
,
93 Remove all items from the gallery.
98 Query if the gallery has no items in it.
100 bool IsEmpty() const;
103 Get the number of items in the gallery.
105 unsigned int GetCount() const;
108 Get an item by index.
110 wxRibbonGalleryItem
* GetItem(unsigned int n
);
113 Add an item to the gallery (with no client data).
115 The bitmap to display for the item. Note that all items must
116 have equally sized bitmaps.
118 ID number to associate with the item. Not currently used for
121 wxRibbonGalleryItem
* Append(const wxBitmap
& bitmap
, int id
);
124 Add an item to the gallery (with simple client data).
126 The bitmap to display for the item. Note that all items must
127 have equally sized bitmaps.
129 ID number to associate with the item. Not currently used for
132 An opaque pointer to associate with the item.
134 wxRibbonGalleryItem
* Append(const wxBitmap
& bitmap
, int id
, void* clientData
);
137 Add an item to the gallery (with complex client data)
139 The bitmap to display for the item. Note that all items must
140 have equally sized bitmaps.
142 ID number to associate with the item. Not currently used for
145 An object which contains data to associate with the item. The item
146 takes ownership of this pointer, and will delete it when the item
147 client data is changed to something else, or when the item is
150 wxRibbonGalleryItem
* Append(const wxBitmap
& bitmap
, int id
, wxClientData
* clientData
);
153 Set the client object associated with a gallery item.
155 void SetItemClientObject(wxRibbonGalleryItem
* item
, wxClientData
* data
);
158 Get the client object associated with a gallery item.
160 wxClientData
* GetItemClientObject(const wxRibbonGalleryItem
* item
) const;
163 Set the client data associated with a gallery item.
165 void SetItemClientData(wxRibbonGalleryItem
* item
, void* data
);
168 Get the client data associated with a gallery item.
170 void* GetItemClientData(const wxRibbonGalleryItem
* item
) const;
173 Set the selection to the given item, or removes the selection if
176 Note that this not cause any events to be emitted.
178 void SetSelection(wxRibbonGalleryItem
* item
);
181 Get the currently selected item, or NULL if there is none.
183 The selected item is set by SetSelection(), or by the user clicking on
186 wxRibbonGalleryItem
* GetSelection() const;
189 Get the currently hovered item, or NULL if there is none.
191 The hovered item is the item underneath the mouse cursor.
193 wxRibbonGalleryItem
* GetHoveredItem() const;
196 Get the currently active item, or NULL if there is none.
198 The active item is the item being pressed by the user, and will thus
199 become the selected item if the user releases the mouse button.
201 wxRibbonGalleryItem
* GetActiveItem() const;
204 Get the state of the scroll up button.
206 wxRibbonGalleryButtonState
GetUpButtonState() const;
209 Get the state of the scroll down button.
211 wxRibbonGalleryButtonState
GetDownButtonState() const;
214 Get the state of the "extension" button.
216 wxRibbonGalleryButtonState
GetExtensionButtonState() const;
219 Query is the mouse is currently hovered over the gallery.
221 @return @true if the cursor is within the bounds of the gallery (not
222 just hovering over an item), @false otherwise.
224 bool IsHovered() const;
227 Scroll the gallery contents by some amount.
230 Positive values scroll toward the end of the gallery, while negative
231 values scroll toward the start.
233 @return @true if the gallery scrolled at least one pixel in the given
234 direction, @false if it did not scroll.
236 virtual bool ScrollLines(int lines
);
239 Scroll the gallery to ensure that the given item is visible.
241 void EnsureVisible(const wxRibbonGalleryItem
* item
);
245 @class wxRibbonGalleryEvent
248 @category{events,ribbon}
252 class wxRibbonButtonBarEvent
: public wxCommandEvent
258 wxRibbonButtonBarEvent(wxEventType command_type
= wxEVT_NULL
,
260 wxRibbonGallery
* gallery
= NULL
,
261 wxRibbonGalleryItem
* item
= NULL
);
264 Returns the gallery which the event relates to.
266 wxRibbonGallery
* GetGallery();
269 Returns the gallery item which the event relates to, or NULL if it does
270 not relate to an item.
272 wxRibbonGalleryItem
* GetGalleryItem();
275 Sets the gallery relating to this event.
277 void SetGallery(wxRibbonGallery
* gallery
);
280 Sets the gallery item relating to this event.
282 void SetGalleryItem(wxRibbonGalleryItem
* item
);