wx.lib.agw.ribbon.toolbar.RibbonToolBar¶

Base class for all the Ribbon stuff.

Class Hierarchy¶

Inheritance diagram for class RibbonToolBar:

Control Appearance¶

Known Superclasses¶

wx.lib.agw.ribbon.control.RibbonControl

Methods Summary¶

`__init__`	Default class constructor.
`AddDropdownTool`	Add a dropdown tool to the tool bar (simple version).
`AddHybridTool`	Add a hybrid tool to the tool bar (simple version).
`AddSeparator`	Adds a separator to the tool bar.
`AddSimpleTool`	Add a tool to the tool bar (simple version).
`AddToggleTool`	Add a toggle tool to the tool bar (simple version).
`AddTool`	Add a tool to the tool bar.
`AppendGroup`
`ClearTools`	Deletes all the tools in the toolbar.
`CommonInit`
`DeleteTool`	Removes the specified tool from the toolbar and deletes it.
`DeleteToolByPos`	This function behaves like `DeleteTool` but it deletes the tool at the
`DoGetBestSize`	Gets the size which best suits the window: for a control, it would be the
`DoGetNextLargerSize`	Implementation of `RibbonControl.GetNextLargerSize()`.
`DoGetNextSmallerSize`	Implementation of `RibbonControl.GetNextSmallerSize()`.
`EnableTool`	Enables or disables a single tool on the bar.
`FindById`	Returns a pointer to the tool opaque structure by tool_id or `None` if
`GetBestSizeForParentSize`	Finds the best width and height given the parent’s width and height.
`GetDefaultBorder`	Returns the default border style for `RibbonToolBar`.
`GetToolByPos`	Returns a pointer to the tool opaque structure by pos or `None` if
`GetToolClientData`	Get any client data associated with the tool.
`GetToolCount`	Returns the number of tools in this `RibbonToolBar`.
`GetToolEnabled`	Called to determine whether a tool is enabled (responds to user input).
`GetToolHelpString`	Returns the tool short help string.
`GetToolId`	Returns the tool id for the specified input tool.
`GetToolKind`	Returns the kind of the given tool.
`GetToolPos`	Returns the tool position in the toolbar, or `wx.NOT_FOUND` if the tool is not found.
`GetToolState`	Gets the on/off state of a toggle tool.
`InsertDropdownTool`	Inserts a dropdown tool in the tool bar at the position specified by pos.
`InsertGroup`
`InsertHybridTool`	Inserts a hybrid tool in the tool bar at the position specified by pos.
`InsertSeparator`	Inserts a separator into the tool bar at the position specified by pos.
`InsertToggleTool`	Inserts a toggle tool in the tool bar at the position specified by pos.
`InsertTool`	Inserts a tool in the tool bar at the position specified by pos.
`IsSizingContinuous`	Returns `True` if this window can take any size (greater than its minimum size),
`MakeDisabledBitmap`
`OnEraseBackground`	Handles the `wx.EVT_ERASE_BACKGROUND` event for `RibbonToolBar`.
`OnMouseDown`	Handles the `wx.EVT_LEFT_DOWN` event for `RibbonToolBar`.
`OnMouseEnter`	Handles the `wx.EVT_ENTER_WINDOW` event for `RibbonToolBar`.
`OnMouseLeave`	Handles the `wx.EVT_LEAVE_WINDOW` event for `RibbonToolBar`.
`OnMouseMove`	Handles the `wx.EVT_MOTION` event for `RibbonToolBar`.
`OnMouseUp`	Handles the `wx.EVT_LEFT_UP` event for `RibbonToolBar`.
`OnPaint`	Handles the `wx.EVT_PAINT` event for `RibbonToolBar`.
`OnSize`	Handles the `wx.EVT_SIZE` event for `RibbonToolBar`.
`Realize`	Calculates tool layouts and positions.
`SetRows`	Set the number of rows to distribute tool groups over.
`SetToolClientData`	Sets the client data associated with the tool.
`SetToolDisabledBitmap`	Sets the bitmap to be used by the tool with the given ID when the tool is in a disabled state.
`SetToolHelpString`	Sets the tool short help string.
`SetToolNormalBitmap`	Sets the bitmap to be used by the tool with the given ID when the tool is enabled.
`ToggleTool`	Toggles on or off a single tool on the bar.
`UpdateWindowUI`	This function sends one or more `UpdateUIEvent` to the window.

