phoenix_title wx.ribbon.RibbonToolBar

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.

^^

events Events Emitted by this Class

Handlers bound for the following event types will receive a wx.ribbon.RibbonToolBarEvent parameter.

  • EVT_RIBBONTOOLBAR_CLICKED: Triggered when the normal (non-dropdown) region of a tool on the tool bar is clicked.

  • EVT_RIBBONTOOLBAR_DROPDOWN_CLICKED: Triggered when the dropdown region of a tool on the tool bar is clicked. wx.ribbon.RibbonToolBarEvent.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). ^^


class_hierarchy Class Hierarchy

Inheritance diagram for class RibbonToolBar:

method_summary Methods Summary

__init__

Default constructor.

AddDropdownTool

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

AddHybridTool

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

AddSeparator

Add a separator to the tool bar.

AddToggleTool

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

AddTool

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

ClearTools

Deletes all the tools in the toolbar.

Create

Create a tool bar in two-step tool bar construction.

DeleteTool

Removes the specified tool from the toolbar and deletes it.

DeleteToolByPos

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

EnableTool

Enable or disable a single tool on the bar.

FindById

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

GetActiveTool

Returns the active item of the tool bar or None if there is none.

GetClassDefaultAttributes

GetToolByPos

Return the opaque pointer corresponding to the given tool.

GetToolClientData

Get any client data associated with the tool.

GetToolCount

Returns the number of tools in the toolbar.

GetToolEnabled

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

GetToolHelpString

Returns the help string for the given tool.

GetToolId

Return the id associated to the tool opaque structure.

GetToolKind

Return the kind of the given tool.

GetToolPos

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

GetToolRect

Returns the tool’s rect with coordinates relative to the toolbar’s parent, or a default-constructed rect if the tool is not found.

GetToolState

Gets the on/off state of a toggle tool.

InsertDropdownTool

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

InsertHybridTool

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

InsertSeparator

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

InsertToggleTool

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

InsertTool

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

Realize

Calculate 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 help string shown in tooltip for the given tool.

SetToolNormalBitmap

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

ToggleTool

Set a toggle tool to the checked or unchecked state.


property_summary Properties Summary

ActiveTool

See GetActiveTool

ToolCount

See GetToolCount


api Class API

class wx.ribbon.RibbonToolBar(RibbonControl)

Possible constructors:

RibbonToolBar()

RibbonToolBar(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize,
              style=0)

A ribbon tool bar is similar to a traditional toolbar which has no labels.


Methods

__init__(self, *args, **kw)

overload Overloaded Implementations:



__init__ (self)

Default constructor.

With this constructor, Create should be called in order to create the tool bar.



__init__ (self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0)

Construct a ribbon tool bar with the given parameters.

Parameters
  • parent (wx.Window) – Parent window for the tool bar (typically a wx.ribbon.RibbonPanel).

  • id (wx.WindowID) – An identifier for the toolbar. ID_ANY is taken to mean a default.

  • pos (wx.Point) – Initial position of the tool bar.

  • size (wx.Size) – Initial size of the tool bar.

  • style (long) – Tool bar style, currently unused.





AddDropdownTool(self, tool_id, bitmap, help_string="")

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

Parameters
  • tool_id (int) –

  • bitmap (wx.Bitmap) –

  • help_string (string) –

Return type

RibbonToolBarToolBase

See also

AddTool



AddHybridTool(self, tool_id, bitmap, help_string="")

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

Parameters
  • tool_id (int) –

  • bitmap (wx.Bitmap) –

  • help_string (string) –

Return type

RibbonToolBarToolBase

See also

AddTool



AddSeparator(self)

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.

Return type

RibbonToolBarToolBase



AddToggleTool(self, tool_id, bitmap, help_string)

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

Parameters
  • tool_id (int) –

  • bitmap (wx.Bitmap) –

  • help_string (string) –

Return type

RibbonToolBarToolBase

New in version 2.9.4.

See also

AddTool



AddTool(self, *args, **kw)

overload Overloaded Implementations:



AddTool (self, tool_id, bitmap, help_string, kind=RIBBON_BUTTON_NORMAL)

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

