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