Class API¶

class RibbonToolBar(RibbonControl)¶

Base class for all the Ribbon stuff.

Methods¶

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, name='RibbonToolBar')¶

Default class constructor.

Parameters:

parent – pointer to a parent window, typically a RibbonPanel;
id – window identifier. If wx.ID_ANY, will automatically create an identifier;
pos – window position. wx.DefaultPosition indicates that wxPython should generate a default position for the window;
size – window size. wx.DefaultSize indicates that wxPython should generate a default size for the window. If no suitable size can be found, the window will be sized to 20x20 pixels so that the window is visible but obviously not correctly sized;
style – window style, currently unused.
name – the window name.

AddDropdownTool(self, tool_id, bitmap, help_string='')¶

Add a dropdown tool to the tool bar (simple version).

Parameters:

tool_id – id of the new tool (used for event callbacks);
bitmap – large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar;
help_string – the UI help string to associate with the new button.

See also

AddTool

AddHybridTool(self, tool_id, bitmap, help_string='')¶

Add a hybrid tool to the tool bar (simple version).

Parameters:

tool_id – id of the new tool (used for event callbacks);
bitmap – large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar;
help_string – the UI help string to associate with the new button.

See also

AddTool

AddSeparator(self)¶

Adds 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.

AddSimpleTool(self, tool_id, bitmap, help_string, kind=RIBBON_BUTTON_NORMAL)¶

Add a tool to the tool bar (simple version).

Parameters:

tool_id – id of the new tool (used for event callbacks);
bitmap – large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar;
help_string – the UI help string to associate with the new button;
kind – the kind of button to add.

AddToggleTool(self, tool_id, bitmap, help_string='')¶

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

Parameters:

tool_id – id of the new tool (used for event callbacks);
bitmap – large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar;
help_string – the UI help string to associate with the new button.

See also

AddTool

AddTool(self, tool_id, bitmap, bitmap_disabled=wx.NullBitmap, help_string='', kind=RIBBON_BUTTON_NORMAL, client_data=None)¶

Add a tool to the tool bar.

Parameters:

tool_id – id of the new tool (used for event callbacks);
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;
bitmap_disabled – bitmap to use when the tool is disabled. If left as NullBitmap, then a bitmap will be automatically generated from bitmap;
help_string – the UI help string to associate with the new tool;
kind – the kind of tool to add;
client_data – client data to associate with the new tool.

Returns:

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

AppendGroup(self)¶

ClearTools(self)¶: Deletes all the tools in the toolbar.

Added in version 0.9.5.

CommonInit(self, style)¶

DeleteTool(self, tool_id)¶

Removes the specified tool from the toolbar and deletes it.

Parameters:: tool_id – id of the tool to delete.
Returns:: True if the tool was deleted, False otherwise.

See also

DeleteToolByPos

Added in version 0.9.5.

DeleteToolByPos(self, pos)¶

This function behaves like DeleteTool but it deletes the tool at the specified position pos and not the one with the given id.

Useful to delete separators.

Parameters:: pos – zero-based position of the tool to delete.
Returns:: True if the tool was deleted, False otherwise.

See also

DeleteTool

Added in version 0.9.5.

DoGetBestSize(self)¶

Gets the size which best suits the window: for a control, it would be the minimal size which doesn’t truncate the control, for a panel - the same size as it would have after a call to Fit().

Returns:: An instance of wx.Size.

Note

Overridden from wx.Control.

DoGetNextLargerSize(self, direction, relative_to)¶

Implementation of RibbonControl.GetNextLargerSize().

Controls which have non-continuous sizing must override this virtual function rather than RibbonControl.GetNextLargerSize().

DoGetNextSmallerSize(self, direction, relative_to)¶

Implementation of RibbonControl.GetNextSmallerSize().

Controls which have non-continuous sizing must override this virtual function rather than RibbonControl.GetNextSmallerSize().

EnableTool(self, tool_id, enable=True)¶

Enables or disables a single tool on the bar.

Parameters:

tool_id – id of the tool in question, as passed to AddTool;
enable – True to enable the tool, False to disable it.

Added in version 0.9.5.

FindById(self, tool_id)¶

Returns a pointer to the tool opaque structure by tool_id or None if no corresponding tool is found.

Parameters:: tool_id – id of the tool to find.

