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

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

/**
    Flags for button bar button size and state.
    
    Buttons on a ribbon button bar can each come in three sizes: small, medium,
    and large. In some places this is called the size class, and the term size
    used for the pixel width and height associated with a particular size
    class.
    
    A button can also be in zero or more hovered or active states, or in the
    disabled state.
*/
enum wxRibbonButtonBarButtonState
{
    /**
        Button is small (the interpretation of small is dependant upon the art
        provider, but it will be smaller than medium).
    */
    wxRIBBON_BUTTONBAR_BUTTON_SMALL     = 0 << 0,
    
    /**
        Button is medium sized (the interpretation of medium is dependant upon
        the art provider, but it will be between small and large).
    */
    wxRIBBON_BUTTONBAR_BUTTON_MEDIUM    = 1 << 0,
    
    /**
        Button is large (the interpretation of large is dependant upon the art
        provider, but it will be larger than medium).
    */
    wxRIBBON_BUTTONBAR_BUTTON_LARGE     = 2 << 0,
    
    /**
        A mask to extract button size from a combination of flags.
    */
    wxRIBBON_BUTTONBAR_BUTTON_SIZE_MASK = 3 << 0,

    /**
        The normal (non-dropdown) region of the button is being hovered over by
        the mouse cursor. Only applicable to normal and hybrid buttons.
    */
    wxRIBBON_BUTTONBAR_BUTTON_NORMAL_HOVERED    = 1 << 3,
    
    /**
        The dropdown region of the button is being hovered over by the mouse
        cursor. Only applicable to dropdown and hybrid buttons.
    */
    wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_HOVERED  = 1 << 4,
    
    /**
        A mask to extract button hover state from a combination of flags.
    */
    wxRIBBON_BUTTONBAR_BUTTON_HOVER_MASK        = wxRIBBON_BUTTONBAR_BUTTON_NORMAL_HOVERED | wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_HOVERED,
    
    /**
        The normal (non-dropdown) region of the button is being pressed.
        Only applicable to normal and hybrid buttons.
    */
    wxRIBBON_BUTTONBAR_BUTTON_NORMAL_ACTIVE     = 1 << 5,
    
    /**
        The dropdown region of the button is being pressed.
        Only applicable to dropdown and hybrid buttons.
    */
    wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_ACTIVE   = 1 << 6,
    
    /**
        The button is disabled. Hover flags may still be set when a button
        is disabled, but should be ignored during drawing if the button is
        disabled.
    */
    wxRIBBON_BUTTONBAR_BUTTON_DISABLED          = 1 << 7,
    
    /**
        A mask to extract button state from a combination of flags.
    */
    wxRIBBON_BUTTONBAR_BUTTON_STATE_MASK        = 0xF8,
};

/**
    @class wxRibbonButtonBar
    
    A ribbon button bar is similar to a traditional toolbar. It contains one or
    more buttons (button bar buttons, not wxButtons), each of which has a label
    and an icon. It differs from a wxRibbonToolBar in several ways:
      @li Individual buttons can grow and contract.
      @li Buttons have labels as well as bitmaps.
      @li Bitmaps are typically larger (at least 32x32 pixels) on a button bar
        compared to a tool bar (which typically has 16x15).
      @li There is no grouping of buttons on a button bar
      @li A button bar typically has a border around each individual button,
        whereas a tool bar typically has a border around each group of buttons.
    
    @beginEventEmissionTable{wxRibbonButtonBarEvent}
    @event{EVT_RIBBONBUTTONBAR_CLICKED(id, func)}
        Triggered when the normal (non-dropdown) region of a button on the
        button bar is clicked.
    @event{EVT_RIBBONBUTTONBAR_DROPDOWN_CLICKED(id, func)}
        Triggered when the dropdown region of a button on the button bar is
        clicked. wxRibbonButtonBarEvent::PopupMenu() should be called by the
        event handler if it wants to display a popup menu (which is what most
        dropdown buttons should be doing).
    @endEventTable
    
    @library{wxribbon}
    @category{ribbon}
*/
class wxRibbonButtonBar : public wxRibbonControl
{
public:
    /**
        Default constructor.
        With this constructor, Create() should be called in order to create
        the button bar.
    */
    wxRibbonButtonBar();

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

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

