interface/wx/ribbon/gallery.h

   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 };