Added in version 0.9.5.

GetBestSizeForParentSize(self, parentSize)¶: Finds the best width and height given the parent’s width and height.

GetDefaultBorder(self)¶: Returns the default border style for RibbonToolBar.

GetToolByPos(self, pos)¶

Returns a pointer to the tool opaque structure by pos or None if no corresponding tool is found.

Parameters:: pos – zero-based position of the tool to retrieve.
Returns:: An instance of RibbonToolBarToolBase if the tool was found, None if it was not found.

Added in version 0.9.5.

GetToolClientData(self, tool_id)¶

Get any client data associated with the tool.

Parameters:: tool_id – id of the tool in question, as passed to AddTool.
Returns:: Client data (any Python object), or None if there is none.

Added in version 0.9.5.

GetToolCount(self)¶: Returns the number of tools in this RibbonToolBar.

Added in version 0.9.5.

GetToolEnabled(self, tool_id)¶

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

Parameters:: tool_id – id of the tool in question, as passed to AddTool.
Returns:: True if the tool was found and it is enabled, False otherwise.

Added in version 0.9.5.

GetToolHelpString(self, tool_id)¶

Returns the tool short help string.

Parameters:: tool_id – id of the tool in question, as passed to AddTool.

Added in version 0.9.5.

GetToolId(self, tool)¶

Returns the tool id for the specified input tool.

Parameters:: tool – an instance of RibbonToolBarToolBase.

Added in version 0.9.5.

GetToolKind(self, tool_id)¶

Returns the kind of the given tool.

Parameters:: tool_id – id of the tool in question, as passed to AddTool.

Added in version 0.9.5.

GetToolPos(self, tool_id)¶

Returns the tool position in the toolbar, or wx.NOT_FOUND if the tool is not found.

Parameters:: tool_id – id of the tool in question, as passed to AddTool.

Added in version 0.9.5.

GetToolState(self, tool_id)¶

Gets the on/off state of a toggle tool.

Parameters:: tool_id – id of the tool in question, as passed to AddTool.
Returns:: True if the tool is toggled on, False otherwise.

See also

ToggleTool

Added in version 0.9.5.

InsertDropdownTool(self, pos, tool_id, bitmap, help_string='')¶

Inserts a dropdown tool in the tool bar at the position specified by pos.

Parameters:

pos – the position of the new tool in the toolbar (zero-based);
tool_id – id of the new tool (used for event callbacks);
bitmap – large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar;
help_string – the UI help string to associate with the new button.

See also

AddTool, InsertTool

Added in version 0.9.5.

InsertGroup(self, pos)¶

InsertHybridTool(self, pos, tool_id, bitmap, help_string='')¶

Inserts a hybrid tool in the tool bar at the position specified by pos.

Parameters:

pos – the position of the new tool in the toolbar (zero-based);
tool_id – id of the new tool (used for event callbacks);
bitmap – large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar;
help_string – the UI help string to associate with the new button.

See also

AddTool, InsertTool

Added in version 0.9.5.

InsertSeparator(self, pos)¶

Inserts a separator into the tool bar at the position specified by pos.

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.

Parameters:: pos – the position of the new tool in the toolbar (zero-based).

Added in version 0.9.5.

InsertToggleTool(self, pos, tool_id, bitmap, help_string='')¶

Inserts a toggle tool in the tool bar at the position specified by pos.

Parameters:

pos – the position of the new tool in the toolbar (zero-based);
tool_id – id of the new tool (used for event callbacks);
bitmap – large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar;
help_string – the UI help string to associate with the new button.

See also

AddTool, InsertTool

Added in version 0.9.5.

InsertTool(self, pos, tool_id, bitmap, bitmap_disabled=wx.NullBitmap, help_string='', kind=RIBBON_BUTTON_NORMAL, client_data=None)¶

Inserts a tool in the tool bar at the position specified by pos.

Parameters:

pos – the position of the new tool in the toolbar (zero-based);
tool_id – id of the new tool (used for event callbacks);
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;
bitmap_disabled – bitmap to use when the tool is disabled. If left as NullBitmap, then a bitmap will be automatically generated from bitmap;
help_string – the UI help string to associate with the new tool;
kind – the kind of tool to add;
client_data – client data to associate with the new tool.

Returns:

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

Added in version 0.9.5.

IsSizingContinuous(self)¶: Returns True if this window can take any size (greater than its minimum size), False if it can only take certain sizes.

