[wxWidgets.git] / interface / wx / ribbon / gallery.h

///////////////////////////////////////////////////////////////////////////////
// Name:        ribbon/gallery.h
// Purpose:     interface of wxRibbonGallery
// Author:      Peter Cawley
// RCS-ID:      $Id$
// Licence:     wxWindows licence
///////////////////////////////////////////////////////////////////////////////

enum wxRibbonGalleryButtonState
{
    wxRIBBON_GALLERY_BUTTON_NORMAL,
    wxRIBBON_GALLERY_BUTTON_HOVERED,
    wxRIBBON_GALLERY_BUTTON_ACTIVE,
    wxRIBBON_GALLERY_BUTTON_DISABLED,
};

/**
    @class wxRibbonGallery
    
    A ribbon gallery is like a wxListBox, but for bitmaps rather than strings.
    It displays a collection of bitmaps arranged in a grid and allows the user
    to choose one. As there are typically more bitmaps in a gallery than can
    be displayed in the space used for a ribbon, a gallery always has scroll
    buttons to allow the user to navigate through the entire gallery. It also
    has an "extension" button, the behaviour of which is outside the scope of
    the gallery control itself, though it typically displays some kind of
    dialog related to the gallery.
    
    @beginEventEmissionTable{wxRibbonGalleryEvent}
    @event{EVT_RIBBONGALLERY_SELECTED(id, func)}
        Triggered when the user selects an item from the gallery. Note that the
        ID is that of the gallery, not of the item.
    @event{EVT_RIBBONGALLERY_HOVER_CHANGED(id, func)}
        Triggered when the item being hovered over by the user changes. The
        item in the event will be the new item being hovered, or NULL if there
        is no longer an item being hovered. Note that the ID is that of the
        gallery, not of the item.
    @endEventTable
    @beginEventEmissionTable{wxCommandEvent}
    @event{EVT_BUTTON(id, func)}
        Triggered when the "extension" button of the gallery is pressed.
    @endEventTable

    @library{wxribbon}
    @category{ribbon}
*/
class wxRibbonGallery : public wxRibbonControl
{
public:
    /**
        Default constructor.
        With this constructor, Create() should be called in order to create
        the gallery.
    */
    wxRibbonGallery();

    /**
        Construct a ribbon gallery with the given parameters.
        @param parent
            Parent window for the gallery (typically a wxRibbonPanel).
        @param id
            An identifier for the gallery. @c wxID_ANY is taken to mean a default.
        @param pos
            Initial position of the gallery.
        @param size
            Initial size of the gallery.
        @param style
            Gallery style, currently unused.
    */
    wxRibbonGallery(wxWindow* parent,
                  wxWindowID id = wxID_ANY,
                  const wxPoint& pos = wxDefaultPosition,
                  const wxSize& size = wxDefaultSize,
                  long style = 0);

    /**
        Destructor.
    */
    virtual ~wxRibbonGallery();

    /**
        Create a gallery in two-step gallery construction.
        Should only be called when the default constructor is used, and
        arguments have the same meaning as in the full constructor.
    */
    bool Create(wxWindow* parent,
                wxWindowID id = wxID_ANY,
                const wxPoint& pos = wxDefaultPosition,
                const wxSize& size = wxDefaultSize,
                long style = 0);

    /**
        Remove all items from the gallery.
    */
    void Clear();

    /**
        Query if the gallery has no items in it.
    */
    bool IsEmpty() const;
    
    /**
        Get the number of items in the gallery.
    */
    unsigned int GetCount() const;
    
    /**
        Get an item by index.
    */
    wxRibbonGalleryItem* GetItem(unsigned int n);
    
    /**
        Add an item to the gallery (with no client data).
        @param bitmap
            The bitmap to display for the item. Note that all items must
            have equally sized bitmaps.
        @param id
            ID number to associate with the item. Not currently used for
            anything important.
    */
    wxRibbonGalleryItem* Append(const wxBitmap& bitmap, int id);
    
    /**
        Add an item to the gallery (with simple client data).
        @param bitmap
            The bitmap to display for the item. Note that all items must
            have equally sized bitmaps.
        @param id
            ID number to associate with the item. Not currently used for
            anything important.
        @param clientData
            An opaque pointer to associate with the item.
    */
    wxRibbonGalleryItem* Append(const wxBitmap& bitmap, int id, void* clientData);
    
