wx.ribbon.RibbonButtonBar¶

A ribbon button bar is similar to a traditional toolbar.

It contains one or more buttons (button bar buttons, not Buttons), each of which has a label and an icon. It differs from a wx.ribbon.RibbonToolBar in several ways:

Individual buttons can grow and contract.
Buttons have labels as well as bitmaps.
Bitmaps are typically larger (at least 32x32 pixels) on a button bar compared to a tool bar (which typically has 16x15).
There is no grouping of buttons on a button bar
A button bar typically has a border around each individual button, whereas a tool bar typically has a border around each group of buttons.

^^

Events Emitted by this Class¶

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

EVT_RIBBONBUTTONBAR_CLICKED: Triggered when the normal (non-dropdown) region of a button on the button bar is clicked.
EVT_RIBBONBUTTONBAR_DROPDOWN_CLICKED: Triggered when the dropdown region of a button on the button bar is clicked. wx.ribbon.RibbonButtonBarEvent.PopupMenu should be called by the event handler if it wants to display a popup menu (which is what most dropdown buttons should be doing). ^^

Class Hierarchy¶

Inheritance diagram for class RibbonButtonBar:

Methods Summary¶

`__init__`	Default constructor.
`AddButton`	Add a button to the button bar (simple version).
`AddDropdownButton`	Add a dropdown button to the button bar (simple version).
`AddHybridButton`	Add a hybrid button to the button bar (simple version).
`AddToggleButton`	Add a toggle button to the button bar (simple version).
`ClearButtons`	Delete all buttons from the button bar.
`Create`	Create a button bar in two-step button bar construction.
`DeleteButton`	Delete a single button from the button bar.
`EnableButton`	Enable or disable a single button on the bar.
`GetActiveItem`	Returns the active item of the button bar or `None` if there is none.
`GetButtonCount`	Returns the number of buttons in this button bar.
`GetClassDefaultAttributes`
`GetHoveredItem`	Returns the hovered item of the button bar or `None` if there is none.
`GetItem`	Returns the N-th button of the bar.
`GetItemById`	Returns the first button having a given id or `None` if none matches.
`GetItemClientData`	Get the client object associated with a button.
`GetItemId`	Returns the id of a button.
`GetItemRect`	Returns the items’s rect with coordinates relative to the button bar’s parent, or a default-constructed rect if the tool is not found.
`GetShowToolTipsForDisabled`	Sets whether tooltips should be shown for disabled buttons or not.
`InsertButton`	Inserts a button to the button bar (simple version) at the given position.
`InsertDropdownButton`	Inserts a dropdown button to the button bar (simple version) at the given position.
`InsertHybridButton`	Inserts a hybrid button to the button bar (simple version) at the given position.
`InsertToggleButton`	Inserts a toggle button to the button bar (simple version) at the given position.
`Realize`	Calculate button layouts and positions.
`SetButtonIcon`	Changes the bitmap of an existing button.
`SetButtonMaxSizeClass`	Sets the maximum size class of a ribbon button.
`SetButtonMinSizeClass`	Sets the minimum size class of a ribbon button.
`SetButtonText`	Changes the label text of an existing button.
`SetButtonTextMinWidth`	Sets the minimum width of the button label, to indicate to the wx.ribbon.RibbonArtProvider layout mechanism that this is the minimum required size.
`SetItemClientData`	Set the client object associated with a button.
`SetShowToolTipsForDisabled`	Indicates whether tooltips are shown for disabled buttons.
`ToggleButton`	Set a toggle button to the checked or unchecked state.

Properties Summary¶

`ActiveItem`	See `GetActiveItem`
`ButtonCount`	See `GetButtonCount`
`HoveredItem`	See `GetHoveredItem`
`ShowToolTipsForDisabled`	See `GetShowToolTipsForDisabled` and `SetShowToolTipsForDisabled`

Class API¶

class wx.ribbon.RibbonButtonBar(RibbonControl)¶

Possible constructors:

RibbonButtonBar()

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

A ribbon button bar is similar to a traditional toolbar.

Methods¶

__init__(self, *args, **kw)¶

Overloaded Implementations:

__init__ (self)

Default constructor.

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

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

Construct a ribbon button bar with the given parameters.

Parameters:

parent (wx.Window) – Parent window for the button bar (typically a wx.ribbon.RibbonPanel).
id (wx.WindowID) – An identifier for the button bar. ID_ANY is taken to mean a default.
pos (wx.Point) – Initial position of the button bar.
size (wx.Size) – Initial size of the button bar.
style (long) – Button bar style, currently unused.

