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