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

///////////////////////////////////////////////////////////////////////////////
// Name:        ribbon/buttonbar.h
// Purpose:     interface of wxRibbonButtonBar
// Author:      Peter Cawley
// 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 dependent 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 dependent 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 dependent 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,
    
    /**
        The button is a toggle button which is currently in the toggled state.
    */
    wxRIBBON_BUTTONBAR_BUTTON_TOGGLED           = 1 << 8,
    
    /**
        A mask to extract button state from a combination of flags.
    */
    wxRIBBON_BUTTONBAR_BUTTON_STATE_MASK        = 0x1F8,
};

/**
    @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,
                wxRibbonButtonKind kind = wxRIBBON_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 toggle button to the button bar (simple version).
        
        @see AddButton()
    */
    virtual wxRibbonButtonBarButtonBase* AddToggleButton(
                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.
        
        @return An opaque pointer which can be used only with other button bar
            methods.
            
        @see AddDropdownButton()
        @see AddHybridButton()
        @see AddToggleButton()
    */
    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,
                wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
                const wxString& help_string = wxEmptyString);

    /**
        Inserts a button to the button bar (simple version) at the given position.

        @see AddButton()

        @since 2.9.4
    */
    virtual wxRibbonButtonBarButtonBase* InsertButton(
                size_t pos,
                int button_id,
                const wxString& label,
                const wxBitmap& bitmap,
                const wxString& help_string,
                wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);

    /**
        Inserts a dropdown button to the button bar (simple version) at the
            given position.

        @see InsertButton()
        @see AddDropdownButton()
        @see AddButton()

        @since 2.9.4
    */
    virtual wxRibbonButtonBarButtonBase* InsertDropdownButton(
                size_t pos,
                int button_id,
                const wxString& label,
                const wxBitmap& bitmap,
                const wxString& help_string = wxEmptyString);

    /**
        Inserts a hybrid button to the button bar (simple version) at the given
            position.

        @see InsertButton()
        @see AddHybridButton()
        @see AddButton()

        @since 2.9.4
    */
    virtual wxRibbonButtonBarButtonBase* InsertHybridButton(
                size_t pos,
                int button_id,
                const wxString& label,
                const wxBitmap& bitmap,
                const wxString& help_string = wxEmptyString);

    /**
        Inserts a toggle button to the button bar (simple version) at the given
            position.

        @see InsertButton()
        @see AddToggleButton()
        @see AddButton()

        @since 2.9.4
    */
    virtual wxRibbonButtonBarButtonBase* InsertToggleButton(
                size_t pos,
                int button_id,
                const wxString& label,
                const wxBitmap& bitmap,
                const wxString& help_string = wxEmptyString);

    /**
        Insert a button to the button bar at the given position.

        @param pos
            Position of the new button in 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.

        @return An opaque pointer which can be used only with other button bar
            methods.

        @see InsertDropdownButton()
        @see InsertHybridButton()
        @see InsertToggleButton()
        @see AddButton()

        @since 2.9.4
    */
    virtual wxRibbonButtonBarButtonBase* InsertButton(
                size_t pos,
                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,
                wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
                const wxString& help_string = wxEmptyString);

    /**
        Returns the number of buttons in this button bar.

        @since 2.9.4
    */
    virtual size_t GetButtonCount() const;

    /**
        Set the client object associated with a button. The button bar
        owns the given object and takes care of its deletion.
        Please, note that you cannot use both client object and client data.

        @since 2.9.5
    */
    void SetItemClientObject(wxRibbonButtonBarButtonBase* item, wxClientData* data);

    /**
        Get the client object associated with a button.

        @since 2.9.5
    */
    wxClientData* GetItemClientObject(const wxRibbonButtonBarButtonBase* item) const;

    /**
        Set the client data associated with a button.
        Please, note that you cannot use both client object and client data.

        @since 2.9.5
    */
    void SetItemClientData(wxRibbonButtonBarButtonBase* item, void* data);

    /**
        Get the client data associated with a button.

        @since 2.9.5
    */
    void* GetItemClientData(const wxRibbonButtonBarButtonBase* item) const;

    /**
        Returns the N-th button of the bar.

        @see GetButtonCount()

        @since 2.9.5
    */
    virtual wxRibbonButtonBarButtonBase *GetItem(size_t n) const;

    /**
        Returns the first button having a given id or NULL if none matches.

        @since 2.9.5
    */
    virtual wxRibbonButtonBarButtonBase *GetItemById(int id) const;

    /**
        Returns the id of a button.

        @since 2.9.5
    */
    virtual int GetItemId(wxRibbonButtonBarButtonBase *) const;

    /**
        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);
    
    /**
        Set a toggle button to the checked or unchecked state.
        
        @param button_id
            ID of the toggle button to manipulate.
        @param checked
            @true to set the button to the toggled/pressed/checked state,
            @false to set it to the untoggled/unpressed/unchecked state.
    */
    virtual void ToggleButton(int button_id, bool checked);

    /**
        Returns the active item of the button bar or NULL if there is none.
        The active button is the one being clicked.

        @since 2.9.5
    */
    virtual wxRibbonButtonBarButtonBase *GetActiveItem() const;

    /**
        Returns the hovered item of the button bar or NULL if there is none.
        The hovered button is the one the mouse is over.

        @since 2.9.5
    */
    virtual wxRibbonButtonBarButtonBase *GetHoveredItem() const;

    /**
        Indicates whether tooltips are shown for disabled buttons.

        By default they are not shown.

        @since 2.9.5
    */
    void SetShowToolTipsForDisabled(bool show);

    /**
        Sets whether tooltips should be shown for disabled buttons or not.

        You may wish to show it to explain why a button is disabled or
        what it normally does when enabled.

        @since 2.9.5
    */
    bool GetShowToolTipsForDisabled() const;

};