AddButton(self, *args, **kw)¶

Overloaded Implementations:

AddButton (self, button_id, label, bitmap, help_string, kind=RIBBON_BUTTON_NORMAL)

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

Parameters:

button_id (int) –
label (string) –
bitmap (wx.Bitmap) –
help_string (string) –
kind (RibbonButtonKind) –

Return type:

RibbonButtonBarButtonBase

AddButton (self, button_id, label, bitmap, bitmap_small=NullBitmap, bitmap_disabled=NullBitmap, bitmap_small_disabled=NullBitmap, kind=RIBBON_BUTTON_NORMAL, help_string=””)

Add a button to the button bar.

Parameters:

button_id (int) – ID of the new button (used for event callbacks).
label (string) – Label of the new button.
bitmap (wx.Bitmap) – Large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar.
bitmap_small (wx.Bitmap) – Small bitmap of the new button. If left as null, then a small bitmap will be automatically generated. Must be the same size as all other small bitmaps used on the button bar.
bitmap_disabled (wx.Bitmap) – Large bitmap of the new button when it is disabled. If left as null, then a bitmap will be automatically generated from bitmap.
bitmap_small_disabled (wx.Bitmap) – Small bitmap of the new button when it is disabled. If left as null, then a bitmap will be automatically generated from bitmap_small.
kind (RibbonButtonKind) – The kind of button to add.
help_string (string) – The UI help string to associate with the new button.

Return type:

RibbonButtonBarButtonBase

Returns:

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

See also

AddDropdownButton

See also

AddHybridButton

See also

AddToggleButton

AddDropdownButton(self, button_id, label, bitmap, help_string="")¶

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

Parameters:

button_id (int) –
label (string) –
bitmap (wx.Bitmap) –
help_string (string) –

Return type:

RibbonButtonBarButtonBase

See also

AddButton

AddHybridButton(self, button_id, label, bitmap, help_string="")¶

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

Parameters:

button_id (int) –
label (string) –
bitmap (wx.Bitmap) –
help_string (string) –

Return type:

RibbonButtonBarButtonBase

See also

AddButton

AddToggleButton(self, button_id, label, bitmap, help_string="")¶

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

Parameters:

button_id (int) –
label (string) –
bitmap (wx.Bitmap) –
help_string (string) –

Return type:

RibbonButtonBarButtonBase

See also

AddButton

ClearButtons(self)¶: Delete all buttons from the button bar.

See also

DeleteButton

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

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

Should only be called when the default constructor is used, and arguments have the same meaning as in the full constructor.

Parameters:

parent (wx.Window) –
id (wx.WindowID) –
pos (wx.Point) –
size (wx.Size) –
style (long) –

Return type:

bool

DeleteButton(self, button_id)¶

Delete a single button from the button bar.

The corresponding button is deleted by this function, so any pointers to it previously obtained by GetItem or GetItemById become invalid.

Parameters:: button_id (int) –
Return type:: bool

See also

ClearButtons

EnableButton(self, button_id, enable=True)¶

Enable or disable a single button on the bar.

Parameters:

button_id (int) – ID of the button to enable or disable.
enable (bool) – True to enable the button, False to disable it.

GetActiveItem(self)¶

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

The active button is the one being clicked.

Return type:: RibbonButtonBarButtonBase

New in version 2.9.5.

GetButtonCount(self)¶

Returns the number of buttons in this button bar.

Return type:: int

New in version 2.9.4.

static GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)¶

Parameters:: variant (WindowVariant) –
Return type:: VisualAttributes

GetHoveredItem(self)¶

Returns the hovered item of the button bar or None if there is none.

The hovered button is the one the mouse is over.

Return type:: RibbonButtonBarButtonBase

New in version 2.9.5.

GetItem(self, n)¶

Returns the N-th button of the bar.

Parameters:: n (int) –
Return type:: RibbonButtonBarButtonBase

New in version 2.9.5.

See also

GetButtonCount

GetItemById(self, id)¶

Returns the first button having a given id or None if none matches.

Parameters:: id (int) –
Return type:: RibbonButtonBarButtonBase

New in version 2.9.5.

GetItemClientData(self, item)¶

Get the client object associated with a button.

Parameters:: item (RibbonButtonBarButtonBase) –
Return type:: ClientData

New in version 2.9.5.

GetItemId(self, item)¶

Returns the id of a button.

Parameters:: item (RibbonButtonBarButtonBase) –
Return type:: int

New in version 2.9.5.

