wx.lib.agw.ribbon.buttonbar.RibbonButtonBar¶

A ribbon button bar is similar to a traditional toolbar.

Class Hierarchy¶

Inheritance diagram for class RibbonButtonBar:

Control Appearance¶

wxMSW¶

wxMAC¶

wxGTK¶

Known Superclasses¶

wx.lib.agw.ribbon.control.RibbonControl

Methods Summary¶

`__init__`	Default class constructor.
`AddButton`	Add a button to the button bar.
`AddDropdownButton`	Add a dropdown button to the button bar (simple version).
`AddHybridButton`	Add a hybrid button to the button bar (simple version).
`AddSimpleButton`	Add a button to the button bar (simple version).
`AddToggleButton`	Add a toggle button to the button bar.
`ClearButtons`	Delete all buttons from the button bar.
`CommonInit`	Common initialization procedures.
`DeleteButton`	Delete a single button from the button bar.
`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()`.
`EnableButton`	Enable or disable a single button on the bar.
`FetchButtonSizeInfo`
`GetButtonCount`	Returns the number of buttons in this `RibbonButtonBar`.
`GetDefaultBorder`	Returns the default border style for `RibbonButtonBar`.
`GetMinSize`	Returns the minimum size of the window, an indication to the sizer layout mechanism
`InsertButton`	Inserts a button in the button bar at the position specified by pos.
`InsertDropdownButton`	Inserts a dropdown button in the button bar at the position specified by pos.
`InsertHybridButton`	Inserts a hybrid button in the button bar at the position specified by pos.
`InsertToggleButton`	Inserts a toggle button in the button bar at the position specified by pos.
`IsButtonEnabled`	Returns whether a button in the bar is enabled or not.
`IsSizingContinuous`	Returns `True` if this window can take any size (greater than its minimum size),
`MakeDisabledBitmap`	Converts the original bitmap into a visually-looking disabled one.
`MakeLayouts`
`MakeResizedBitmap`	Resize and scale the original bitmap to the dimensions specified in size.
`OnEraseBackground`	Handles the `wx.EVT_ERASE_BACKGROUND` event for `RibbonButtonBar`.
`OnMouseDown`	Handles the `wx.EVT_LEFT_DOWN` event for `RibbonButtonBar`.
`OnMouseEnter`	Handles the `wx.EVT_ENTER_WINDOW` event for `RibbonButtonBar`.
`OnMouseLeave`	Handles the `wx.EVT_LEAVE_WINDOW` event for `RibbonButtonBar`.
`OnMouseMove`	Handles the `wx.EVT_MOTION` event for `RibbonButtonBar`.
`OnMouseUp`	Handles the `wx.EVT_LEFT_UP` event for `RibbonButtonBar`.
`OnPaint`	Handles the `wx.EVT_PAINT` event for `RibbonButtonBar`.
`OnSize`	Handles the `wx.EVT_SIZE` event for `RibbonButtonBar`.
`Realize`	Calculate button layouts and positions.
`SetArtProvider`	Set the art provider to be used.
`ToggleButton`	Toggles/untoggles a `RibbonButtonBar` toggle button.
`TryCollapseLayout`
`UpdateWindowUI`	This function sends one or more `UpdateUIEvent` to the window.

Class API¶

class RibbonButtonBar(RibbonControl)¶

A ribbon button bar is similar to a traditional toolbar.

Methods¶

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, agwStyle=0)¶

Default class constructor.

Parameters