    /**
        Add an item to the gallery (with complex client data)
        @param bitmap
            The bitmap to display for the item. Note that all items must
            have equally sized bitmaps.
        @param id
            ID number to associate with the item. Not currently used for
            anything important.
        @param clientData
            An object which contains data to associate with the item. The item
            takes ownership of this pointer, and will delete it when the item
            client data is changed to something else, or when the item is
            destroyed.
    */
    wxRibbonGalleryItem* Append(const wxBitmap& bitmap, int id, wxClientData* clientData);

    /**
        Set the client object associated with a gallery item.
    */
    void SetItemClientObject(wxRibbonGalleryItem* item, wxClientData* data);
    
    /**
        Get the client object associated with a gallery item.
    */
    wxClientData* GetItemClientObject(const wxRibbonGalleryItem* item) const;
    
    /**
        Set the client data associated with a gallery item.
    */
    void SetItemClientData(wxRibbonGalleryItem* item, void* data);
    
    /**
        Get the client data associated with a gallery item.
    */
    void* GetItemClientData(const wxRibbonGalleryItem* item) const;

    /**
        Set the selection to the given item, or removes the selection if
        @a item == NULL.
        
        Note that this not cause any events to be emitted.
    */
    void SetSelection(wxRibbonGalleryItem* item);

    /**
        Get the currently selected item, or NULL if there is none.
        
        The selected item is set by SetSelection(), or by the user clicking on
        an item.
    */
    wxRibbonGalleryItem* GetSelection() const;
    
    /**
        Get the currently hovered item, or NULL if there is none.
        
        The hovered item is the item underneath the mouse cursor.
    */
    wxRibbonGalleryItem* GetHoveredItem() const;
    
    /**
        Get the currently active item, or NULL if there is none.
        
        The active item is the item being pressed by the user, and will thus
        become the selected item if the user releases the mouse button.
    */
    wxRibbonGalleryItem* GetActiveItem() const;
    
    /**
        Get the state of the scroll up button.
    */
    wxRibbonGalleryButtonState GetUpButtonState() const;
    
    /**
        Get the state of the scroll down button.
    */
    wxRibbonGalleryButtonState GetDownButtonState() const;
    
    /**
        Get the state of the "extension" button.
    */
    wxRibbonGalleryButtonState GetExtensionButtonState() const;

    /**
        Query is the mouse is currently hovered over the gallery.
        
        @return @true if the cursor is within the bounds of the gallery (not
            just hovering over an item), @false otherwise.
    */
    bool IsHovered() const;
    
    /**
        Scroll the gallery contents by some amount.
        
        @param lines
          Positive values scroll toward the end of the gallery, while negative
          values scroll toward the start.
    
        @return @true if the gallery scrolled at least one pixel in the given
            direction, @false if it did not scroll.
    */
    virtual bool ScrollLines(int lines);
    
    /**
        Scroll the gallery to ensure that the given item is visible.
    */
    void EnsureVisible(const wxRibbonGalleryItem* item);
};

/**
    @class wxRibbonGalleryEvent

    @library{wxribbon}
    @category{events,ribbon}

    @see wxRibbonBar
*/
class wxRibbonGalleryEvent : public wxCommandEvent
{
public:
    /**
        Constructor.
    */
    wxRibbonGalleryEvent(wxEventType command_type = wxEVT_NULL,
                         int win_id = 0,
                         wxRibbonGallery* gallery = NULL,
                         wxRibbonGalleryItem* item = NULL);

    /**
        Returns the gallery which the event relates to.
    */
    wxRibbonGallery* GetGallery();
    
    /**
        Returns the gallery item which the event relates to, or NULL if it does
        not relate to an item.
    */
    wxRibbonGalleryItem* GetGalleryItem();
        
    /**
        Sets the gallery relating to this event.
    */
    void SetGallery(wxRibbonGallery* gallery);
    
    /**
        Sets the gallery item relating to this event.
    */
    void SetGalleryItem(wxRibbonGalleryItem* item);
};
Commit	Line	Data
3c3ead1d PC	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).
69aa257b FM	61	@param id
69aa257b FM	62	An identifier for the gallery. @c wxID_ANY is taken to mean a default.
3c3ead1d PC	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	*/
dc735b40	252	class wxRibbonGalleryEvent : public wxCommandEvent
3c3ead1d PC	253	{
	254	public:
	255	/**
	256	Constructor.
	257	*/
dc735b40 FM	258	wxRibbonGalleryEvent(wxEventType command_type = wxEVT_NULL,
	259	int win_id = 0,
	260	wxRibbonGallery* gallery = NULL,
	261	wxRibbonGalleryItem* item = NULL);
3c3ead1d PC	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	};