GetItemRect(self, button_id)¶

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

Parameters:: button_id (int) – ID of the button in question.
Return type:: Rect

New in version 4.1/wxWidgets-3.1.7.

GetShowToolTipsForDisabled(self)¶

Sets whether tooltips should be shown for disabled buttons or not.

You may wish to show it to explain why a button is disabled or what it normally does when enabled.

Return type:: bool

New in version 2.9.5.

InsertButton(self, *args, **kw)¶

Overloaded Implementations:

InsertButton (self, pos, button_id, label, bitmap, help_string, kind=RIBBON_BUTTON_NORMAL)

Inserts a button to the button bar (simple version) at the given position.

Parameters:

pos (int) –
button_id (int) –
label (string) –
bitmap (wx.Bitmap) –
help_string (string) –
kind (RibbonButtonKind) –

Return type:

RibbonButtonBarButtonBase

New in version 2.9.4.

See also

AddButton

InsertButton (self, pos, button_id, label, bitmap, bitmap_small=NullBitmap, bitmap_disabled=NullBitmap, bitmap_small_disabled=NullBitmap, kind=RIBBON_BUTTON_NORMAL, help_string=””)

Insert a button to the button bar at the given position.

Parameters:

pos (int) – Position of the new button in the button bar.
button_id (int) – ID of the new button (used for event callbacks).
label (string) – Label of the new button.
bitmap (wx.Bitmap) – Large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar.
bitmap_small (wx.Bitmap) – Small bitmap of the new button. If left as null, then a small bitmap will be automatically generated. Must be the same size as all other small bitmaps used on the button bar.
bitmap_disabled (wx.Bitmap) – Large bitmap of the new button when it is disabled. If left as null, then a bitmap will be automatically generated from bitmap.
bitmap_small_disabled (wx.Bitmap) – Small bitmap of the new button when it is disabled. If left as null, then a bitmap will be automatically generated from bitmap_small.
kind (RibbonButtonKind) – The kind of button to add.
help_string (string) – The UI help string to associate with the new button.

Return type:

RibbonButtonBarButtonBase

Returns:

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

New in version 2.9.4.

See also

InsertDropdownButton

See also

InsertHybridButton

See also

InsertToggleButton

See also

AddButton

InsertDropdownButton(self, pos, button_id, label, bitmap, help_string="")¶

Inserts a dropdown button to the button bar (simple version) at the given position.

Parameters:

pos (int) –
button_id (int) –
label (string) –
bitmap (wx.Bitmap) –
help_string (string) –

Return type:

RibbonButtonBarButtonBase

New in version 2.9.4.

See also

InsertButton

See also

AddDropdownButton

See also

AddButton

InsertHybridButton(self, pos, button_id, label, bitmap, help_string="")¶

Inserts a hybrid button to the button bar (simple version) at the given position.

Parameters:

pos (int) –
button_id (int) –
label (string) –
bitmap (wx.Bitmap) –
help_string (string) –

Return type:

RibbonButtonBarButtonBase

New in version 2.9.4.

See also

InsertButton

See also

AddHybridButton

See also

AddButton

InsertToggleButton(self, pos, button_id, label, bitmap, help_string="")¶

Inserts a toggle button to the button bar (simple version) at the given position.

Parameters:

pos (int) –
button_id (int) –
label (string) –
bitmap (wx.Bitmap) –
help_string (string) –

Return type:

RibbonButtonBarButtonBase

New in version 2.9.4.

See also

InsertButton

See also

AddToggleButton

See also

AddButton

Realize(self)¶

Calculate button layouts and positions.

Must be called after buttons are added to the button bar, as otherwise the newly added buttons will not be displayed. In normal situations, it will be called automatically when wx.ribbon.RibbonBar.Realize is called.

Return type:: bool

SetButtonIcon(self, button_id, bitmap, bitmap_small=NullBitmap, bitmap_disabled=NullBitmap, bitmap_small_disabled=NullBitmap)¶

Changes the bitmap of an existing button.

Parameters:

button_id (int) – ID of the button to manipulate.
bitmap (wx.Bitmap) – Large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar.
bitmap_small (wx.Bitmap) – Small bitmap of the new button. If left as null, then a small bitmap will be automatically generated. Must be the same size as all other small bitmaps used on the button bar.
bitmap_disabled (wx.Bitmap) – Large bitmap of the new button when it is disabled. If left as null, then a bitmap will be automatically generated from bitmap.
bitmap_small_disabled (wx.Bitmap) – Small bitmap of the new button when it is disabled. If left as null, then a bitmap will be automatically generated from bitmap_small.

