interface/wx/ribbon/gallery.h

   1 ///////////////////////////////////////////////////////////////////////////////
   2 // Name:        ribbon/gallery.h
   3 // Purpose:     interface of wxRibbonGallery
   4 // Author:      Peter Cawley
   5 // Licence:     wxWindows licence
   6 ///////////////////////////////////////////////////////////////////////////////
   7
   8 enum wxRibbonGalleryButtonState
   9 {
  10     wxRIBBON_GALLERY_BUTTON_NORMAL,
  11     wxRIBBON_GALLERY_BUTTON_HOVERED,
  12     wxRIBBON_GALLERY_BUTTON_ACTIVE,
  13     wxRIBBON_GALLERY_BUTTON_DISABLED,
  14 };
  15
  16 /**
  17     @class wxRibbonGallery
  18
  19     A ribbon gallery is like a wxListBox, but for bitmaps rather than strings.
  20     It displays a collection of bitmaps arranged in a grid and allows the user
  21     to choose one. As there are typically more bitmaps in a gallery than can
  22     be displayed in the space used for a ribbon, a gallery always has scroll
  23     buttons to allow the user to navigate through the entire gallery. It also
  24     has an "extension" button, the behaviour of which is outside the scope of
  25     the gallery control itself, though it typically displays some kind of
  26     dialog related to the gallery.
  27
  28     @beginEventEmissionTable{wxRibbonGalleryEvent}
  29     @event{EVT_RIBBONGALLERY_SELECTED(id, func)}
  30         Triggered when the user selects an item from the gallery. Note that the
  31         ID is that of the gallery, not of the item.
  32     @event{EVT_RIBBONGALLERY_CLICKED(id, func)}
  33         Similar to EVT_RIBBONGALLERY_SELECTED but triggered every time a
  34         gallery item is clicked, even if it is already selected. Note that the
  35         ID of the event is that of the gallery, not of the item, just as above.
  36         This event is available since wxWidgets 2.9.2.
  37     @event{EVT_RIBBONGALLERY_HOVER_CHANGED(id, func)}
  38         Triggered when the item being hovered over by the user changes. The
  39         item in the event will be the new item being hovered, or NULL if there
  40         is no longer an item being hovered. Note that the ID is that of the
  41         gallery, not of the item.
  42     @endEventTable
  43     @beginEventEmissionTable{wxCommandEvent}
  44     @event{EVT_BUTTON(id, func)}
  45         Triggered when the "extension" button of the gallery is pressed.
  46     @endEventTable
  47
  48     @library{wxribbon}
  49     @category{ribbon}
  50 */
  51 class wxRibbonGallery : public wxRibbonControl
  52 {
  53 public:
  54     /**
  55         Default constructor.
  56         With this constructor, Create() should be called in order to create
  57         the gallery.
  58     */
  59     wxRibbonGallery();
  60
  61     /**
  62         Construct a ribbon gallery with the given parameters.
  63         @param parent
  64             Parent window for the gallery (typically a wxRibbonPanel).
  65         @param id
  66             An identifier for the gallery. @c wxID_ANY is taken to mean a default.
  67         @param pos
  68             Initial position of the gallery.
  69         @param size
  70             Initial size of the gallery.
  71         @param style
  72             Gallery style, currently unused.
  73     */
  74     wxRibbonGallery(wxWindow* parent,
  75                   wxWindowID id = wxID_ANY,
  76                   const wxPoint& pos = wxDefaultPosition,
  77                   const wxSize& size = wxDefaultSize,
  78                   long style = 0);
  79
  80     /**
  81         Destructor.
  82     */
  83     virtual ~wxRibbonGallery();
  84
  85     /**
  86         Create a gallery in two-step gallery construction.
  87         Should only be called when the default constructor is used, and
  88         arguments have the same meaning as in the full constructor.
  89     */
  90     bool Create(wxWindow* parent,
  91                 wxWindowID id = wxID_ANY,
  92                 const wxPoint& pos = wxDefaultPosition,
  93                 const wxSize& size = wxDefaultSize,
  94                 long style = 0);
  95
  96     /**
  97         Remove all items from the gallery.
  98     */
  99     void Clear();
 100
 101     /**
 102         Query if the gallery has no items in it.
 103     */
 104     bool IsEmpty() const;
 105
 106     /**
 107         Get the number of items in the gallery.
 108     */
 109     unsigned int GetCount() const;
 110
 111     /**
 112         Get an item by index.
 113     */
 114     wxRibbonGalleryItem* GetItem(unsigned int n);
 115
 116     /**
 117         Add an item to the gallery (with no client data).
 118         @param bitmap
 119             The bitmap to display for the item. Note that all items must
 120             have equally sized bitmaps.
 121         @param id
 122             ID number to associate with the item. Not currently used for
 123             anything important.
 124     */
 125     wxRibbonGalleryItem* Append(const wxBitmap& bitmap, int id);
 126
 127     /**
 128         Add an item to the gallery (with simple client data).
 129         @param bitmap
 130             The bitmap to display for the item. Note that all items must
 131             have equally sized bitmaps.
 132         @param id
 133             ID number to associate with the item. Not currently used for
 134             anything important.
 135         @param clientData
 136             An opaque pointer to associate with the item.
 137     */
 138     wxRibbonGalleryItem* Append(const wxBitmap& bitmap, int id, void* clientData);
 139
 140     /**
 141         Add an item to the gallery (with complex client data)
 142         @param bitmap
 143             The bitmap to display for the item. Note that all items must
 144             have equally sized bitmaps.
 145         @param id
 146             ID number to associate with the item. Not currently used for
 147             anything important.
 148         @param clientData
 149             An object which contains data to associate with the item. The item
 150             takes ownership of this pointer, and will delete it when the item
 151             client data is changed to something else, or when the item is
 152             destroyed.
 153     */
 154     wxRibbonGalleryItem* Append(const wxBitmap& bitmap, int id, wxClientData* clientData);
 155
 156     /**
 157         Set the client object associated with a gallery item.
 158     */
 159     void SetItemClientObject(wxRibbonGalleryItem* item, wxClientData* data);
 160
 161     /**
 162         Get the client object associated with a gallery item.
 163     */
 164     wxClientData* GetItemClientObject(const wxRibbonGalleryItem* item) const;
 165
 166     /**
 167         Set the client data associated with a gallery item.
 168     */
 169     void SetItemClientData(wxRibbonGalleryItem* item, void* data);
 170
 171     /**
 172         Get the client data associated with a gallery item.
 173     */
 174     void* GetItemClientData(const wxRibbonGalleryItem* item) const;
 175
 176     /**
 177         Set the selection to the given item, or removes the selection if
 178         @a item == NULL.
 179
 180         Note that this not cause any events to be emitted.
 181     */
 182     void SetSelection(wxRibbonGalleryItem* item);
 183
 184     /**
 185         Get the currently selected item, or NULL if there is none.
 186
 187         The selected item is set by SetSelection(), or by the user clicking on
 188         an item.
 189     */
 190     wxRibbonGalleryItem* GetSelection() const;
 191
 192     /**
 193         Get the currently hovered item, or NULL if there is none.
 194
 195         The hovered item is the item underneath the mouse cursor.
 196     */
 197     wxRibbonGalleryItem* GetHoveredItem() const;
 198
 199     /**
 200         Get the currently active item, or NULL if there is none.
 201
 202         The active item is the item being pressed by the user, and will thus
 203         become the selected item if the user releases the mouse button.
 204     */
 205     wxRibbonGalleryItem* GetActiveItem() const;
 206
 207     /**
 208         Get the state of the scroll up button.
 209     */
 210     wxRibbonGalleryButtonState GetUpButtonState() const;
 211
 212     /**
 213         Get the state of the scroll down button.
 214     */
 215     wxRibbonGalleryButtonState GetDownButtonState() const;
 216
 217     /**
 218         Get the state of the "extension" button.
 219     */
 220     wxRibbonGalleryButtonState GetExtensionButtonState() const;
 221
 222     /**
 223         Query is the mouse is currently hovered over the gallery.
 224
 225         @return @true if the cursor is within the bounds of the gallery (not
 226             just hovering over an item), @false otherwise.
 227     */
 228     bool IsHovered() const;
 229
 230     /**
 231         Scroll the gallery contents by some amount.
 232
 233         @param lines
 234           Positive values scroll toward the end of the gallery, while negative
 235           values scroll toward the start.
 236
 237         @return @true if the gallery scrolled at least one pixel in the given
 238             direction, @false if it did not scroll.
 239     */
 240     virtual bool ScrollLines(int lines);
 241
 242     /**
 243         Scroll the gallery contents by some fine-grained amount.
 244
 245         @param pixels
 246           Positive values scroll toward the end of the gallery, while negative
 247           values scroll toward the start.
 248
 249         @return @true if the gallery scrolled at least one pixel in the given
 250             direction, @false if it did not scroll.
 251     */
 252     bool ScrollPixels(int pixels);
 253
 254     /**
 255         Scroll the gallery to ensure that the given item is visible.
 256     */
 257     void EnsureVisible(const wxRibbonGalleryItem* item);
 258 };
 259
 260 /**
 261     @class wxRibbonGalleryEvent
 262
 263     @library{wxribbon}
 264     @category{events,ribbon}
 265
 266     @see wxRibbonBar
 267 */
 268 class wxRibbonGalleryEvent : public wxCommandEvent
 269 {
 270 public:
 271     /**
 272         Constructor.
 273     */
 274     wxRibbonGalleryEvent(wxEventType command_type = wxEVT_NULL,
 275                          int win_id = 0,
 276                          wxRibbonGallery* gallery = NULL,
 277                          wxRibbonGalleryItem* item = NULL);
 278
 279     /**
 280         Returns the gallery which the event relates to.
 281     */
 282     wxRibbonGallery* GetGallery();
 283
 284     /**
 285         Returns the gallery item which the event relates to, or NULL if it does
 286         not relate to an item.
 287     */
 288     wxRibbonGalleryItem* GetGalleryItem();
 289
 290     /**
 291         Sets the gallery relating to this event.
 292     */
 293     void SetGallery(wxRibbonGallery* gallery);
 294
 295     /**
 296         Sets the gallery item relating to this event.
 297     */
 298     void SetGalleryItem(wxRibbonGalleryItem* item);
 299 };