| 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 | |
| 9 | enum 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 | */ |
| 52 | class wxRibbonGallery : public wxRibbonControl |
| 53 | { |
| 54 | public: |
| 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 | */ |
| 269 | class wxRibbonGalleryEvent : public wxCommandEvent |
| 270 | { |
| 271 | public: |
| 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 | }; |