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

///////////////////////////////////////////////////////////////////////////////
// Name:        ribbon/toolbar.h
// Purpose:     interface of wxRibbonToolBar
// Author:      Peter Cawley
// Licence:     wxWindows licence
///////////////////////////////////////////////////////////////////////////////

/**
    @class wxRibbonToolBar
    
    A ribbon tool bar is similar to a traditional toolbar which has no labels.
    It contains one or more tool groups, each of which contains one or more
    tools. Each tool is represented by a (generally small, i.e. 16x15) bitmap.
    
    @beginEventEmissionTable{wxRibbonToolBarEvent}
    @event{EVT_RIBBONTOOLBAR_CLICKED(id, func)}
        Triggered when the normal (non-dropdown) region of a tool on the tool
        bar is clicked.
    @event{EVT_RIBBONTOOLBAR_DROPDOWN_CLICKED(id, func)}
        Triggered when the dropdown region of a tool on the tool bar is
        clicked. wxRibbonToolBarEvent::PopupMenu() should be called by the
        event handler if it wants to display a popup menu (which is what most
        dropdown tools should be doing).
    @endEventTable
    
    @library{wxribbon}
    @category{ribbon}
*/
class wxRibbonToolBar : public wxRibbonControl
{
public:
    /**
        Default constructor.
        With this constructor, Create() should be called in order to create
        the tool bar.
    */
    wxRibbonToolBar();

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

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

    /**
        Create a tool bar in two-step tool 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 tool to the tool bar (simple version).
    */
    virtual wxRibbonToolBarToolBase* AddTool(
                int tool_id,
                const wxBitmap& bitmap,
                const wxString& help_string,
                wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);

    /**
        Add a dropdown tool to the tool bar (simple version).
        
        @see AddTool()
    */
    virtual wxRibbonToolBarToolBase* AddDropdownTool(
                int tool_id,
                const wxBitmap& bitmap,
                const wxString& help_string = wxEmptyString);

    /**
        Add a hybrid tool to the tool bar (simple version).
        
        @see AddTool()
    */
    virtual wxRibbonToolBarToolBase* AddHybridTool(
                int tool_id,
                const wxBitmap& bitmap,
                const wxString& help_string = wxEmptyString);

    /**
        Add a toggle tool to the tool bar (simple version).

        @since 2.9.4

        @see AddTool()
    */
    virtual wxRibbonToolBarToolBase* AddToggleTool(
        int tool_id,
        const wxBitmap& bitmap,
        const wxString& help_string);

    /**
        Add a tool to the tool bar.
        
        @param tool_id
            ID of the new tool (used for event callbacks).
        @param bitmap
            Bitmap to use as the foreground for the new tool. Does not have
            to be the same size as other tool bitmaps, but should be similar
            as otherwise it will look visually odd.
        @param bitmap_disabled
            Bitmap to use when the tool is disabled. If left as wxNullBitmap,
            then a bitmap will be automatically generated from @a bitmap.
        @param help_string
            The UI help string to associate with the new tool.
        @param kind
            The kind of tool to add.
        @param client_data
            Client data to associate with the new tool.
        
        @return An opaque pointer which can be used only with other tool bar
            methods.
            
        @see AddDropdownTool(), AddHybridTool(), AddSeparator(), InsertTool()
    */
    virtual wxRibbonToolBarToolBase* AddTool(
                int tool_id,
                const wxBitmap& bitmap,
                const wxBitmap& bitmap_disabled = wxNullBitmap,
                const wxString& help_string = wxEmptyString,
                wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
                wxObject* client_data = NULL);

    /**
        Add a separator to the tool bar.
        
        Separators are used to separate tools into groups. As such, a separator
        is not explicitly drawn, but is visually seen as the gap between tool
        groups.
    */
    virtual wxRibbonToolBarToolBase* AddSeparator();

    /**
        Insert a tool to the tool bar (simple version) as the specified
        position.

        @since 2.9.4

        @see InsertTool()
     */
    virtual wxRibbonToolBarToolBase* InsertTool(
                size_t pos,
                int tool_id,
                const wxBitmap& bitmap,
                const wxString& help_string,
                wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);