Parameters
Return type

RibbonToolBarToolBase



AddTool (self, tool_id, bitmap, bitmap_disabled=NullBitmap, help_string=””, kind=RIBBON_BUTTON_NORMAL, clientData=None)

Add a tool to the tool bar.

Parameters
  • tool_id (int) – ID of the new tool (used for event callbacks).

  • bitmap (wx.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 (wx.Bitmap) – Bitmap to use when the tool is disabled. If left as NullBitmap, then a bitmap will be automatically generated from bitmap.

  • help_string (string) – The UI help string to associate with the new tool.

  • kind (RibbonButtonKind) – The kind of tool to add.

  • clientData (PyUserData) – Client data to associate with the new tool.

Return type

RibbonToolBarToolBase

Returns

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





ClearTools(self)

Deletes all the tools in the toolbar.

New in version 2.9.4.



Create(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0)

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.

Parameters
Return type

bool



DeleteTool(self, tool_id)

Removes the specified tool from the toolbar and deletes it.

Parameters

tool_id (int) – ID of the tool to delete.

Return type

bool

Returns

True if the tool was deleted, False otherwise.

New in version 2.9.4.

See also

DeleteToolByPos



DeleteToolByPos(self, pos)

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.

Parameters

pos (int) –

Return type

bool

New in version 2.9.4.



EnableTool(self, tool_id, enable=True)

Enable or disable a single tool on the bar.

Parameters
  • tool_id (int) – ID of the tool to enable or disable.

  • enable (bool) – True to enable the tool, False to disable it.

New in version 2.9.4.



FindById(self, tool_id)

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

Parameters

tool_id (int) –

Return type

RibbonToolBarToolBase

New in version 2.9.4.



GetActiveTool(self)

Returns the active item of the tool bar or None if there is none.

The active tool is the one being clicked.

Return type

RibbonToolBarToolBase

New in version 4.1/wxWidgets-3.1.7.



static GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)
Parameters

variant (WindowVariant) –

Return type

VisualAttributes



GetToolByPos(self, *args, **kw)

overload Overloaded Implementations:



GetToolByPos (self, pos)

Return the opaque pointer corresponding to the given tool.

Parameters

pos (int) –

Return type

RibbonToolBarToolBase

Returns

an opaque pointer, None if is a separator or not found.

New in version 2.9.4.



GetToolByPos (self, x, y)

Returns the opaque pointer for the tool at the given coordinates, which are relative to the toolbar’s parent.

Parameters
  • x (int) –

  • y (int) –

Return type

RibbonToolBarToolBase

Returns

an opaque pointer, None if is not found.

New in version 4.1/wxWidgets-3.1.5.





GetToolClientData(self, tool_id)

Get any client data associated with the tool.

Parameters

tool_id (int) – ID of the tool in question, as passed to AddTool .

Return type

PyUserData

Returns

Client data, or None if there is none.

New in version 2.9.4.



GetToolCount(self)

Returns the number of tools in the toolbar.

Return type

int

New in version 2.9.4.



GetToolEnabled(self, tool_id)

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

Parameters

tool_id (int) – ID of the tool in question, as passed to AddTool .

Return type

bool

Returns

True if the tool is enabled, False otherwise.

New in version 2.9.4.

See also

EnableTool



GetToolHelpString(self, tool_id)

Returns the help string for the given tool.

Parameters

tool_id (int) – ID of the tool in question, as passed to AddTool .

Return type

string

New in version 2.9.4.



GetToolId(self, tool)

Return the id associated to the tool opaque structure.

The structure pointer must not be None.

Parameters

tool (RibbonToolBarToolBase) –

Return type

int

New in version 2.9.4.



GetToolKind(self, tool_id)

Return the kind of the given tool.

Parameters

tool_id (int) – ID of the tool in question, as passed to AddTool .

Return type

wx.ribbon.RibbonButtonKind

New in version 2.9.4.



GetToolPos(self, tool_id)

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

Parameters

tool_id (int) – ID of the tool in question, as passed to AddTool .

Return type

int