New in version 4.1/wxWidgets-3.1.2.

SetButtonMaxSizeClass(self, button_id, max_size_class)¶

Sets the maximum size class of a ribbon button.

You have to call Realize after calling this function to apply the given maximum size.

Parameters:

button_id (int) – ID of the button to manipulate.
max_size_class (RibbonButtonBarButtonState) – The maximum size-class of the button. Buttons on a button bar can have three distinct sizes: wx.ribbon.RIBBON_BUTTONBAR_BUTTON_SMALL, wx.ribbon.RIBBON_BUTTONBAR_BUTTON_MEDIUM, and wx.ribbon.RIBBON_BUTTONBAR_BUTTON_LARGE.

New in version 4.1/wxWidgets-3.1.2.

SetButtonMinSizeClass(self, button_id, min_size_class)¶

Sets the minimum size class of a ribbon button.

You have to call Realize after calling this function to apply the given minimum size.

Parameters:

button_id (int) – ID of the button to manipulate.
min_size_class (RibbonButtonBarButtonState) – The minimum size-class of the button. Buttons on a button bar can have three distinct sizes: wx.ribbon.RIBBON_BUTTONBAR_BUTTON_SMALL, wx.ribbon.RIBBON_BUTTONBAR_BUTTON_MEDIUM, and wx.ribbon.RIBBON_BUTTONBAR_BUTTON_LARGE.

New in version 4.1/wxWidgets-3.1.2.

SetButtonText(self, button_id, label)¶

Changes the label text of an existing button.

Parameters:

button_id (int) – ID of the button to manipulate.
label (string) – New label of the button.

New in version 4.1/wxWidgets-3.1.2.

Note

If text size has changed, Realize must be called on the top level wx.ribbon.RibbonBar object to recalculate panel sizes. Use SetButtonTextMinWidth to avoid calling Realize after every change.

See also

SetButtonTextMinWidth

SetButtonTextMinWidth(self, *args, **kw)¶

Overloaded Implementations:

SetButtonTextMinWidth (self, button_id, min_width_medium, min_width_large)

Sets the minimum width of the button label, to indicate to the wx.ribbon.RibbonArtProvider layout mechanism that this is the minimum required size.

You have to call Realize after calling this function to apply the given minimum width.

Parameters:

button_id (int) – ID of the button to manipulate.
min_width_medium (int) – Requested minimum width of the button text in pixel if the button is medium size.
min_width_large (int) – Requested minimum width of the button text in pixel if the button is large size.

New in version 4.1/wxWidgets-3.1.2.

Note

This function is used together with SetButtonText to change button labels on the fly without modifying the button bar layout.

See also

SetButtonText

SetButtonTextMinWidth (self, button_id, label)

Sets the minimum width of the button label, to indicate to the wx.ribbon.RibbonArtProvider layout mechanism that this is the minimum required size.

You have to call Realize after calling this function to apply the given minimum width.

Parameters:

button_id (int) – ID of the button to manipulate.
label (string) – The minimum width is set to the width of this label.

New in version 4.1/wxWidgets-3.1.2.

Note

This function is used together with SetButtonText to change button labels on the fly without modifying the button bar layout.

See also

SetButtonText

SetItemClientData(self, item, data)¶

Set the client object associated with a button.

The button bar owns the given object and takes care of its deletion. Please, note that you cannot use both client object and client data.

Parameters:

item (RibbonButtonBarButtonBase) –
data (ClientData) –

New in version 2.9.5.

SetShowToolTipsForDisabled(self, show)¶

Indicates whether tooltips are shown for disabled buttons.

By default they are not shown.

Parameters:: show (bool) –

New in version 2.9.5.

ToggleButton(self, button_id, checked)¶

Set a toggle button to the checked or unchecked state.

Parameters:

button_id (int) – ID of the toggle button to manipulate.
checked (bool) – True to set the button to the toggled/pressed/checked state, False to set it to the untoggled/unpressed/unchecked state.

Properties¶

ActiveItem¶: See GetActiveItem

ButtonCount¶: See GetButtonCount

HoveredItem¶: See GetHoveredItem

ShowToolTipsForDisabled¶: See GetShowToolTipsForDisabled and SetShowToolTipsForDisabled

Navigation

wx.ribbon.RibbonButtonBar¶

Events Emitted by this Class¶

Class Hierarchy¶

Methods Summary¶

Properties Summary¶

Class API¶

Methods¶

Properties¶