    /**
        Insert a dropdown tool to the tool bar (simple version) as the specified
        position.

        @since 2.9.4

        @see AddDropdownTool(), InsertTool()
     */
    virtual wxRibbonToolBarToolBase* InsertDropdownTool(
                size_t pos,
                int tool_id,
                const wxBitmap& bitmap,
                const wxString& help_string = wxEmptyString);

    /**
        Insert a hybrid tool to the tool bar (simple version) as the specified
        position.

        @since 2.9.4

        @see AddHybridTool(), InsertTool()
     */
    virtual wxRibbonToolBarToolBase* InsertHybridTool(
                size_t pos,
                int tool_id,
                const wxBitmap& bitmap,
                const wxString& help_string = wxEmptyString);

    /**
        Insert a toggle tool to the tool bar (simple version) as the specified
        position.

        @since 2.9.4

       @see AddToggleTool(), InsertTool()
     */
    virtual wxRibbonToolBarToolBase* InsertToggleTool(
                size_t pos,
                int tool_id,
                const wxBitmap& bitmap,
                const wxString& help_string = wxEmptyString);

    /**
        Insert a tool to the tool bar at the specified position.

        @param pos
            Position of the new tool (number of tools and separators from the
            beginning of the toolbar).
        @param tool_id
            ID of the new tool (used for event callbacks).
        @param bitmap
            Bitmap to use as the foreground for the new tool. Does not have
            to be the same size as other tool bitmaps, but should be similar
            as otherwise it will look visually odd.
        @param bitmap_disabled
            Bitmap to use when the tool is disabled. If left as wxNullBitmap,
            then a bitmap will be automatically generated from @a bitmap.
        @param help_string
            The UI help string to associate with the new tool.
        @param kind
            The kind of tool to add.
        @param client_data
            Client data to associate with the new tool.

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

        @since 2.9.4

        @see InsertDropdownTool(), InsertHybridTool(), InsertSeparator()
    */
    virtual wxRibbonToolBarToolBase* InsertTool(
                size_t pos,
                int tool_id,
                const wxBitmap& bitmap,
                const wxBitmap& bitmap_disabled = wxNullBitmap,
                const wxString& help_string = wxEmptyString,
                wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
                wxObject* client_data = NULL);

    /**
        Insert a separator to the tool bar at the specified position.

        @since 2.9.4

        @see AddSeparator(), InsertTool()
    */
    virtual wxRibbonToolBarToolBase* InsertSeparator(size_t pos);

    /**
        Deletes all the tools in the toolbar.

        @since 2.9.4
    */
    virtual void ClearTools();

    /**
        Removes the specified tool from the toolbar and deletes it.

        @param tool_id
            ID of the tool to delete.

        @returns @true if the tool was deleted, @false otherwise.

        @since 2.9.4

        @see DeleteToolByPos()
    */
    virtual bool DeleteTool(int tool_id);

    /**
        This function behaves like DeleteTool() but it deletes the tool at the
        specified position and not the one with the given id.
        Useful to delete separators.

        @since 2.9.4
    */
    virtual bool DeleteToolByPos(size_t pos);

    /**
        Returns a pointer to the tool opaque structure by @a id or @NULL if no
        corresponding tool is found.

        @since 2.9.4
    */
    virtual wxRibbonToolBarToolBase* FindById(int tool_id)const;

    /**
        Return the opaque pointer corresponding to the given tool.

        @return an opaque pointer, NULL if is a separator or not found.

        @since 2.9.4
    */
    wxRibbonToolBarToolBase* GetToolByPos(size_t pos)const

    /**
        Returns the number of tools in the toolbar.

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

    /**
        Return the id assciated to the tool opaque structure.

        The structure pointer must not be @NULL.

        @since 2.9.4
    */
    virtual int GetToolId(const wxRibbonToolBarToolBase* tool)const;

    /**
        Get any client data associated with the tool.

        @param tool_id
            ID of the tool in question, as passed to AddTool().

        @return Client data, or @NULL if there is none.

        @since 2.9.4
    */
    virtual wxObject* GetToolClientData(int tool_id)const;

