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