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¶