New in version 2.9.4.



GetToolRect(self, tool_id)

Returns the tool’s rect with coordinates relative to the toolbar’s parent, or a default-constructed rect if the tool is not found.

Parameters

tool_id (int) – ID of the tool in question, as passed to AddTool .

Return type

Rect

New in version 4.1/wxWidgets-3.1.5.



GetToolState(self, tool_id)

Gets the on/off state of a toggle tool.

Parameters

tool_id (int) – ID of the tool in question, as passed to AddTool .

Return type

bool

Returns

True if the tool is toggled on, False otherwise.

New in version 2.9.4.

See also

ToggleTool



InsertDropdownTool(self, pos, tool_id, bitmap, help_string="")

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

Parameters
  • pos (int) –

  • tool_id (int) –

  • bitmap (wx.Bitmap) –

  • help_string (string) –

Return type

RibbonToolBarToolBase

New in version 2.9.4.



InsertHybridTool(self, pos, tool_id, bitmap, help_string="")

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

Parameters
  • pos (int) –

  • tool_id (int) –

  • bitmap (wx.Bitmap) –

  • help_string (string) –

Return type

RibbonToolBarToolBase

New in version 2.9.4.



InsertSeparator(self, pos)

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

Parameters

pos (int) –

Return type

RibbonToolBarToolBase

New in version 2.9.4.



InsertToggleTool(self, pos, tool_id, bitmap, help_string="")

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

Parameters
  • pos (int) –

  • tool_id (int) –

  • bitmap (wx.Bitmap) –

  • help_string (string) –

Return type

RibbonToolBarToolBase

New in version 2.9.4.



InsertTool(self, *args, **kw)

overload Overloaded Implementations:



InsertTool (self, pos, tool_id, bitmap, help_string, kind=RIBBON_BUTTON_NORMAL)

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

Parameters
Return type

RibbonToolBarToolBase

New in version 2.9.4.

See also

InsertTool



InsertTool (self, pos, tool_id, bitmap, bitmap_disabled=NullBitmap, help_string=””, kind=RIBBON_BUTTON_NORMAL, clientData=None)

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

Parameters
  • pos (int) – Position of the new tool (number of tools and separators from the beginning of the toolbar).

  • tool_id (int) – ID of the new tool (used for event callbacks).

  • bitmap (wx.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 (wx.Bitmap) – Bitmap to use when the tool is disabled. If left as NullBitmap, then a bitmap will be automatically generated from bitmap.

  • help_string (string) – The UI help string to associate with the new tool.

  • kind (RibbonButtonKind) – The kind of tool to add.

  • clientData (PyUserData) – Client data to associate with the new tool.

Return type

RibbonToolBarToolBase

Returns

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

New in version 2.9.4.





Realize(self)

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.

Return type

bool



SetRows(self, nMin, nMax=-1)

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 (int) – The minimum number of rows to use.

  • nMax (int) – 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 (int) – ID of the tool in question, as passed to AddTool .

  • clientData (PyUserData) – The client data to use.

New in version 2.9.4.



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 (int) – ID of the tool in question, as passed to AddTool .

  • bitmap (wx.Bitmap) – Bitmap to use for disabled tools.

New in version 2.9.4.



SetToolHelpString(self, tool_id, helpString)

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

Parameters
  • tool_id (int) – ID of the tool in question, as passed to AddTool .

  • helpString (string) – A string for the help.

New in version 2.9.4.



SetToolNormalBitmap(self, tool_id, bitmap)

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

Parameters
  • tool_id (int) – ID of the tool in question, as passed to AddTool .

  • bitmap (wx.Bitmap) – Bitmap to use for normals tools.

New in version 2.9.4.



ToggleTool(self, tool_id, checked)

Set a toggle tool to the checked or unchecked state.

Parameters
  • tool_id (int) – ID of the toggle tool to manipulate.

  • checked (bool) – True to set the tool to the toggled/pressed/checked state, False to set it to the untoggled/unpressed/unchecked state.

New in version 2.9.4.


Properties

ActiveTool

See GetActiveTool



ToolCount

See GetToolCount