parent (wx.Window) – pointer to a parent window, typically a RibbonPanel;
id (integer) – window identifier. If wx.ID_ANY, will automatically create an identifier;
pos (tuple or wx.Point) – window position. wx.DefaultPosition indicates that wxPython should generate a default position for the window;
size (tuple or wx.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;
agwStyle (integer) – the AGW-specific window style, currently unused.

AddButton(self, button_id, label, bitmap, bitmap_small=wx.NullBitmap, bitmap_disabled=wx.NullBitmap, bitmap_small_disabled=wx.NullBitmap, kind=RIBBON_BUTTON_NORMAL, help_string="", client_data=None)¶

Add a button to the button bar.

Parameters

button_id (integer) – id of the new button (used for event callbacks);
label (string) – label of the new button;
bitmap – large bitmap of the new button, an instance of wx.Bitmap. Must be the same size as all other large bitmaps used on the button bar;
bitmap_small – small bitmap of the new button, an instance of wx.Bitmap. If left as NullBitmap, 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 – large bitmap of the new button when it is disabled, an instance of wx.Bitmap. If left as NullBitmap, then a bitmap will be automatically generated from bitmap;
bitmap_small_disabled – small bitmap of the new button when it is disabled, an instance of wx.Bitmap. If left as NullBitmap, then a bitmap will be automatically generated from bitmap_small;

kind (integer) – the kind of button to add, one of the following values:

Button Kind	Hex Value	Description
`RIBBON_BUTTON_NORMAL`	0x1	Normal button or tool with a clickable area which causes some generic action.
`RIBBON_BUTTON_DROPDOWN`	0x2	Dropdown button or tool with a clickable area which typically causes a dropdown menu.
`RIBBON_BUTTON_HYBRID`	0x3	Button or tool with two clickable areas - one which causes a dropdown menu, and one which causes a generic action.
`RIBBON_BUTTON_TOGGLE`	0x4	Normal button or tool with a clickable area which toggles the button between a pressed and unpressed state.

help_string (string) – the UI help string to associate with the new button;
client_data (object) – client data to associate with the new button (any Python object).

Returns

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

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

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

Parameters

button_id (integer) – id of the new button (used for event callbacks);
label (string) – label of the new button;
bitmap – large bitmap of the new button, an instance of wx.Bitmap. Must be the same size as all other large bitmaps used on the button bar;
help_string (string) – the UI help string to associate with the new button.

Returns

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

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

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

Parameters

button_id (integer) – id of the new button (used for event callbacks);
label (string) – label of the new button;
bitmap – large bitmap of the new button, an instance of wx.Bitmap. Must be the same size as all other large bitmaps used on the button bar;
help_string (string) – the UI help string to associate with the new button.

Returns

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

AddSimpleButton(self, button_id, label, bitmap, help_string, kind=RIBBON_BUTTON_NORMAL)¶

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

Parameters

button_id (integer) – id of the new button (used for event callbacks);
label (string) – label of the new button;
bitmap – large bitmap of the new button, an instance of wx.Bitmap. Must be the same size as all other large bitmaps used on the button bar;
help_string (string) – the UI help string to associate with the new button;
kind (integer) – the kind of button to add.

Returns

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

See also

AddButton for a list of valid button kind values.

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

Add a toggle button to the button bar.

Parameters

button_id (integer) – id of the new button (used for event callbacks);
label (string) – label of the new button;
bitmap – large bitmap of the new button, an instance of wx.Bitmap. Must be the same size as all other large bitmaps used on the button bar;
help_string (string) – the UI help string to associate with the new button.

Returns

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

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

See also

DeleteButton

CommonInit(self, agwStyle)¶

Common initialization procedures.

Parameters: agwStyle (integer) – the AGW-specific window style, currently unused.

DeleteButton(self, button_id)¶

Delete a single button from the button bar.

Parameters: button_id (integer) – id of the button to delete.
Returns: True if the button has been found and successfully deleted, False otherwise.

See also

ClearButtons

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, _result)¶

Implementation of RibbonControl.GetNextLargerSize().

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

Returns: An instance of wx.Size.

DoGetNextSmallerSize(self, direction, _result)¶

Implementation of RibbonControl.GetNextSmallerSize().

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

Returns: An instance of wx.Size.

EnableButton(self, button_id, enable=True)¶

Enable or disable a single button on the bar.

Parameters

button_id (integer) – id of the button to enable or disable;
enable (bool) – True to enable the button, False to disable it.

Raise

Exception when the input button_id could not be associated with a RibbonButtonBar button.

FetchButtonSizeInfo(self, button, size, dc)¶

GetButtonCount(self)¶: Returns the number of buttons in this RibbonButtonBar.

New in version 0.9.5.

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

GetMinSize(self)¶

Returns the minimum size of the window, an indication to the sizer layout mechanism that this is the minimum required size.

This method normally just returns the value set by SetMinSize, but it can be overridden to do the calculation on demand.

Returns: An instance of wx.Size.

InsertButton(self, pos, button_id, label, bitmap, bitmap_small=wx.NullBitmap, bitmap_disabled=wx.NullBitmap, bitmap_small_disabled=wx.NullBitmap, kind=RIBBON_BUTTON_NORMAL, help_string="", client_data=None)¶

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

Parameters

pos (integer) – the position at which the new button must be inserted (zero-based);
button_id (integer) – id of the new button (used for event callbacks);
label (string) – label of the new button;
bitmap – large bitmap of the new button, an instance of wx.Bitmap. Must be the same size as all other large bitmaps used on the button bar;
bitmap_small – small bitmap of the new button, an instance of wx.Bitmap. If left as NullBitmap, 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 – large bitmap of the new button when it is disabled, an instance of wx.Bitmap. If left as NullBitmap, then a bitmap will be automatically generated from bitmap;
bitmap_small_disabled – small bitmap of the new button when it is disabled, an instance of wx.Bitmap. If left as NullBitmap, then a bitmap will be automatically generated from bitmap_small;
kind (integer) – the kind of button to add;
help_string (string) – the UI help string to associate with the new button;
client_data (object) – client data to associate with the new button.