/**
    @class wxRibbonButtonBarEvent

    Event used to indicate various actions relating to a button on a
    wxRibbonButtonBar. For toggle buttons, IsChecked() can be used to test
    the state of the button.

    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,
                       wxRibbonButtonBarButtonBase* button = 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);
    
    /**
        Returns the button which the event relates to.

        @since 2.9.5
    */
    wxRibbonButtonBarButtonBase* GetButton();

    /**
        Sets the button relating to this event.

        @since 2.9.5
    */
    void SetButton(wxRibbonButtonBarButtonBase* 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
3c3ead1d PC	5	// Licence: wxWindows licence
	6	///////////////////////////////////////////////////////////////////////////////
	7
	8	/**
	9	Flags for button bar button size and state.
	10
	11	Buttons on a ribbon button bar can each come in three sizes: small, medium,
	12	and large. In some places this is called the size class, and the term size
	13	used for the pixel width and height associated with a particular size
	14	class.
	15
	16	A button can also be in zero or more hovered or active states, or in the
	17	disabled state.
	18	*/
	19	enum wxRibbonButtonBarButtonState
	20	{
	21	/**
8cddee2d	22	Button is small (the interpretation of small is dependent upon the art
3c3ead1d PC	23	provider, but it will be smaller than medium).
	24	*/
	25	wxRIBBON_BUTTONBAR_BUTTON_SMALL = 0 << 0,
	26
	27	/**
8cddee2d	28	Button is medium sized (the interpretation of medium is dependent upon
3c3ead1d PC	29	the art provider, but it will be between small and large).
	30	*/
	31	wxRIBBON_BUTTONBAR_BUTTON_MEDIUM = 1 << 0,
	32
	33	/**
8cddee2d	34	Button is large (the interpretation of large is dependent upon the art
3c3ead1d PC	35	provider, but it will be larger than medium).
	36	*/
	37	wxRIBBON_BUTTONBAR_BUTTON_LARGE = 2 << 0,
	38
	39	/**
	40	A mask to extract button size from a combination of flags.
	41	*/
	42	wxRIBBON_BUTTONBAR_BUTTON_SIZE_MASK = 3 << 0,
	43
	44	/**
	45	The normal (non-dropdown) region of the button is being hovered over by
	46	the mouse cursor. Only applicable to normal and hybrid buttons.
	47	*/
	48	wxRIBBON_BUTTONBAR_BUTTON_NORMAL_HOVERED = 1 << 3,
	49
	50	/**
	51	The dropdown region of the button is being hovered over by the mouse
	52	cursor. Only applicable to dropdown and hybrid buttons.
	53	*/
	54	wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_HOVERED = 1 << 4,
	55
	56	/**
	57	A mask to extract button hover state from a combination of flags.
	58	*/
	59	wxRIBBON_BUTTONBAR_BUTTON_HOVER_MASK = wxRIBBON_BUTTONBAR_BUTTON_NORMAL_HOVERED \| wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_HOVERED,
	60
	61	/**
	62	The normal (non-dropdown) region of the button is being pressed.
	63	Only applicable to normal and hybrid buttons.
	64	*/
	65	wxRIBBON_BUTTONBAR_BUTTON_NORMAL_ACTIVE = 1 << 5,
	66
	67	/**
	68	The dropdown region of the button is being pressed.
	69	Only applicable to dropdown and hybrid buttons.
	70	*/
	71	wxRIBBON_BUTTONBAR_BUTTON_DROPDOWN_ACTIVE = 1 << 6,
	72
	73	/**
	74	The button is disabled. Hover flags may still be set when a button
	75	is disabled, but should be ignored during drawing if the button is
	76	disabled.
	77	*/
	78	wxRIBBON_BUTTONBAR_BUTTON_DISABLED = 1 << 7,
	79
955bad41 PC	80	/**
	81	The button is a toggle button which is currently in the toggled state.
	82	*/
	83	wxRIBBON_BUTTONBAR_BUTTON_TOGGLED = 1 << 8,
	84
3c3ead1d PC	85	/**
	86	A mask to extract button state from a combination of flags.
	87	*/
955bad41	88	wxRIBBON_BUTTONBAR_BUTTON_STATE_MASK = 0x1F8,
3c3ead1d PC	89	};
	90
	91	/**
	92	@class wxRibbonButtonBar
	93
	94	A ribbon button bar is similar to a traditional toolbar. It contains one or
	95	more buttons (button bar buttons, not wxButtons), each of which has a label
	96	and an icon. It differs from a wxRibbonToolBar in several ways:
	97	@li Individual buttons can grow and contract.
	98	@li Buttons have labels as well as bitmaps.
	99	@li Bitmaps are typically larger (at least 32x32 pixels) on a button bar
	100	compared to a tool bar (which typically has 16x15).
	101	@li There is no grouping of buttons on a button bar
	102	@li A button bar typically has a border around each individual button,
	103	whereas a tool bar typically has a border around each group of buttons.
	104
	105	@beginEventEmissionTable{wxRibbonButtonBarEvent}
	106	@event{EVT_RIBBONBUTTONBAR_CLICKED(id, func)}
	107	Triggered when the normal (non-dropdown) region of a button on the
	108	button bar is clicked.
	109	@event{EVT_RIBBONBUTTONBAR_DROPDOWN_CLICKED(id, func)}
	110	Triggered when the dropdown region of a button on the button bar is
	111	clicked. wxRibbonButtonBarEvent::PopupMenu() should be called by the
	112	event handler if it wants to display a popup menu (which is what most
	113	dropdown buttons should be doing).
	114	@endEventTable
	115
	116	@library{wxribbon}
	117	@category{ribbon}
	118	*/
	119	class wxRibbonButtonBar : public wxRibbonControl
	120	{
	121	public:
	122	/**
	123	Default constructor.
	124	With this constructor, Create() should be called in order to create
	125	the button bar.
	126	*/
	127	wxRibbonButtonBar();
	128
	129	/**
	130	Construct a ribbon button bar with the given parameters.
69aa257b	131
3c3ead1d PC	132	@param parent
3c3ead1d PC	133	Parent window for the button bar (typically a wxRibbonPanel).
69aa257b FM	134	@param id
69aa257b FM	135	An identifier for the button bar. @c wxID_ANY is taken to mean a default.
3c3ead1d PC	136	@param pos
	137	Initial position of the button bar.
	138	@param size
	139	Initial size of the button bar.
	140	@param style
	141	Button bar style, currently unused.
	142	*/
	143	wxRibbonButtonBar(wxWindow* parent,
	144	wxWindowID id = wxID_ANY,
	145	const wxPoint& pos = wxDefaultPosition,
	146	const wxSize& size = wxDefaultSize,
	147	long style = 0);
	148
	149	/**
	150	Destructor.
	151	*/
	152	virtual ~wxRibbonButtonBar();
	153
	154	/**
	155	Create a button bar in two-step button bar construction.
	156	Should only be called when the default constructor is used, and
	157	arguments have the same meaning as in the full constructor.
	158	*/
	159	bool Create(wxWindow* parent,
	160	wxWindowID id = wxID_ANY,
	161	const wxPoint& pos = wxDefaultPosition,
	162	const wxSize& size = wxDefaultSize,
	163	long style = 0);
	164
	165	/**
	166	Add a button to the button bar (simple version).
	167	*/
	168	virtual wxRibbonButtonBarButtonBase* AddButton(
	169	int button_id,
	170	const wxString& label,
	171	const wxBitmap& bitmap,
	172	const wxString& help_string,
c9069ea3	173	wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);
3c3ead1d PC	174
	175	/**
	176	Add a dropdown button to the button bar (simple version).
	177
	178	@see AddButton()
	179	*/
	180	virtual wxRibbonButtonBarButtonBase* AddDropdownButton(
	181	int button_id,
	182	const wxString& label,
	183	const wxBitmap& bitmap,
	184	const wxString& help_string = wxEmptyString);
	185
	186	/**
	187	Add a hybrid button to the button bar (simple version).
	188
	189	@see AddButton()
	190	*/
	191	virtual wxRibbonButtonBarButtonBase* AddHybridButton(
	192	int button_id,
	193	const wxString& label,
	194	const wxBitmap& bitmap,
	195	const wxString& help_string = wxEmptyString);
	196
955bad41 PC	197	/**
	198	Add a toggle button to the button bar (simple version).
	199
	200	@see AddButton()
	201	*/
	202	virtual wxRibbonButtonBarButtonBase* AddToggleButton(
	203	int button_id,
	204	const wxString& label,
	205	const wxBitmap& bitmap,
	206	const wxString& help_string = wxEmptyString);
	207
3c3ead1d PC	208	/**
	209	Add a button to the button bar.
	210
	211	@param button_id
	212	ID of the new button (used for event callbacks).
	213	@param label
	214	Label of the new button.
	215	@param bitmap
	216	Large bitmap of the new button. Must be the same size as all other
	217	large bitmaps used on the button bar.
	218	@param bitmap_small
	219	Small bitmap of the new button. If left as null, then a small
	220	bitmap will be automatically generated. Must be the same size as
	221	all other small bitmaps used on the button bar.
	222	@param bitmap_disabled
	223	Large bitmap of the new button when it is disabled. If left as
	224	null, then a bitmap will be automatically generated from @a bitmap.
	225	@param bitmap_small_disabled
	226	Small bitmap of the new button when it is disabled. If left as
	227	null, then a bitmap will be automatically generated from @a
	228	bitmap_small.
	229	@param kind
	230	The kind of button to add.
	231	@param help_string
	232	The UI help string to associate with the new button.
3c3ead1d PC	233
	234	@return An opaque pointer which can be used only with other button bar
	235	methods.
	236
	237	@see AddDropdownButton()
	238	@see AddHybridButton()
955bad41	239	@see AddToggleButton()
3c3ead1d PC	240	*/
	241	virtual wxRibbonButtonBarButtonBase* AddButton(
	242	int button_id,
	243	const wxString& label,
	244	const wxBitmap& bitmap,
	245	const wxBitmap& bitmap_small = wxNullBitmap,
	246	const wxBitmap& bitmap_disabled = wxNullBitmap,
	247	const wxBitmap& bitmap_small_disabled = wxNullBitmap,
c9069ea3	248	wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
652aa936	249	const wxString& help_string = wxEmptyString);
3c3ead1d	250
ff4cb916 VZ	251	/**
	252	Inserts a button to the button bar (simple version) at the given position.
	253
	254	@see AddButton()
	255
	256	@since 2.9.4
	257	*/
	258	virtual wxRibbonButtonBarButtonBase* InsertButton(
	259	size_t pos,
	260	int button_id,
	261	const wxString& label,
	262	const wxBitmap& bitmap,
	263	const wxString& help_string,
c9069ea3	264	wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);
ff4cb916 VZ	265
	266	/**
	267	Inserts a dropdown button to the button bar (simple version) at the
	268	given position.
	269
	270	@see InsertButton()
	271	@see AddDropdownButton()
	272	@see AddButton()
	273
	274	@since 2.9.4
	275	*/
	276	virtual wxRibbonButtonBarButtonBase* InsertDropdownButton(
	277	size_t pos,
	278	int button_id,
	279	const wxString& label,
	280	const wxBitmap& bitmap,
	281	const wxString& help_string = wxEmptyString);
	282
	283	/**
	284	Inserts a hybrid button to the button bar (simple version) at the given
	285	position.
	286
	287	@see InsertButton()
	288	@see AddHybridButton()
	289	@see AddButton()
	290
	291	@since 2.9.4
	292	*/
	293	virtual wxRibbonButtonBarButtonBase* InsertHybridButton(
	294	size_t pos,
	295	int button_id,
	296	const wxString& label,
	297	const wxBitmap& bitmap,
	298	const wxString& help_string = wxEmptyString);
	299
	300	/**
	301	Inserts a toggle button to the button bar (simple version) at the given
	302	position.
	303
	304	@see InsertButton()
	305	@see AddToggleButton()
	306	@see AddButton()
	307
	308	@since 2.9.4
	309	*/
	310	virtual wxRibbonButtonBarButtonBase* InsertToggleButton(
	311	size_t pos,
	312	int button_id,
	313	const wxString& label,
	314	const wxBitmap& bitmap,
	315	const wxString& help_string = wxEmptyString);
	316
	317	/**
	318	Insert a button to the button bar at the given position.
	319
	320	@param pos
	321	Position of the new button in the button bar.
	322	@param button_id
	323	ID of the new button (used for event callbacks).
	324	@param label
	325	Label of the new button.
	326	@param bitmap
	327	Large bitmap of the new button. Must be the same size as all other
	328	large bitmaps used on the button bar.
329	@param bitmap_small
330	Small bitmap of the new button. If left as null, then a small
331	bitmap will be automatically generated. Must be the same size as
332	all other small bitmaps used on the button bar.
333	@param bitmap_disabled
334	Large bitmap of the new button when it is disabled. If left as
335	null, then a bitmap will be automatically generated from @a bitmap.
336	@param bitmap_small_disabled
337	Small bitmap of the new button when it is disabled. If left as
338	null, then a bitmap will be automatically generated from @a
339	bitmap_small.
340	@param kind
341	The kind of button to add.
342	@param help_string
343	The UI help string to associate with the new button.
ff4cb916 VZ	344
	345	@return An opaque pointer which can be used only with other button bar
	346	methods.
	347
	348	@see InsertDropdownButton()
	349	@see InsertHybridButton()
	350	@see InsertToggleButton()
	351	@see AddButton()
	352
	353	@since 2.9.4
	354	*/
	355	virtual wxRibbonButtonBarButtonBase* InsertButton(
	356	size_t pos,
	357	int button_id,
	358	const wxString& label,
	359	const wxBitmap& bitmap,
	360	const wxBitmap& bitmap_small = wxNullBitmap,
	361	const wxBitmap& bitmap_disabled = wxNullBitmap,
	362	const wxBitmap& bitmap_small_disabled = wxNullBitmap,
c9069ea3	363	wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
652aa936	364	const wxString& help_string = wxEmptyString);
ff4cb916 VZ	365
	366	/**
	367	Returns the number of buttons in this button bar.
	368
	369	@since 2.9.4
	370	*/
	371	virtual size_t GetButtonCount() const;
	372
652aa936 VZ	373	/**
	374	Set the client object associated with a button. The button bar
	375	owns the given object and takes care of its deletion.
	376	Please, note that you cannot use both client object and client data.
	377
	378	@since 2.9.5
	379	*/
	380	void SetItemClientObject(wxRibbonButtonBarButtonBase* item, wxClientData* data);
	381
	382	/**
	383	Get the client object associated with a button.
	384
	385	@since 2.9.5
	386	*/
	387	wxClientData* GetItemClientObject(const wxRibbonButtonBarButtonBase* item) const;
	388
	389	/**
	390	Set the client data associated with a button.
	391	Please, note that you cannot use both client object and client data.
	392
	393	@since 2.9.5
	394	*/
	395	void SetItemClientData(wxRibbonButtonBarButtonBase* item, void* data);
	396
	397	/**
	398	Get the client data associated with a button.
	399
	400	@since 2.9.5
	401	*/
	402	void* GetItemClientData(const wxRibbonButtonBarButtonBase* item) const;
	403
71a77e77 VZ	404	/**
	405	Returns the N-th button of the bar.
	406
	407	@see GetButtonCount()
	408
	409	@since 2.9.5
	410	*/
	411	virtual wxRibbonButtonBarButtonBase *GetItem(size_t n) const;
	412
	413	/**
	414	Returns the first button having a given id or NULL if none matches.
	415
	416	@since 2.9.5
	417	*/
	418	virtual wxRibbonButtonBarButtonBase *GetItemById(int id) const;
	419
	420	/**
	421	Returns the id of a button.
	422
	423	@since 2.9.5
	424	*/
	425	virtual int GetItemId(wxRibbonButtonBarButtonBase *) const;
	426
3c3ead1d PC	427	/**
	428	Calculate button layouts and positions.
	429
	430	Must be called after buttons are added to the button bar, as otherwise
	431	the newly added buttons will not be displayed. In normal situations, it
	432	will be called automatically when wxRibbonBar::Realize() is called.
	433	*/
	434	virtual bool Realize();
	435
	436	/**
	437	Delete all buttons from the button bar.
	438
	439	@see DeleteButton()
	440	*/
	441	virtual void ClearButtons();
	442
	443	/**
	444	Delete a single button from the button bar.
	445
	446	@see ClearButtons()
	447	*/
	448	virtual bool DeleteButton(int button_id);
	449
	450	/**
	451	Enable or disable a single button on the bar.
	452
	453	@param button_id
	454	ID of the button to enable or disable.
	455	@param enable
	456	@true to enable the button, @false to disable it.
	457	*/
	458	virtual void EnableButton(int button_id, bool enable = true);
955bad41 PC	459
	460	/**
	461	Set a toggle button to the checked or unchecked state.
	462
	463	@param button_id
	464	ID of the toggle button to manipulate.
	465	@param checked
	466	@true to set the button to the toggled/pressed/checked state,
	467	@false to set it to the untoggled/unpressed/unchecked state.
	468	*/
	469	virtual void ToggleButton(int button_id, bool checked);
02a40ac1 VZ	470
	471	/**
	472	Returns the active item of the button bar or NULL if there is none.
	473	The active button is the one being clicked.
	474
	475	@since 2.9.5
	476	*/
	477	virtual wxRibbonButtonBarButtonBase *GetActiveItem() const;
	478
	479	/**
	480	Returns the hovered item of the button bar or NULL if there is none.
	481	The hovered button is the one the mouse is over.
	482
	483	@since 2.9.5
	484	*/
	485	virtual wxRibbonButtonBarButtonBase *GetHoveredItem() const;
	486
40df8a51 VZ	487	/**
	488	Indicates whether tooltips are shown for disabled buttons.
	489
	490	By default they are not shown.
	491
	492	@since 2.9.5
	493	*/
	494	void SetShowToolTipsForDisabled(bool show);
	495
	496	/**
	497	Sets whether tooltips should be shown for disabled buttons or not.
	498
	499	You may wish to show it to explain why a button is disabled or
	500	what it normally does when enabled.
	501
	502	@since 2.9.5
	503	*/
	504	bool GetShowToolTipsForDisabled() const;
	505
3c3ead1d PC	506	};
	507
	508	/**
	509	@class wxRibbonButtonBarEvent
	510
	511	Event used to indicate various actions relating to a button on a
955bad41 PC	512	wxRibbonButtonBar. For toggle buttons, IsChecked() can be used to test
955bad41 PC	513	the state of the button.
3c3ead1d PC	514
	515	See wxRibbonButtonBar for available event types.
	516
	517	@library{wxribbon}
	518	@category{events,ribbon}
	519
	520	@see wxRibbonBar
	521	*/
	522	class wxRibbonButtonBarEvent : public wxCommandEvent
	523	{
	524	public:
	525	/**
	526	Constructor.
	527	*/
	528	wxRibbonButtonBarEvent(wxEventType command_type = wxEVT_NULL,
	529	int win_id = 0,
7f08b828 VZ	530	wxRibbonButtonBar* bar = NULL,
7f08b828 VZ	531	wxRibbonButtonBarButtonBase* button = NULL);
3c3ead1d PC	532
	533	/**
	534	Returns the bar which contains the button which the event relates to.
	535	*/
	536	wxRibbonButtonBar* GetBar();
	537
	538	/**
	539	Sets the button bar relating to this event.
	540	*/
	541	void SetBar(wxRibbonButtonBar* bar);
	542
7f08b828 VZ	543	/**
	544	Returns the button which the event relates to.
	545
	546	@since 2.9.5
	547	*/
	548	wxRibbonButtonBarButtonBase* GetButton();
	549
	550	/**
	551	Sets the button relating to this event.
	552
	553	@since 2.9.5
	554	*/
	555	void SetButton(wxRibbonButtonBarButtonBase* bar);
	556
3c3ead1d PC	557	/**
	558	Display a popup menu as a result of this (dropdown clicked) event.
	559	*/
	560	bool PopupMenu(wxMenu* menu);
	561	};