    /**
        Create a button bar in two-step button bar 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);

    /**
        Add a button to the button bar (simple version).
    */
    virtual wxRibbonButtonBarButtonBase* AddButton(
                int button_id,
                const wxString& label,
                const wxBitmap& bitmap,
                const wxString& help_string,
                wxRibbonButtonBarButtonKind kind = wxRIBBON_BUTTONBAR_BUTTON_NORMAL);

    /**
        Add a dropdown button to the button bar (simple version).
        
        @see AddButton()
    */
    virtual wxRibbonButtonBarButtonBase* AddDropdownButton(
                int button_id,
                const wxString& label,
                const wxBitmap& bitmap,
                const wxString& help_string = wxEmptyString);

    /**
        Add a hybrid button to the button bar (simple version).
        
        @see AddButton()
    */
    virtual wxRibbonButtonBarButtonBase* AddHybridButton(
                int button_id,
                const wxString& label,
                const wxBitmap& bitmap,
                const wxString& help_string = wxEmptyString);
    
    /**
        Add a button to the button bar.
        
        @param button_id
            ID of the new button (used for event callbacks).
        @param label
            Label of the new button.
        @param bitmap
            Large bitmap of the new button. Must be the same size as all other
            large bitmaps used on the button bar.
        @param bitmap_small
            Small bitmap of the new button. If left as null, then a small
            bitmap will be automatically generated. Must be the same size as
            all other small bitmaps used on the button bar.
        @param bitmap_disabled
            Large bitmap of the new button when it is disabled. If left as
            null, then a bitmap will be automatically generated from @a bitmap.
        @param bitmap_small_disabled
            Small bitmap of the new button when it is disabled. If left as
            null, then a bitmap will be automatically generated from @a
            bitmap_small.
        @param kind
            The kind of button to add.
        @param help_string
            The UI help string to associate with the new button.
        @param client_data
            Client data to associate with the new button.
        
        @return An opaque pointer which can be used only with other button bar
            methods.
            
        @see AddDropdownButton()
        @see AddHybridButton()
    */
    virtual wxRibbonButtonBarButtonBase* AddButton(
                int button_id,
                const wxString& label,
                const wxBitmap& bitmap,
                const wxBitmap& bitmap_small = wxNullBitmap,
                const wxBitmap& bitmap_disabled = wxNullBitmap,
                const wxBitmap& bitmap_small_disabled = wxNullBitmap,
                wxRibbonButtonBarButtonKind kind = wxRIBBON_BUTTONBAR_BUTTON_NORMAL,
                const wxString& help_string = wxEmptyString,
                wxObject* client_data = NULL);

    /**
        Calculate button layouts and positions.
        
        Must be called after buttons are added to the button bar, as otherwise
        the newly added buttons will not be displayed. In normal situations, it
        will be called automatically when wxRibbonBar::Realize() is called.
    */
    virtual bool Realize();
    
    /**
        Delete all buttons from the button bar.
        
        @see DeleteButton()
    */
    virtual void ClearButtons();
    
    /**
        Delete a single button from the button bar.
        
        @see ClearButtons()
    */
    virtual bool DeleteButton(int button_id);
    
    /**
        Enable or disable a single button on the bar.
        
        @param button_id
            ID of the button to enable or disable.
        @param enable
            @true to enable the button, @false to disable it.
    */
    virtual void EnableButton(int button_id, bool enable = true);
};

