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

///////////////////////////////////////////////////////////////////////////////
// Name:        ribbon/toolbar.h
// Purpose:     interface of wxRibbonToolBar
// Author:      Peter Cawley
// RCS-ID:      $Id$
// 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
            begining 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.
        Usefull 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 toolId
            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 toolId
            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 toolId
            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 toolId
            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 toolId
            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 toolId
            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 id
            ID of the tool in question, as passed to AddTool().

        @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().

        @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().

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