Returns

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

Raise

Exception if both bitmap and bitmap_small are invalid or if the input help_string is not a valid Python basestring.

See also

AddDropdownButton, AddHybridButton and AddButton for a list of valid button kind values.

New in version 0.9.5.

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

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

Parameters

pos (integer) – the position at which the new button must be inserted (zero-based);
button_id (integer) – id of the new button (used for event callbacks);
label (string) – label of the new button;
bitmap – large bitmap of the new button, an instance of wx.Bitmap. Must be the same size as all other large bitmaps used on the button bar;
help_string (string) – the UI help string to associate with the new button.

Returns

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

New in version 0.9.5.

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

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

Parameters

pos (integer) – the position at which the new button must be inserted (zero-based);
button_id (integer) – id of the new button (used for event callbacks);
label (string) – label of the new button;
bitmap – large bitmap of the new button, an instance of wx.Bitmap. Must be the same size as all other large bitmaps used on the button bar;
help_string (string) – the UI help string to associate with the new button.

Returns

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

New in version 0.9.5.

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

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

Parameters

pos (integer) – the position at which the new button must be inserted (zero-based);
button_id (integer) – id of the new button (used for event callbacks);
label (string) – label of the new button;
bitmap – large bitmap of the new button, an instance of wx.Bitmap. Must be the same size as all other large bitmaps used on the button bar;
help_string (string) – the UI help string to associate with the new button.

Returns

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

New in version 0.9.5.

IsButtonEnabled(self, button_id)¶

Returns whether a button in the bar is enabled or not.

Parameters: button_id (integer) – id of the button to check.
Returns: True if the button is enabled, False otherwise.
Raise: Exception when the input button_id could not be associated with a RibbonButtonBar button.

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

Converts the original bitmap into a visually-looking disabled one.

Parameters: original – the original bitmap, an instance of wx.Bitmap.
Returns: A visually-looking disabled representation of the input bitmap.

MakeLayouts(self)¶

MakeResizedBitmap(self, original, size)¶

Resize and scale the original bitmap to the dimensions specified in size.

Parameters

original – the original bitmap, an instance of wx.Bitmap;
size – the size to which the input bitmap must be rescaled, an instance of wx.Size.

Returns

A scaled representation of the input bitmap.

OnEraseBackground(self, event)¶

Handles the wx.EVT_ERASE_BACKGROUND event for RibbonButtonBar.

Parameters: event – a EraseEvent event to be processed.

OnMouseDown(self, event)¶

Handles the wx.EVT_LEFT_DOWN event for RibbonButtonBar.

Parameters: event – a MouseEvent event to be processed.

OnMouseEnter(self, event)¶

Handles the wx.EVT_ENTER_WINDOW event for RibbonButtonBar.

Parameters: event – a MouseEvent event to be processed.

OnMouseLeave(self, event)¶

Handles the wx.EVT_LEAVE_WINDOW event for RibbonButtonBar.

Parameters: event – a MouseEvent event to be processed.

OnMouseMove(self, event)¶

Handles the wx.EVT_MOTION event for RibbonButtonBar.

Parameters: event – a MouseEvent event to be processed.

OnMouseUp(self, event)¶

Handles the wx.EVT_LEFT_UP event for RibbonButtonBar.

Parameters: event – a MouseEvent event to be processed.

OnPaint(self, event)¶

Handles the wx.EVT_PAINT event for RibbonButtonBar.

Parameters: event – a PaintEvent event to be processed.

OnSize(self, event)¶

Handles the wx.EVT_SIZE event for RibbonButtonBar.

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

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 RibbonBar.Realize() is called.

Note

Reimplemented from RibbonControl.

SetArtProvider(self, art)¶

Set the art provider to be used.

In many cases, setting the art provider will also set the art provider on all child windows which extend RibbonControl. In most cases, controls will not take ownership of the given pointer, with the notable exception being RibbonBar.SetArtProvider().

Parameters: art – an art provider.

ToggleButton(self, button_id, checked=True)¶

Toggles/untoggles a RibbonButtonBar toggle button.

Parameters

button_id (integer) – id of the button to be toggles/untoggled;
checked (bool) – True to toggle the button, False to untoggle it.

Raise

Exception when the input button_id could not be associated with a RibbonButtonBar button.

TryCollapseLayout(self, original, first_btn, last_button=None)¶

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)

New in version 0.9.5.

Navigation

wx.lib.agw.ribbon.buttonbar.RibbonButtonBar¶

Class Hierarchy¶

Control Appearance¶

Known Superclasses¶

Methods Summary¶

Class API¶

Methods¶