/**
    @class wxRibbonButtonBarEvent

    Event used to indicate various actions relating to a button on a
    wxRibbonButtonBar.

    See wxRibbonButtonBar for available event types.

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

    @see wxRibbonBar
*/
class wxRibbonButtonBarEvent : public wxCommandEvent
{
public:
    /**
        Constructor.
    */
    wxRibbonButtonBarEvent(wxEventType command_type = wxEVT_NULL,
                       int win_id = 0,
                       wxRibbonButtonBar* bar = NULL);

    /**
        Returns the bar which contains the button which the event relates to.
    */
    wxRibbonButtonBar* GetBar();
        
    /**
        Sets the button bar relating to this event.
    */
    void SetBar(wxRibbonButtonBar* bar);
    
    /**
        Display a popup menu as a result of this (dropdown clicked) event.
    */
    bool PopupMenu(wxMenu* menu);
};
Commit	Line	Data
3c3ead1d PC	1	///////////////////////////////////////////////////////////////////////////////
	2	// Name: ribbon/buttonbar.h
	3	// Purpose: interface of wxRibbonButtonBar
	4	// Author: Peter Cawley
	5	// RCS-ID: $Id$
	6	// Licence: wxWindows licence
	7	///////////////////////////////////////////////////////////////////////////////
	8
	9	/**
	10	Flags for button bar button size and state.
	11
	12	Buttons on a ribbon button bar can each come in three sizes: small, medium,
	13	and large. In some places this is called the size class, and the term size
	14	used for the pixel width and height associated with a particular size
	15	class.
	16
	17	A button can also be in zero or more hovered or active states, or in the
	18	disabled state.
	19	*/
	20	enum wxRibbonButtonBarButtonState
	21	{
	22	/**
	23	Button is small (the interpretation of small is dependant upon the art
	24	provider, but it will be smaller than medium).
	25	*/
	26	wxRIBBON_BUTTONBAR_BUTTON_SMALL = 0 << 0,
	27
	28	/**
	29	Button is medium sized (the interpretation of medium is dependant upon
	30	the art provider, but it will be between small and large).
	31	*/
	32	wxRIBBON_BUTTONBAR_BUTTON_MEDIUM = 1 << 0,
	33
	34	/**
	35	Button is large (the interpretation of large is dependant upon the art
	36	provider, but it will be larger than medium).
	37	*/
	38	wxRIBBON_BUTTONBAR_BUTTON_LARGE = 2 << 0,
	39
	40	/**
	41	A mask to extract button size from a combination of flags.
	42	*/
	43	wxRIBBON_BUTTONBAR_BUTTON_SIZE_MASK = 3 << 0,
	44
	45	/**
	46	The normal (non-dropdown) region of the button is being hovered over by
	47	the mouse cursor. Only applicable to normal and hybrid buttons.
	48	*/
	49	wxRIBBON_BUTTONBAR_BUTTON_NORMAL_HOVERED = 1 << 3,
	50
	51	/**
	52	The dropdown region of the button is being hovered over by the mouse
	53	cursor. Only applicable to dropdown and hybrid buttons.
	54	*/
	55	wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_HOVERED = 1 << 4,
	56
	57	/**
	58	A mask to extract button hover state from a combination of flags.
	59	*/
	60	wxRIBBON_BUTTONBAR_BUTTON_HOVER_MASK = wxRIBBON_BUTTONBAR_BUTTON_NORMAL_HOVERED \| wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_HOVERED,
	61
	62	/**
	63	The normal (non-dropdown) region of the button is being pressed.
	64	Only applicable to normal and hybrid buttons.
65	*/
66	wxRIBBON_BUTTONBAR_BUTTON_NORMAL_ACTIVE = 1 << 5,
67
68	/**
69	The dropdown region of the button is being pressed.
70	Only applicable to dropdown and hybrid buttons.
71	*/
72	wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_ACTIVE = 1 << 6,
73
74	/**
75	The button is disabled. Hover flags may still be set when a button
76	is disabled, but should be ignored during drawing if the button is
77	disabled.
78	*/
79	wxRIBBON_BUTTONBAR_BUTTON_DISABLED = 1 << 7,
80
81	/**
82	A mask to extract button state from a combination of flags.
83	*/
84	wxRIBBON_BUTTONBAR_BUTTON_STATE_MASK = 0xF8,
85	};
86
87	/**
88	@class wxRibbonButtonBar
89
90	A ribbon button bar is similar to a traditional toolbar. It contains one or
91	more buttons (button bar buttons, not wxButtons), each of which has a label
92	and an icon. It differs from a wxRibbonToolBar in several ways:
93	@li Individual buttons can grow and contract.
94	@li Buttons have labels as well as bitmaps.
95	@li Bitmaps are typically larger (at least 32x32 pixels) on a button bar
96	compared to a tool bar (which typically has 16x15).
97	@li There is no grouping of buttons on a button bar
98	@li A button bar typically has a border around each individual button,
99	whereas a tool bar typically has a border around each group of buttons.
100
101	@beginEventEmissionTable{wxRibbonButtonBarEvent}
102	@event{EVT_RIBBONBUTTONBAR_CLICKED(id, func)}
103	Triggered when the normal (non-dropdown) region of a button on the
104	button bar is clicked.
105	@event{EVT_RIBBONBUTTONBAR_DROPDOWN_CLICKED(id, func)}
106	Triggered when the dropdown region of a button on the button bar is
107	clicked. wxRibbonButtonBarEvent::PopupMenu() should be called by the
108	event handler if it wants to display a popup menu (which is what most
109	dropdown buttons should be doing).
110	@endEventTable
111
112	@library{wxribbon}
113	@category{ribbon}
114	*/
115	class wxRibbonButtonBar : public wxRibbonControl
116	{
117	public:
118	/**
119	Default constructor.
120	With this constructor, Create() should be called in order to create
121	the button bar.
122	*/
123	wxRibbonButtonBar();
124
125	/**
126	Construct a ribbon button bar with the given parameters.
69aa257b	127
3c3ead1d PC	128	@param parent
3c3ead1d PC	129	Parent window for the button bar (typically a wxRibbonPanel).
69aa257b FM	130	@param id
69aa257b FM	131	An identifier for the button bar. @c wxID_ANY is taken to mean a default.
3c3ead1d PC	132	@param pos
	133	Initial position of the button bar.
	134	@param size
	135	Initial size of the button bar.
	136	@param style
	137	Button bar style, currently unused.
	138	*/
	139	wxRibbonButtonBar(wxWindow* parent,
	140	wxWindowID id = wxID_ANY,
	141	const wxPoint& pos = wxDefaultPosition,
	142	const wxSize& size = wxDefaultSize,
	143	long style = 0);
	144
	145	/**
	146	Destructor.
	147	*/
	148	virtual ~wxRibbonButtonBar();
	149
	150	/**
	151	Create a button bar in two-step button bar construction.
	152	Should only be called when the default constructor is used, and
	153	arguments have the same meaning as in the full constructor.
	154	*/
	155	bool Create(wxWindow* parent,
	156	wxWindowID id = wxID_ANY,
	157	const wxPoint& pos = wxDefaultPosition,
	158	const wxSize& size = wxDefaultSize,
	159	long style = 0);
	160
	161	/**
	162	Add a button to the button bar (simple version).
	163	*/
	164	virtual wxRibbonButtonBarButtonBase* AddButton(
	165	int button_id,
	166	const wxString& label,
	167	const wxBitmap& bitmap,
	168	const wxString& help_string,
	169	wxRibbonButtonBarButtonKind kind = wxRIBBON_BUTTONBAR_BUTTON_NORMAL);
	170
	171	/**
	172	Add a dropdown button to the button bar (simple version).
	173
	174	@see AddButton()
	175	*/
	176	virtual wxRibbonButtonBarButtonBase* AddDropdownButton(
	177	int button_id,
	178	const wxString& label,
	179	const wxBitmap& bitmap,
	180	const wxString& help_string = wxEmptyString);
	181
	182	/**
	183	Add a hybrid button to the button bar (simple version).
	184
	185	@see AddButton()
	186	*/
	187	virtual wxRibbonButtonBarButtonBase* AddHybridButton(
	188	int button_id,
	189	const wxString& label,
	190	const wxBitmap& bitmap,
	191	const wxString& help_string = wxEmptyString);
	192
	193	/**
	194	Add a button to the button bar.
	195
196	@param button_id
197	ID of the new button (used for event callbacks).
198	@param label
199	Label of the new button.
200	@param bitmap
201	Large bitmap of the new button. Must be the same size as all other
202	large bitmaps used on the button bar.
203	@param bitmap_small
204	Small bitmap of the new button. If left as null, then a small
205	bitmap will be automatically generated. Must be the same size as
206	all other small bitmaps used on the button bar.
207	@param bitmap_disabled
208	Large bitmap of the new button when it is disabled. If left as
209	null, then a bitmap will be automatically generated from @a bitmap.
210	@param bitmap_small_disabled
211	Small bitmap of the new button when it is disabled. If left as
212	null, then a bitmap will be automatically generated from @a
213	bitmap_small.
214	@param kind
215	The kind of button to add.
216	@param help_string
217	The UI help string to associate with the new button.
218	@param client_data
219	Client data to associate with the new button.
220
221	@return An opaque pointer which can be used only with other button bar
222	methods.
223
224	@see AddDropdownButton()
225	@see AddHybridButton()
226	*/
227	virtual wxRibbonButtonBarButtonBase* AddButton(
228	int button_id,
229	const wxString& label,
230	const wxBitmap& bitmap,
231	const wxBitmap& bitmap_small = wxNullBitmap,
232	const wxBitmap& bitmap_disabled = wxNullBitmap,
233	const wxBitmap& bitmap_small_disabled = wxNullBitmap,
234	wxRibbonButtonBarButtonKind kind = wxRIBBON_BUTTONBAR_BUTTON_NORMAL,
235	const wxString& help_string = wxEmptyString,
236	wxObject* client_data = NULL);
237
238	/**
239	Calculate button layouts and positions.
240
241	Must be called after buttons are added to the button bar, as otherwise
242	the newly added buttons will not be displayed. In normal situations, it
243	will be called automatically when wxRibbonBar::Realize() is called.
244	*/
245	virtual bool Realize();
246
247	/**
248	Delete all buttons from the button bar.
249
250	@see DeleteButton()
251	*/
252	virtual void ClearButtons();
253
254	/**
255	Delete a single button from the button bar.
256
257	@see ClearButtons()
258	*/
259	virtual bool DeleteButton(int button_id);
260
261	/**
262	Enable or disable a single button on the bar.
263
264	@param button_id
265	ID of the button to enable or disable.
266	@param enable
267	@true to enable the button, @false to disable it.
268	*/
269	virtual void EnableButton(int button_id, bool enable = true);
270	};
271
272	/**
273	@class wxRibbonButtonBarEvent
274
275	Event used to indicate various actions relating to a button on a
276	wxRibbonButtonBar.
277
278	See wxRibbonButtonBar for available event types.
279
280	@library{wxribbon}
281	@category{events,ribbon}
282
283	@see wxRibbonBar
284	*/
285	class wxRibbonButtonBarEvent : public wxCommandEvent
286	{
287	public:
288	/**
289	Constructor.
290	*/
291	wxRibbonButtonBarEvent(wxEventType command_type = wxEVT_NULL,
292	int win_id = 0,
293	wxRibbonButtonBar* bar = NULL);
294
295	/**
296	Returns the bar which contains the button which the event relates to.
297	*/
298	wxRibbonButtonBar* GetBar();
299
300	/**
301	Sets the button bar relating to this event.
302	*/
303	void SetBar(wxRibbonButtonBar* bar);
304
305	/**
306	Display a popup menu as a result of this (dropdown clicked) event.
307	*/
308	bool PopupMenu(wxMenu* menu);
309	};