.. wxPython Phoenix documentation
This file was generated by Phoenix's sphinx generator and associated
tools, do not edit by hand.
Copyright: (c) 2011-2018 by Total Control Software
License: wxWindows License
.. include:: headings.inc
.. _wx.ribbon.RibbonButtonBar:
==========================================================================================================================================
|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 :ref:`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.
.. _RibbonButtonBar-events:
|events| Events Emitted by this Class
=====================================
Handlers bound for the following event types will receive a :ref:`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. :meth:`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
=================================
.. raw:: html
<div id="toggleBlock" onclick="return toggleVisibility(this)" class="closed" style="cursor:pointer;">
<img id="toggleBlock-trigger" src="_static/images/closed.png"/>
Inheritance diagram for class <strong>RibbonButtonBar</strong>:
</div>
<div id="toggleBlock-summary" style="display:block;"></div>
<div id="toggleBlock-content" style="display:none;">
<p class="graphviz">
<center><img src="_static/images/inheritance/wx.ribbon.RibbonButtonBar_inheritance.png" alt="Inheritance diagram of RibbonButtonBar" usemap="#dummy" class="inheritance"/></center>
<script type="text/javascript">toggleVisibilityOnLoad(document.getElementById('toggleBlock'))</script>
<map id="dummy" name="dummy"> <area shape="rect" id="node1" href="wx.ribbon.RibbonButtonBar.html" title="A ribbon button bar is similar to a traditional toolbar." alt="" coords="8,392,213,421"/> <area shape="rect" id="node2" href="wx.ribbon.RibbonControl.html" title="wx.ribbon.RibbonControl serves as a base class for all controls which share the ribbon characteristics of having a ribbon art provider, and (optionally) non-continuous resizing." alt="" coords="17,315,204,344"/> <area shape="rect" id="node3" href="wx.Control.html" title="This is the base class for a control or 'widget'." alt="" coords="64,237,157,267"/> <area shape="rect" id="node4" href="wx.Window.html" title="wx.Window is the base class for all windows and represents any visible object on screen." alt="" coords="62,160,159,189"/> <area shape="rect" id="node5" href="wx.EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="51,83,170,112"/> <area shape="rect" id="node6" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="5,5,93,35"/> <area shape="rect" id="node7" href="wx.Trackable.html" title="Add-on base class for a trackable object." alt="" coords="118,5,229,35"/> </map>
</p>
</div>
|
|method_summary| Methods Summary
================================
================================================================================ ================================================================================
:meth:`~wx.ribbon.RibbonButtonBar.__init__` Default constructor.
:meth:`~wx.ribbon.RibbonButtonBar.AddButton` Add a button to the button bar (simple version).
:meth:`~wx.ribbon.RibbonButtonBar.AddDropdownButton` Add a dropdown button to the button bar (simple version).
:meth:`~wx.ribbon.RibbonButtonBar.AddHybridButton` Add a hybrid button to the button bar (simple version).
:meth:`~wx.ribbon.RibbonButtonBar.AddToggleButton` Add a toggle button to the button bar (simple version).
:meth:`~wx.ribbon.RibbonButtonBar.ClearButtons` Delete all buttons from the button bar.
:meth:`~wx.ribbon.RibbonButtonBar.Create` Create a button bar in two-step button bar construction.
:meth:`~wx.ribbon.RibbonButtonBar.DeleteButton` Delete a single button from the button bar.
:meth:`~wx.ribbon.RibbonButtonBar.EnableButton` Enable or disable a single button on the bar.
:meth:`~wx.ribbon.RibbonButtonBar.GetActiveItem` Returns the active item of the button bar or ``None`` if there is none.
:meth:`~wx.ribbon.RibbonButtonBar.GetButtonCount` Returns the number of buttons in this button bar.
:meth:`~wx.ribbon.RibbonButtonBar.GetClassDefaultAttributes`
:meth:`~wx.ribbon.RibbonButtonBar.GetHoveredItem` Returns the hovered item of the button bar or ``None`` if there is none.
:meth:`~wx.ribbon.RibbonButtonBar.GetItem` Returns the N-th button of the bar.
:meth:`~wx.ribbon.RibbonButtonBar.GetItemById` Returns the first button having a given id or ``None`` if none matches.
:meth:`~wx.ribbon.RibbonButtonBar.GetItemClientData` Get the client object associated with a button.
:meth:`~wx.ribbon.RibbonButtonBar.GetItemId` Returns the id of a button.
:meth:`~wx.ribbon.RibbonButtonBar.GetShowToolTipsForDisabled` Sets whether tooltips should be shown for disabled buttons or not.
:meth:`~wx.ribbon.RibbonButtonBar.InsertButton` Inserts a button to the button bar (simple version) at the given position.
:meth:`~wx.ribbon.RibbonButtonBar.InsertDropdownButton` Inserts a dropdown button to the button bar (simple version) at the given position.
:meth:`~wx.ribbon.RibbonButtonBar.InsertHybridButton` Inserts a hybrid button to the button bar (simple version) at the given position.
:meth:`~wx.ribbon.RibbonButtonBar.InsertToggleButton` Inserts a toggle button to the button bar (simple version) at the given position.
:meth:`~wx.ribbon.RibbonButtonBar.Realize` Calculate button layouts and positions.
:meth:`~wx.ribbon.RibbonButtonBar.SetItemClientData` Set the client object associated with a button.
:meth:`~wx.ribbon.RibbonButtonBar.SetShowToolTipsForDisabled` Indicates whether tooltips are shown for disabled buttons.
:meth:`~wx.ribbon.RibbonButtonBar.ToggleButton` Set a toggle button to the checked or unchecked state.
================================================================================ ================================================================================
|
|property_summary| Properties Summary
=====================================
================================================================================ ================================================================================
:attr:`~wx.ribbon.RibbonButtonBar.ActiveItem` See :meth:`~wx.ribbon.RibbonButtonBar.GetActiveItem`
:attr:`~wx.ribbon.RibbonButtonBar.ButtonCount` See :meth:`~wx.ribbon.RibbonButtonBar.GetButtonCount`
:attr:`~wx.ribbon.RibbonButtonBar.HoveredItem` See :meth:`~wx.ribbon.RibbonButtonBar.GetHoveredItem`
:attr:`~wx.ribbon.RibbonButtonBar.ShowToolTipsForDisabled` See :meth:`~wx.ribbon.RibbonButtonBar.GetShowToolTipsForDisabled` and :meth:`~wx.ribbon.RibbonButtonBar.SetShowToolTipsForDisabled`
================================================================================ ================================================================================
|
|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.
.. method:: __init__(self, *args, **kw)
|overload| Overloaded Implementations:
:html:`<hr class="overloadsep" /><br />`
**__init__** `(self)`
Default constructor.
With this constructor, :meth:`Create` should be called in order to create the button bar.
:html:`<hr class="overloadsep" /><br />`
**__init__** `(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0)`
Construct a ribbon button bar with the given parameters.
:param `parent`: Parent window for the button bar (typically a :ref:`wx.ribbon.RibbonPanel`).
:type `parent`: wx.Window
:param `id`: An identifier for the button bar. ``ID_ANY`` is taken to mean a default.
:type `id`: wx.WindowID
:param `pos`: Initial position of the button bar.
:type `pos`: wx.Point
:param `size`: Initial size of the button bar.
:type `size`: wx.Size
:param `style`: Button bar style, currently unused.
:type `style`: long
:html:`<hr class="overloadsep" /><br />`
.. method:: AddButton(self, *args, **kw)
|overload| Overloaded Implementations:
:html:`<hr class="overloadsep" /><br />`
**AddButton** `(self, button_id, label, bitmap, help_string, kind=RIBBON_BUTTON_NORMAL)`
Add a button to the button bar (simple version).
:param `button_id`:
:type `button_id`: int
:param `label`:
:type `label`: string
:param `bitmap`:
:type `bitmap`: wx.Bitmap
:param `help_string`:
:type `help_string`: string
:param `kind`:
:type `kind`: wx.ribbon.RibbonButtonKind
:rtype: `RibbonButtonBarButtonBase`
:html:`<hr class="overloadsep" /><br />`
**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.
:param `button_id`: ``ID`` of the new button (used for event callbacks).
:type `button_id`: int
:param `label`: Label of the new button.
:type `label`: string
:param `bitmap`: Large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar.
:type `bitmap`: wx.Bitmap
:param `bitmap_small`: 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.
:type `bitmap_small`: wx.Bitmap
:param `bitmap_disabled`: Large bitmap of the new button when it is disabled. If left as null, then a bitmap will be automatically generated from `bitmap`.
:type `bitmap_disabled`: wx.Bitmap
:param `bitmap_small_disabled`: Small bitmap of the new button when it is disabled. If left as null, then a bitmap will be automatically generated from `bitmap_small`.
:type `bitmap_small_disabled`: wx.Bitmap
:param `kind`: The kind of button to add.
:type `kind`: wx.ribbon.RibbonButtonKind
:param `help_string`: The UI help string to associate with the new button.
:type `help_string`: string
:rtype: `RibbonButtonBarButtonBase`
:returns:
An opaque pointer which can be used only with other button bar methods.
.. seealso:: :meth:`AddDropdownButton`
.. seealso:: :meth:`AddHybridButton`
.. seealso:: :meth:`AddToggleButton`
:html:`<hr class="overloadsep" /><br />`
.. method:: AddDropdownButton(self, button_id, label, bitmap, help_string="")
Add a dropdown button to the button bar (simple version).
:param `button_id`:
:type `button_id`: int
:param `label`:
:type `label`: string
:param `bitmap`:
:type `bitmap`: wx.Bitmap
:param `help_string`:
:type `help_string`: string
:rtype: `RibbonButtonBarButtonBase`
.. seealso:: :meth:`AddButton`
.. method:: AddHybridButton(self, button_id, label, bitmap, help_string="")
Add a hybrid button to the button bar (simple version).
:param `button_id`:
:type `button_id`: int
:param `label`:
:type `label`: string
:param `bitmap`:
:type `bitmap`: wx.Bitmap
:param `help_string`:
:type `help_string`: string
:rtype: `RibbonButtonBarButtonBase`
.. seealso:: :meth:`AddButton`
.. method:: AddToggleButton(self, button_id, label, bitmap, help_string="")
Add a toggle button to the button bar (simple version).
:param `button_id`:
:type `button_id`: int
:param `label`:
:type `label`: string
:param `bitmap`:
:type `bitmap`: wx.Bitmap
:param `help_string`:
:type `help_string`: string
:rtype: `RibbonButtonBarButtonBase`
.. seealso:: :meth:`AddButton`
.. method:: ClearButtons(self)
Delete all buttons from the button bar.
.. seealso:: :meth:`DeleteButton`
.. method:: 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.
:param `parent`:
:type `parent`: wx.Window
:param `id`:
:type `id`: wx.WindowID
:param `pos`:
:type `pos`: wx.Point
:param `size`:
:type `size`: wx.Size
:param `style`:
:type `style`: long
:rtype: `bool`
.. method:: DeleteButton(self, button_id)
Delete a single button from the button bar.
:param `button_id`:
:type `button_id`: int
:rtype: `bool`
.. seealso:: :meth:`ClearButtons`
.. method:: EnableButton(self, button_id, enable=True)
Enable or disable a single button on the bar.
:param `button_id`: ``ID`` of the button to enable or disable.
:type `button_id`: int
:param `enable`: ``True`` to enable the button, ``False`` to disable it.
:type `enable`: bool
.. method:: GetActiveItem(self)
Returns the active item of the button bar or ``None`` if there is none.
The active button is the one being clicked.
:rtype: `RibbonButtonBarButtonBase`
.. versionadded:: 2.9.5
.. method:: GetButtonCount(self)
Returns the number of buttons in this button bar.
:rtype: `int`
.. versionadded:: 2.9.4
.. staticmethod:: GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)
:param `variant`:
:type `variant`: wx.WindowVariant
:rtype: `VisualAttributes`
.. method:: 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.
:rtype: `RibbonButtonBarButtonBase`
.. versionadded:: 2.9.5
.. method:: GetItem(self, n)
Returns the N-th button of the bar.
:param `n`:
:type `n`: int
:rtype: `RibbonButtonBarButtonBase`
.. versionadded:: 2.9.5
.. seealso:: :meth:`GetButtonCount`
.. method:: GetItemById(self, id)
Returns the first button having a given id or ``None`` if none matches.
:param `id`:
:type `id`: int
:rtype: `RibbonButtonBarButtonBase`
.. versionadded:: 2.9.5
.. method:: GetItemClientData(self, item)
Get the client object associated with a button.
:param `item`:
:type `item`: RibbonButtonBarButtonBase
:rtype: `ClientData`
.. versionadded:: 2.9.5
.. method:: GetItemId(self, item)
Returns the id of a button.
:param `item`:
:type `item`: RibbonButtonBarButtonBase
:rtype: `int`
.. versionadded:: 2.9.5
.. method:: 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.
:rtype: `bool`
.. versionadded:: 2.9.5
.. method:: InsertButton(self, *args, **kw)
|overload| Overloaded Implementations:
:html:`<hr class="overloadsep" /><br />`
**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.
:param `pos`:
:type `pos`: int
:param `button_id`:
:type `button_id`: int
:param `label`:
:type `label`: string
:param `bitmap`:
:type `bitmap`: wx.Bitmap
:param `help_string`:
:type `help_string`: string
:param `kind`:
:type `kind`: wx.ribbon.RibbonButtonKind
:rtype: `RibbonButtonBarButtonBase`
.. versionadded:: 2.9.4
.. seealso:: :meth:`AddButton`
:html:`<hr class="overloadsep" /><br />`
**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.
:param `pos`: Position of the new button in the button bar.
:type `pos`: int
:param `button_id`: ``ID`` of the new button (used for event callbacks).
:type `button_id`: int
:param `label`: Label of the new button.
:type `label`: string
:param `bitmap`: Large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar.
:type `bitmap`: wx.Bitmap
:param `bitmap_small`: 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.
:type `bitmap_small`: wx.Bitmap
:param `bitmap_disabled`: Large bitmap of the new button when it is disabled. If left as null, then a bitmap will be automatically generated from `bitmap`.
:type `bitmap_disabled`: wx.Bitmap
:param `bitmap_small_disabled`: Small bitmap of the new button when it is disabled. If left as null, then a bitmap will be automatically generated from `bitmap_small`.
:type `bitmap_small_disabled`: wx.Bitmap
:param `kind`: The kind of button to add.
:type `kind`: wx.ribbon.RibbonButtonKind
:param `help_string`: The UI help string to associate with the new button.
:type `help_string`: string
:rtype: `RibbonButtonBarButtonBase`
:returns:
An opaque pointer which can be used only with other button bar methods.
.. versionadded:: 2.9.4
.. seealso:: :meth:`InsertDropdownButton`
.. seealso:: :meth:`InsertHybridButton`
.. seealso:: :meth:`InsertToggleButton`
.. seealso:: :meth:`AddButton`
:html:`<hr class="overloadsep" /><br />`
.. method:: InsertDropdownButton(self, pos, button_id, label, bitmap, help_string="")
Inserts a dropdown button to the button bar (simple version) at the given position.
:param `pos`:
:type `pos`: int
:param `button_id`:
:type `button_id`: int
:param `label`:
:type `label`: string
:param `bitmap`:
:type `bitmap`: wx.Bitmap
:param `help_string`:
:type `help_string`: string
:rtype: `RibbonButtonBarButtonBase`
.. versionadded:: 2.9.4
.. seealso:: :meth:`InsertButton`
.. seealso:: :meth:`AddDropdownButton`
.. seealso:: :meth:`AddButton`
.. method:: InsertHybridButton(self, pos, button_id, label, bitmap, help_string="")
Inserts a hybrid button to the button bar (simple version) at the given position.
:param `pos`:
:type `pos`: int
:param `button_id`:
:type `button_id`: int
:param `label`:
:type `label`: string
:param `bitmap`:
:type `bitmap`: wx.Bitmap
:param `help_string`:
:type `help_string`: string
:rtype: `RibbonButtonBarButtonBase`
.. versionadded:: 2.9.4
.. seealso:: :meth:`InsertButton`
.. seealso:: :meth:`AddHybridButton`
.. seealso:: :meth:`AddButton`
.. method:: InsertToggleButton(self, pos, button_id, label, bitmap, help_string="")
Inserts a toggle button to the button bar (simple version) at the given position.
:param `pos`:
:type `pos`: int
:param `button_id`:
:type `button_id`: int
:param `label`:
:type `label`: string
:param `bitmap`:
:type `bitmap`: wx.Bitmap
:param `help_string`:
:type `help_string`: string
:rtype: `RibbonButtonBarButtonBase`
.. versionadded:: 2.9.4
.. seealso:: :meth:`InsertButton`
.. seealso:: :meth:`AddToggleButton`
.. seealso:: :meth:`AddButton`
.. method:: 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 :meth:`wx.ribbon.RibbonBar.Realize` is called.
:rtype: `bool`
.. method:: 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.
:param `item`:
:type `item`: RibbonButtonBarButtonBase
:param `data`:
:type `data`: ClientData
.. versionadded:: 2.9.5
.. method:: SetShowToolTipsForDisabled(self, show)
Indicates whether tooltips are shown for disabled buttons.
By default they are not shown.
:param `show`:
:type `show`: bool
.. versionadded:: 2.9.5
.. method:: ToggleButton(self, button_id, checked)
Set a toggle button to the checked or unchecked state.
:param `button_id`: ``ID`` of the toggle button to manipulate.
:type `button_id`: int
:param `checked`: ``True`` to set the button to the toggled/pressed/checked state, ``False`` to set it to the untoggled/unpressed/unchecked state.
:type `checked`: bool
.. attribute:: ActiveItem
See :meth:`~wx.ribbon.RibbonButtonBar.GetActiveItem`
.. attribute:: ButtonCount
See :meth:`~wx.ribbon.RibbonButtonBar.GetButtonCount`
.. attribute:: HoveredItem
See :meth:`~wx.ribbon.RibbonButtonBar.GetHoveredItem`
.. attribute:: ShowToolTipsForDisabled
See :meth:`~wx.ribbon.RibbonButtonBar.GetShowToolTipsForDisabled` and :meth:`~wx.ribbon.RibbonButtonBar.SetShowToolTipsForDisabled`