phoenix_title 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 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 Class Hierarchy

Inheritance diagram for class RibbonButtonBar:

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


api 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)

overload 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)

overload Overloaded Implementations:



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

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

Parameters
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

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
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)

overload 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

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

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.



SetButtonTextMinWidth(self, *args, **kw)

overload 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

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