See also

RibbonControl.GetNextSmallerSize(), RibbonControl.GetNextLargerSize()

MakeDisabledBitmap(self, original)¶

OnEraseBackground(self, event)¶

Handles the wx.EVT_ERASE_BACKGROUND event for RibbonToolBar.

Parameters:: event – a EraseEvent event to be processed.

OnMouseDown(self, event)¶

Handles the wx.EVT_LEFT_DOWN event for RibbonToolBar.

Parameters:: event – a MouseEvent event to be processed.

OnMouseEnter(self, event)¶

Handles the wx.EVT_ENTER_WINDOW event for RibbonToolBar.

Parameters:: event – a MouseEvent event to be processed.

OnMouseLeave(self, event)¶

Handles the wx.EVT_LEAVE_WINDOW event for RibbonToolBar.

Parameters:: event – a MouseEvent event to be processed.

OnMouseMove(self, event)¶

Handles the wx.EVT_MOTION event for RibbonToolBar.

Parameters:: event – a MouseEvent event to be processed.

OnMouseUp(self, event)¶

Handles the wx.EVT_LEFT_UP event for RibbonToolBar.

Parameters:: event – a MouseEvent event to be processed.

OnPaint(self, event)¶

Handles the wx.EVT_PAINT event for RibbonToolBar.

Parameters:: event – a PaintEvent event to be processed.

OnSize(self, event)¶

Handles the wx.EVT_SIZE event for RibbonToolBar.

Parameters:: event – a wx.SizeEvent event to be processed.

Realize(self)¶

Calculates 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.

Note

Reimplemented from RibbonControl.

SetRows(self, nMin, nMax)¶

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.

Parameters:

nMin – the minimum number of rows to use;
nMax – the maximum number of rows to use (defaults to nMin).

SetToolClientData(self, tool_id, clientData)¶

Sets the client data associated with the tool.

Parameters:

tool_id – id of the tool in question, as passed to AddTool;
clientData – any Python object.

Added in version 0.9.5.

SetToolDisabledBitmap(self, tool_id, bitmap)¶

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

Parameters:

tool_id – id of the tool in question, as passed to AddTool;
bitmap – an instance of wx.Bitmap.

Added in version 0.9.5.

SetToolHelpString(self, tool_id, helpString)¶

Sets the tool short help string.

Parameters:

tool_id – id of the tool in question, as passed to AddTool;
helpString – a string for the help.

Added in version 0.9.5.

SetToolNormalBitmap(self, tool_id, bitmap)¶

Sets the bitmap to be used by the tool with the given ID when the tool is enabled.

Parameters:

tool_id – id of the tool in question, as passed to AddTool;
bitmap – an instance of wx.Bitmap.

Added in version 0.9.5.

ToggleTool(self, tool_id, checked=True)¶

Toggles on or off a single tool on the bar.

Parameters:

tool_id – id of the tool in question, as passed to AddTool;
checked – True to toggle on the tool, False to toggle it off.

Added in version 0.9.5.

UpdateWindowUI(self, flags)¶

This function sends one or more UpdateUIEvent to the window.

The particular implementation depends on the window; for example a ToolBar will send an update UI event for each toolbar button, and a wx.Frame will send an update UI event for each menubar menu item.

You can call this function from your application to ensure that your UI is up-to-date at this point (as far as your UpdateUIEvent handlers are concerned). This may be necessary if you have called UpdateUIEvent.SetMode or UpdateUIEvent.SetUpdateInterval to limit the overhead that wxWidgets incurs by sending update UI events in idle time.

Parameters:: flags (integer) – should be a bitlist of one or more of wx.UPDATE_UI_NONE, wx.UPDATE_UI_RECURSE or wx.UPDATE_UI_FROMIDLE.

If you are calling this function from an OnInternalIdle or OnIdle function, make sure you pass the wx.UPDATE_UI_FROMIDLE flag, since this tells the window to only update the UI elements that need to be updated in idle time. Some windows update their elements only when necessary, for example when a menu is about to be shown. The following is an example of how to call UpdateWindowUI from an idle function:

def OnInternalIdle(self):

    if wx.UpdateUIEvent.CanUpdate(self):
        self.UpdateWindowUI(wx.UPDATE_UI_FROMIDLE)

Added in version 0.9.5.

Table of Contents

This Page