Phoenix Logo

phoenix_title wx.lib.agw.ribbon.buttonbar.RibbonButtonBar

A ribbon button bar is similar to a traditional toolbar.


class_hierarchy Class Hierarchy

Inheritance diagram for class RibbonButtonBar:

appearance Control Appearance


wxMSW

wxMSW

wxMAC

wxMAC

wxGTK

wxGTK


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

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