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_CLICKED(id, func)}
34 Similar to EVT_RIBBONGALLERY_SELECTED but triggered every time a
35 gallery item is clicked, even if it is already selected. Note that the
36 ID of the event is that of the gallery, not of the item, just as above.
37 This event is available since wxWidgets 2.9.2.
38 @event{EVT_RIBBONGALLERY_HOVER_CHANGED(id, func)}
39 Triggered when the item being hovered over by the user changes. The
40 item in the event will be the new item being hovered, or NULL if there
41 is no longer an item being hovered. Note that the ID is that of the
42 gallery, not of the item.
44 @beginEventEmissionTable{wxCommandEvent}
45 @event{EVT_BUTTON(id, func)}
46 Triggered when the "extension" button of the gallery is pressed.
52 class wxRibbonGallery
: public wxRibbonControl
57 With this constructor, Create() should be called in order to create
63 Construct a ribbon gallery with the given parameters.
65 Parent window for the gallery (typically a wxRibbonPanel).
67 An identifier for the gallery. @c wxID_ANY is taken to mean a default.
69 Initial position of the gallery.
71 Initial size of the gallery.
73 Gallery style, currently unused.
75 wxRibbonGallery(wxWindow
* parent
,
76 wxWindowID id
= wxID_ANY
,
77 const wxPoint
& pos
= wxDefaultPosition
,
78 const wxSize
& size
= wxDefaultSize
,
84 virtual ~wxRibbonGallery();
87 Create a gallery in two-step gallery construction.
88 Should only be called when the default constructor is used, and
89 arguments have the same meaning as in the full constructor.
91 bool Create(wxWindow
* parent
,
92 wxWindowID id
= wxID_ANY
,
93 const wxPoint
& pos
= wxDefaultPosition
,
94 const wxSize
& size
= wxDefaultSize
,
98 Remove all items from the gallery.
103 Query if the gallery has no items in it.
105 bool IsEmpty() const;
108 Get the number of items in the gallery.
110 unsigned int GetCount() const;
113 Get an item by index.
115 wxRibbonGalleryItem
* GetItem(unsigned int n
);
118 Add an item to the gallery (with no client data).
120 The bitmap to display for the item. Note that all items must
121 have equally sized bitmaps.
123 ID number to associate with the item. Not currently used for
126 wxRibbonGalleryItem
* Append(const wxBitmap
& bitmap
, int id
);
129 Add an item to the gallery (with simple client data).
131 The bitmap to display for the item. Note that all items must
132 have equally sized bitmaps.
134 ID number to associate with the item. Not currently used for
137 An opaque pointer to associate with the item.
139 wxRibbonGalleryItem
* Append(const wxBitmap
& bitmap
, int id
, void* clientData
);
142 Add an item to the gallery (with complex client data)
144 The bitmap to display for the item. Note that all items must
145 have equally sized bitmaps.
147 ID number to associate with the item. Not currently used for
150 An object which contains data to associate with the item. The item
151 takes ownership of this pointer, and will delete it when the item
152 client data is changed to something else, or when the item is
155 wxRibbonGalleryItem
* Append(const wxBitmap
& bitmap
, int id
, wxClientData
* clientData
);
158 Set the client object associated with a gallery item.
160 void SetItemClientObject(wxRibbonGalleryItem
* item
, wxClientData
* data
);
163 Get the client object associated with a gallery item.
165 wxClientData
* GetItemClientObject(const wxRibbonGalleryItem
* item
) const;
168 Set the client data associated with a gallery item.
170 void SetItemClientData(wxRibbonGalleryItem
* item
, void* data
);
173 Get the client data associated with a gallery item.
175 void* GetItemClientData(const wxRibbonGalleryItem
* item
) const;
178 Set the selection to the given item, or removes the selection if
181 Note that this not cause any events to be emitted.
183 void SetSelection(wxRibbonGalleryItem
* item
);
186 Get the currently selected item, or NULL if there is none.
188 The selected item is set by SetSelection(), or by the user clicking on
191 wxRibbonGalleryItem
* GetSelection() const;
194 Get the currently hovered item, or NULL if there is none.
196 The hovered item is the item underneath the mouse cursor.
198 wxRibbonGalleryItem
* GetHoveredItem() const;
201 Get the currently active item, or NULL if there is none.
203 The active item is the item being pressed by the user, and will thus
204 become the selected item if the user releases the mouse button.
206 wxRibbonGalleryItem
* GetActiveItem() const;
209 Get the state of the scroll up button.
211 wxRibbonGalleryButtonState
GetUpButtonState() const;
214 Get the state of the scroll down button.
216 wxRibbonGalleryButtonState
GetDownButtonState() const;
219 Get the state of the "extension" button.
221 wxRibbonGalleryButtonState
GetExtensionButtonState() const;
224 Query is the mouse is currently hovered over the gallery.
226 @return @true if the cursor is within the bounds of the gallery (not
227 just hovering over an item), @false otherwise.
229 bool IsHovered() const;
232 Scroll the gallery contents by some amount.
235 Positive values scroll toward the end of the gallery, while negative
236 values scroll toward the start.
238 @return @true if the gallery scrolled at least one pixel in the given
239 direction, @false if it did not scroll.
241 virtual bool ScrollLines(int lines
);
244 Scroll the gallery to ensure that the given item is visible.
246 void EnsureVisible(const wxRibbonGalleryItem
* item
);
250 @class wxRibbonGalleryEvent
253 @category{events,ribbon}
257 class wxRibbonGalleryEvent
: public wxCommandEvent
263 wxRibbonGalleryEvent(wxEventType command_type
= wxEVT_NULL
,
265 wxRibbonGallery
* gallery
= NULL
,
266 wxRibbonGalleryItem
* item
= NULL
);
269 Returns the gallery which the event relates to.
271 wxRibbonGallery
* GetGallery();
274 Returns the gallery item which the event relates to, or NULL if it does
275 not relate to an item.
277 wxRibbonGalleryItem
* GetGalleryItem();
280 Sets the gallery relating to this event.
282 void SetGallery(wxRibbonGallery
* gallery
);
285 Sets the gallery item relating to this event.
287 void SetGalleryItem(wxRibbonGalleryItem
* item
);