avoid infinite recursion for richtooltops, (hopefully) fixes #15070
[wxWidgets.git] / interface / wx / ribbon / gallery.h
0 / 300 (  0%)
CommitLineData
1///////////////////////////////////////////////////////////////////////////////
2// Name: ribbon/gallery.h
3// Purpose: interface of wxRibbonGallery
4// Author: Peter Cawley
5// RCS-ID: $Id$
6// Licence: wxWindows licence
7///////////////////////////////////////////////////////////////////////////////
8
9enum wxRibbonGalleryButtonState
10{
11 wxRIBBON_GALLERY_BUTTON_NORMAL,
12 wxRIBBON_GALLERY_BUTTON_HOVERED,
13 wxRIBBON_GALLERY_BUTTON_ACTIVE,
14 wxRIBBON_GALLERY_BUTTON_DISABLED,
15};
16
17/**
18 @class wxRibbonGallery
19
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.
28
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.
43 @endEventTable
44 @beginEventEmissionTable{wxCommandEvent}
45 @event{EVT_BUTTON(id, func)}
46 Triggered when the "extension" button of the gallery is pressed.
47 @endEventTable
48
49 @library{wxribbon}
50 @category{ribbon}
51*/
52class wxRibbonGallery : public wxRibbonControl
53{
54public:
55 /**
56 Default constructor.
57 With this constructor, Create() should be called in order to create
58 the gallery.
59 */
60 wxRibbonGallery();
61
62 /**
63 Construct a ribbon gallery with the given parameters.
64 @param parent
65 Parent window for the gallery (typically a wxRibbonPanel).
66 @param id
67 An identifier for the gallery. @c wxID_ANY is taken to mean a default.
68 @param pos
69 Initial position of the gallery.
70 @param size
71 Initial size of the gallery.
72 @param style
73 Gallery style, currently unused.
74 */
75 wxRibbonGallery(wxWindow* parent,
76 wxWindowID id = wxID_ANY,
77 const wxPoint& pos = wxDefaultPosition,
78 const wxSize& size = wxDefaultSize,
79 long style = 0);
80
81 /**
82 Destructor.
83 */
84 virtual ~wxRibbonGallery();
85
86 /**
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.
90 */
91 bool Create(wxWindow* parent,
92 wxWindowID id = wxID_ANY,
93 const wxPoint& pos = wxDefaultPosition,
94 const wxSize& size = wxDefaultSize,
95 long style = 0);
96
97 /**
98 Remove all items from the gallery.
99 */
100 void Clear();
101
102 /**
103 Query if the gallery has no items in it.
104 */
105 bool IsEmpty() const;
106
107 /**
108 Get the number of items in the gallery.
109 */
110 unsigned int GetCount() const;
111
112 /**
113 Get an item by index.
114 */
115 wxRibbonGalleryItem* GetItem(unsigned int n);
116
117 /**
118 Add an item to the gallery (with no client data).
119 @param bitmap
120 The bitmap to display for the item. Note that all items must
121 have equally sized bitmaps.
122 @param id
123 ID number to associate with the item. Not currently used for
124 anything important.
125 */
126 wxRibbonGalleryItem* Append(const wxBitmap& bitmap, int id);
127
128 /**
129 Add an item to the gallery (with simple client data).
130 @param bitmap
131 The bitmap to display for the item. Note that all items must
132 have equally sized bitmaps.
133 @param id
134 ID number to associate with the item. Not currently used for
135 anything important.
136 @param clientData
137 An opaque pointer to associate with the item.
138 */
139 wxRibbonGalleryItem* Append(const wxBitmap& bitmap, int id, void* clientData);
140
141 /**
142 Add an item to the gallery (with complex client data)
143 @param bitmap
144 The bitmap to display for the item. Note that all items must
145 have equally sized bitmaps.
146 @param id
147 ID number to associate with the item. Not currently used for
148 anything important.
149 @param clientData
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
153 destroyed.
154 */
155 wxRibbonGalleryItem* Append(const wxBitmap& bitmap, int id, wxClientData* clientData);
156
157 /**
158 Set the client object associated with a gallery item.
159 */
160 void SetItemClientObject(wxRibbonGalleryItem* item, wxClientData* data);
161
162 /**
163 Get the client object associated with a gallery item.
164 */
165 wxClientData* GetItemClientObject(const wxRibbonGalleryItem* item) const;
166
167 /**
168 Set the client data associated with a gallery item.
169 */
170 void SetItemClientData(wxRibbonGalleryItem* item, void* data);
171
172 /**
173 Get the client data associated with a gallery item.
174 */
175 void* GetItemClientData(const wxRibbonGalleryItem* item) const;
176
177 /**
178 Set the selection to the given item, or removes the selection if
179 @a item == NULL.
180
181 Note that this not cause any events to be emitted.
182 */
183 void SetSelection(wxRibbonGalleryItem* item);
184
185 /**
186 Get the currently selected item, or NULL if there is none.
187
188 The selected item is set by SetSelection(), or by the user clicking on
189 an item.
190 */
191 wxRibbonGalleryItem* GetSelection() const;
192
193 /**
194 Get the currently hovered item, or NULL if there is none.
195
196 The hovered item is the item underneath the mouse cursor.
197 */
198 wxRibbonGalleryItem* GetHoveredItem() const;
199
200 /**
201 Get the currently active item, or NULL if there is none.
202
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.
205 */
206 wxRibbonGalleryItem* GetActiveItem() const;
207
208 /**
209 Get the state of the scroll up button.
210 */
211 wxRibbonGalleryButtonState GetUpButtonState() const;
212
213 /**
214 Get the state of the scroll down button.
215 */
216 wxRibbonGalleryButtonState GetDownButtonState() const;
217
218 /**
219 Get the state of the "extension" button.
220 */
221 wxRibbonGalleryButtonState GetExtensionButtonState() const;
222
223 /**
224 Query is the mouse is currently hovered over the gallery.
225
226 @return @true if the cursor is within the bounds of the gallery (not
227 just hovering over an item), @false otherwise.
228 */
229 bool IsHovered() const;
230
231 /**
232 Scroll the gallery contents by some amount.
233
234 @param lines
235 Positive values scroll toward the end of the gallery, while negative
236 values scroll toward the start.
237
238 @return @true if the gallery scrolled at least one pixel in the given
239 direction, @false if it did not scroll.
240 */
241 virtual bool ScrollLines(int lines);
242
243 /**
244 Scroll the gallery contents by some fine-grained amount.
245
246 @param pixels
247 Positive values scroll toward the end of the gallery, while negative
248 values scroll toward the start.
249
250 @return @true if the gallery scrolled at least one pixel in the given
251 direction, @false if it did not scroll.
252 */
253 bool ScrollPixels(int pixels);
254
255 /**
256 Scroll the gallery to ensure that the given item is visible.
257 */
258 void EnsureVisible(const wxRibbonGalleryItem* item);
259};
260
261/**
262 @class wxRibbonGalleryEvent
263
264 @library{wxribbon}
265 @category{events,ribbon}
266
267 @see wxRibbonBar
268*/
269class wxRibbonGalleryEvent : public wxCommandEvent
270{
271public:
272 /**
273 Constructor.
274 */
275 wxRibbonGalleryEvent(wxEventType command_type = wxEVT_NULL,
276 int win_id = 0,
277 wxRibbonGallery* gallery = NULL,
278 wxRibbonGalleryItem* item = NULL);
279
280 /**
281 Returns the gallery which the event relates to.
282 */
283 wxRibbonGallery* GetGallery();
284
285 /**
286 Returns the gallery item which the event relates to, or NULL if it does
287 not relate to an item.
288 */
289 wxRibbonGalleryItem* GetGalleryItem();
290
291 /**
292 Sets the gallery relating to this event.
293 */
294 void SetGallery(wxRibbonGallery* gallery);
295
296 /**
297 Sets the gallery item relating to this event.
298 */
299 void SetGalleryItem(wxRibbonGalleryItem* item);
300};