    /**
        Called to determine whether a tool is enabled (responds to user input).

        @param tool_id
            ID of the tool in question, as passed to AddTool().

        @return @true if the tool is enabled, @false otherwise.

        @since 2.9.4

        @see EnableTool()
    */
    virtual bool GetToolEnabled(int tool_id)const;

    /**
        Returns the help string for the given tool.

        @param tool_id
            ID of the tool in question, as passed to AddTool().

        @since 2.9.4
    */
    virtual wxString GetToolHelpString(int tool_id)const;

    /**
        Return the kind of the given tool.

        @param tool_id
            ID of the tool in question, as passed to AddTool().

        @since 2.9.4
    */
    virtual wxRibbonButtonKind GetToolKind(int tool_id)const;

    /**
        Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
        is not found.

        @param tool_id
            ID of the tool in question, as passed to AddTool().

        @since 2.9.4
    */
    virtual int GetToolPos(int tool_id)const;

    /**
        Gets the on/off state of a toggle tool.

        @param tool_id
            ID of the tool in question, as passed to AddTool().

        @return @true if the tool is toggled on, @false otherwise.

        @see ToggleTool()

        @since 2.9.4
    */
    virtual bool GetToolState(int tool_id)const;

    /**
        Calculate tool layouts and positions.

        Must be called after tools are added to the tool bar, as otherwise
        the newly added tools will not be displayed.
    */
    virtual bool Realize();

    /**
        Set the number of rows to distribute tool groups over.
        
        Tool groups can be distributed over a variable number of rows. The way
        in which groups are assigned to rows is not specified, and the order
        of groups may change, but they will be distributed in such a way as to
        minimise the overall size of the tool bar.
        
        @param nMin
            The minimum number of rows to use.
        @param nMax
            The maximum number of rows to use (defaults to nMin).
    */
    virtual void SetRows(int nMin, int nMax = -1);

    /**
        Sets the client data associated with the tool.

        @param tool_id
            ID of the tool in question, as passed to AddTool().
        @param clientData
            The client data to use.

        @since 2.9.4
    */
    virtual void SetToolClientData(int tool_id, wxObject* clientData);

    /**
        Sets the bitmap to be used by the tool with the given ID when the tool
        is in a disabled state.

        @param tool_id
            ID of the tool in question, as passed to AddTool().
        @param bitmap
            Bitmap to use for disabled tools.

        @since 2.9.4
    */
    virtual void SetToolDisabledBitmap(int tool_id, const wxBitmap &bitmap);

    /**
        Sets the help string shown in tooltip for the given tool.

        @param tool_id
            ID of the tool in question, as passed to AddTool().
        @param helpString
            A string for the help.

        @see GetToolHelpString()

        @since 2.9.4
    */
    virtual void SetToolHelpString(int tool_id, const wxString& helpString);

    /**
        Sets the bitmap to be used by the tool with the given ID.

        @param tool_id
            ID of the tool in question, as passed to AddTool().
        @param bitmap
            Bitmap to use for normals tools.

        @since 2.9.4
    */
    virtual void SetToolNormalBitmap(int tool_id, const wxBitmap &bitmap);

    /**
        Enable or disable a single tool on the bar.

        @param tool_id
            ID of the tool to enable or disable.
        @param enable
            @true to enable the tool, @false to disable it.

        @since 2.9.4
    */
    virtual void EnableTool(int tool_id, bool enable = true);

    /**
        Set a toggle tool to the checked or unchecked state.

        @param tool_id
            ID of the toggle tool to manipulate.
        @param checked
            @true to set the tool to the toggled/pressed/checked state,
            @false to set it to the untoggled/unpressed/unchecked state.

        @since 2.9.4
    */
    virtual void ToggleTool(int tool_id, bool checked);
};
Commit	Line	Data
3c3ead1d PC	1	///////////////////////////////////////////////////////////////////////////////
	2	// Name: ribbon/toolbar.h
	3	// Purpose: interface of wxRibbonToolBar
	4	// Author: Peter Cawley
