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


super_classes Known Superclasses

wx.lib.agw.ribbon.control.RibbonControl


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.

See also

AddButton, InsertButton, AddDropdownButton

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.

See also

AddButton, InsertButton, AddHybridButton

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.

See also

AddButton, InsertButton, AddToggleButton

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.