3c3ead1d PC	5	// Licence: wxWindows licence
	6	///////////////////////////////////////////////////////////////////////////////
	7
	8	/**
	9	@class wxRibbonToolBar
	10
	11	A ribbon tool bar is similar to a traditional toolbar which has no labels.
	12	It contains one or more tool groups, each of which contains one or more
	13	tools. Each tool is represented by a (generally small, i.e. 16x15) bitmap.
	14
	15	@beginEventEmissionTable{wxRibbonToolBarEvent}
	16	@event{EVT_RIBBONTOOLBAR_CLICKED(id, func)}
	17	Triggered when the normal (non-dropdown) region of a tool on the tool
	18	bar is clicked.
	19	@event{EVT_RIBBONTOOLBAR_DROPDOWN_CLICKED(id, func)}
	20	Triggered when the dropdown region of a tool on the tool bar is
	21	clicked. wxRibbonToolBarEvent::PopupMenu() should be called by the
	22	event handler if it wants to display a popup menu (which is what most
	23	dropdown tools should be doing).
	24	@endEventTable
	25
	26	@library{wxribbon}
	27	@category{ribbon}
	28	*/
	29	class wxRibbonToolBar : public wxRibbonControl
	30	{
	31	public:
	32	/**
	33	Default constructor.
	34	With this constructor, Create() should be called in order to create
	35	the tool bar.
	36	*/
	37	wxRibbonToolBar();
	38
	39	/**
	40	Construct a ribbon tool bar with the given parameters.
69aa257b	41
3c3ead1d PC	42	@param parent
3c3ead1d PC	43	Parent window for the tool bar (typically a wxRibbonPanel).
69aa257b FM	44	@param id
69aa257b FM	45	An identifier for the toolbar. @c wxID_ANY is taken to mean a default.
3c3ead1d PC	46	@param pos
	47	Initial position of the tool bar.
	48	@param size
	49	Initial size of the tool bar.
	50	@param style
	51	Tool bar style, currently unused.
	52	*/
	53	wxRibbonToolBar(wxWindow* parent,
	54	wxWindowID id = wxID_ANY,
	55	const wxPoint& pos = wxDefaultPosition,
	56	const wxSize& size = wxDefaultSize,
	57	long style = 0);
	58
	59	/**
	60	Destructor.
	61	*/
	62	virtual ~wxRibbonToolBar();
	63
	64	/**
	65	Create a tool bar in two-step tool bar construction.
	66	Should only be called when the default constructor is used, and
	67	arguments have the same meaning as in the full constructor.
	68	*/
	69	bool Create(wxWindow* parent,
	70	wxWindowID id = wxID_ANY,
	71	const wxPoint& pos = wxDefaultPosition,
	72	const wxSize& size = wxDefaultSize,
	73	long style = 0);
	74
	75	/**
	76	Add a tool to the tool bar (simple version).
	77	*/
	78	virtual wxRibbonToolBarToolBase* AddTool(
	79	int tool_id,
	80	const wxBitmap& bitmap,
	81	const wxString& help_string,
	82	wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);
	83
	84	/**
	85	Add a dropdown tool to the tool bar (simple version).
	86
	87	@see AddTool()
	88	*/
	89	virtual wxRibbonToolBarToolBase* AddDropdownTool(
	90	int tool_id,
	91	const wxBitmap& bitmap,
	92	const wxString& help_string = wxEmptyString);
	93
	94	/**
	95	Add a hybrid tool to the tool bar (simple version).
	96
	97	@see AddTool()
	98	*/
	99	virtual wxRibbonToolBarToolBase* AddHybridTool(
	100	int tool_id,
	101	const wxBitmap& bitmap,
	102	const wxString& help_string = wxEmptyString);
	103
d1bf0be0 VZ	104	/**
	105	Add a toggle tool to the tool bar (simple version).
	106
	107	@since 2.9.4
	108
	109	@see AddTool()
	110	*/
	111	virtual wxRibbonToolBarToolBase* AddToggleTool(
	112	int tool_id,
	113	const wxBitmap& bitmap,
	114	const wxString& help_string);
	115
3c3ead1d PC	116	/**
	117	Add a tool to the tool bar.
	118
	119	@param tool_id
	120	ID of the new tool (used for event callbacks).
	121	@param bitmap
	122	Bitmap to use as the foreground for the new tool. Does not have
	123	to be the same size as other tool bitmaps, but should be similar
	124	as otherwise it will look visually odd.
	125	@param bitmap_disabled
	126	Bitmap to use when the tool is disabled. If left as wxNullBitmap,
	127	then a bitmap will be automatically generated from @a bitmap.
	128	@param help_string
	129	The UI help string to associate with the new tool.
	130	@param kind
	131	The kind of tool to add.
	132	@param client_data
	133	Client data to associate with the new tool.
	134
	135	@return An opaque pointer which can be used only with other tool bar
	136	methods.
	137
d1bf0be0	138	@see AddDropdownTool(), AddHybridTool(), AddSeparator(), InsertTool()
3c3ead1d PC	139	*/
	140	virtual wxRibbonToolBarToolBase* AddTool(
	141	int tool_id,
	142	const wxBitmap& bitmap,
	143	const wxBitmap& bitmap_disabled = wxNullBitmap,
	144	const wxString& help_string = wxEmptyString,
	145	wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
	146	wxObject* client_data = NULL);
	147
	148	/**
	149	Add a separator to the tool bar.
	150
	151	Separators are used to separate tools into groups. As such, a separator
57ab6f23	152	is not explicitly drawn, but is visually seen as the gap between tool
3c3ead1d PC	153	groups.
	154	*/
	155	virtual wxRibbonToolBarToolBase* AddSeparator();
	156
d1bf0be0 VZ	157	/**
	158	Insert a tool to the tool bar (simple version) as the specified
	159	position.
	160
	161	@since 2.9.4
	162
	163	@see InsertTool()
	164	*/
	165	virtual wxRibbonToolBarToolBase* InsertTool(
	166	size_t pos,
	167	int tool_id,
	168	const wxBitmap& bitmap,
	169	const wxString& help_string,
	170	wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL);
	171
	172
	173	/**
	174	Insert a dropdown tool to the tool bar (simple version) as the specified
	175	position.
	176
	177	@since 2.9.4
	178
	179	@see AddDropdownTool(), InsertTool()
	180	*/
	181	virtual wxRibbonToolBarToolBase* InsertDropdownTool(
	182	size_t pos,
	183	int tool_id,
	184	const wxBitmap& bitmap,
	185	const wxString& help_string = wxEmptyString);
	186
	187	/**
	188	Insert a hybrid tool to the tool bar (simple version) as the specified
	189	position.
	190
	191	@since 2.9.4
	192
	193	@see AddHybridTool(), InsertTool()
	194	*/
	195	virtual wxRibbonToolBarToolBase* InsertHybridTool(
	196	size_t pos,
	197	int tool_id,
	198	const wxBitmap& bitmap,
	199	const wxString& help_string = wxEmptyString);
	200
	201	/**
	202	Insert a toggle tool to the tool bar (simple version) as the specified
	203	position.
	204
	205	@since 2.9.4
	206
	207	@see AddToggleTool(), InsertTool()
	208	*/
	209	virtual wxRibbonToolBarToolBase* InsertToggleTool(
	210	size_t pos,
	211	int tool_id,
	212	const wxBitmap& bitmap,
	213	const wxString& help_string = wxEmptyString);
	214
	215	/**
	216	Insert a tool to the tool bar at the specified position.
	217
	218	@param pos
	219	Position of the new tool (number of tools and separators from the
f090e4ef	220	beginning of the toolbar).
d1bf0be0 VZ	221	@param tool_id
	222	ID of the new tool (used for event callbacks).
	223	@param bitmap
	224	Bitmap to use as the foreground for the new tool. Does not have
	225	to be the same size as other tool bitmaps, but should be similar
	226	as otherwise it will look visually odd.
	227	@param bitmap_disabled
	228	Bitmap to use when the tool is disabled. If left as wxNullBitmap,
	229	then a bitmap will be automatically generated from @a bitmap.
	230	@param help_string
	231	The UI help string to associate with the new tool.
	232	@param kind
	233	The kind of tool to add.
	234	@param client_data
	235	Client data to associate with the new tool.
	236
	237	@return An opaque pointer which can be used only with other tool bar
	238	methods.
	239
	240	@since 2.9.4
	241
	242	@see InsertDropdownTool(), InsertHybridTool(), InsertSeparator()
	243	*/
	244	virtual wxRibbonToolBarToolBase* InsertTool(
	245	size_t pos,
	246	int tool_id,
	247	const wxBitmap& bitmap,
	248	const wxBitmap& bitmap_disabled = wxNullBitmap,
	249	const wxString& help_string = wxEmptyString,
	250	wxRibbonButtonKind kind = wxRIBBON_BUTTON_NORMAL,
	251	wxObject* client_data = NULL);
	252
	253	/**
	254	Insert a separator to the tool bar at the specified position.
	255
	256	@since 2.9.4
	257
	258	@see AddSeparator(), InsertTool()
	259	*/
	260	virtual wxRibbonToolBarToolBase* InsertSeparator(size_t pos);
	261
	262	/**
	263	Deletes all the tools in the toolbar.
	264
	265	@since 2.9.4
	266	*/
	267	virtual void ClearTools();
	268
	269	/**
	270	Removes the specified tool from the toolbar and deletes it.
	271
	272	@param tool_id
	273	ID of the tool to delete.
	274
	275	@returns @true if the tool was deleted, @false otherwise.
	276
	277	@since 2.9.4
	278
	279	@see DeleteToolByPos()
	280	*/
	281	virtual bool DeleteTool(int tool_id);
	282
	283	/**
	284	This function behaves like DeleteTool() but it deletes the tool at the
285	specified position and not the one with the given id.
f090e4ef	286	Useful to delete separators.
d1bf0be0 VZ	287
	288	@since 2.9.4
	289	*/
	290	virtual bool DeleteToolByPos(size_t pos);
	291
	292	/**
	293	Returns a pointer to the tool opaque structure by @a id or @NULL if no
	294	corresponding tool is found.
	295
	296	@since 2.9.4
	297	*/
	298	virtual wxRibbonToolBarToolBase* FindById(int tool_id)const;
	299
	300	/**
	301	Return the opaque pointer corresponding to the given tool.
	302
	303	@return an opaque pointer, NULL if is a separator or not found.
	304
	305	@since 2.9.4
	306	*/
	307	wxRibbonToolBarToolBase* GetToolByPos(size_t pos)const
	308
	309	/**
	310	Returns the number of tools in the toolbar.
	311
	312	@since 2.9.4
	313	*/
	314	virtual size_t GetToolCount() const;
	315
	316	/**
	317	Return the id assciated to the tool opaque structure.
	318
	319	The structure pointer must not be @NULL.
	320
	321	@since 2.9.4
	322	*/
	323	virtual int GetToolId(const wxRibbonToolBarToolBase* tool)const;
	324
	325	/**
	326	Get any client data associated with the tool.
	327
2f36b4d2	328	@param tool_id
d1bf0be0 VZ	329	ID of the tool in question, as passed to AddTool().
	330
	331	@return Client data, or @NULL if there is none.
	332
	333	@since 2.9.4
	334	*/
	335	virtual wxObject* GetToolClientData(int tool_id)const;
	336
	337	/**
	338	Called to determine whether a tool is enabled (responds to user input).
	339
2f36b4d2	340	@param tool_id
d1bf0be0 VZ	341	ID of the tool in question, as passed to AddTool().
	342
	343	@return @true if the tool is enabled, @false otherwise.
	344
	345	@since 2.9.4
	346
	347	@see EnableTool()
	348	*/
	349	virtual bool GetToolEnabled(int tool_id)const;
	350
	351	/**
	352	Returns the help string for the given tool.
	353
2f36b4d2	354	@param tool_id
d1bf0be0 VZ	355	ID of the tool in question, as passed to AddTool().
	356
	357	@since 2.9.4
	358	*/
	359	virtual wxString GetToolHelpString(int tool_id)const;
	360
	361	/**
	362	Return the kind of the given tool.
	363
2f36b4d2	364	@param tool_id
d1bf0be0 VZ	365	ID of the tool in question, as passed to AddTool().
	366
	367	@since 2.9.4
	368	*/
	369	virtual wxRibbonButtonKind GetToolKind(int tool_id)const;
	370
	371	/**
	372	Returns the tool position in the toolbar, or @c wxNOT_FOUND if the tool
	373	is not found.
	374
2f36b4d2	375	@param tool_id
d1bf0be0 VZ	376	ID of the tool in question, as passed to AddTool().
	377
	378	@since 2.9.4
	379	*/
	380	virtual int GetToolPos(int tool_id)const;
	381
	382	/**
	383	Gets the on/off state of a toggle tool.
	384
2f36b4d2	385	@param tool_id
d1bf0be0 VZ	386	ID of the tool in question, as passed to AddTool().
	387
	388	@return @true if the tool is toggled on, @false otherwise.
	389
	390	@see ToggleTool()
	391
	392	@since 2.9.4
	393	*/
	394	virtual bool GetToolState(int tool_id)const;
	395
	396	/**
	397	Calculate tool layouts and positions.
	398
	399	Must be called after tools are added to the tool bar, as otherwise
	400	the newly added tools will not be displayed.
	401	*/
	402	virtual bool Realize();
	403
3c3ead1d PC	404	/**
	405	Set the number of rows to distribute tool groups over.
	406
	407	Tool groups can be distributed over a variable number of rows. The way
57ab6f23	408	in which groups are assigned to rows is not specified, and the order
3c3ead1d PC	409	of groups may change, but they will be distributed in such a way as to
	410	minimise the overall size of the tool bar.
	411
	412	@param nMin
	413	The minimum number of rows to use.
	414	@param nMax
	415	The maximum number of rows to use (defaults to nMin).
	416	*/
	417	virtual void SetRows(int nMin, int nMax = -1);
d1bf0be0 VZ	418
	419	/**
	420	Sets the client data associated with the tool.
	421
2f36b4d2	422	@param tool_id
d1bf0be0	423	ID of the tool in question, as passed to AddTool().
2f36b4d2 SL	424	@param clientData
2f36b4d2 SL	425	The client data to use.
d1bf0be0 VZ	426
	427	@since 2.9.4
	428	*/
	429	virtual void SetToolClientData(int tool_id, wxObject* clientData);
	430
	431	/**
	432	Sets the bitmap to be used by the tool with the given ID when the tool
	433	is in a disabled state.
	434
	435	@param tool_id
	436	ID of the tool in question, as passed to AddTool().
2f36b4d2 SL	437	@param bitmap
2f36b4d2 SL	438	Bitmap to use for disabled tools.
d1bf0be0 VZ	439
	440	@since 2.9.4
	441	*/
	442	virtual void SetToolDisabledBitmap(int tool_id, const wxBitmap &bitmap);
	443
	444	/**
	445	Sets the help string shown in tooltip for the given tool.
	446
2f36b4d2	447	@param tool_id
d1bf0be0 VZ	448	ID of the tool in question, as passed to AddTool().
	449	@param helpString
	450	A string for the help.
	451
	452	@see GetToolHelpString()
	453
	454	@since 2.9.4
	455	*/
	456	virtual void SetToolHelpString(int tool_id, const wxString& helpString);
	457
	458	/**
	459	Sets the bitmap to be used by the tool with the given ID.
	460
	461	@param tool_id
	462	ID of the tool in question, as passed to AddTool().
2f36b4d2 SL	463	@param bitmap
2f36b4d2 SL	464	Bitmap to use for normals tools.
d1bf0be0 VZ	465
	466	@since 2.9.4
	467	*/
	468	virtual void SetToolNormalBitmap(int tool_id, const wxBitmap &bitmap);
	469
	470	/**
	471	Enable or disable a single tool on the bar.
	472
	473	@param tool_id
	474	ID of the tool to enable or disable.
	475	@param enable
	476	@true to enable the tool, @false to disable it.
	477
	478	@since 2.9.4
	479	*/
	480	virtual void EnableTool(int tool_id, bool enable = true);
	481
	482	/**
	483	Set a toggle tool to the checked or unchecked state.
	484
	485	@param tool_id
	486	ID of the toggle tool to manipulate.
	487	@param checked
	488	@true to set the tool to the toggled/pressed/checked state,
	489	@false to set it to the untoggled/unpressed/unchecked state.
	490
	491	@since 2.9.4
	492	*/
	493	virtual void ToggleTool(int tool_id, bool checked);
3c3ead1d	494	};