.. wxPython Phoenix documentation

   This file was generated by Phoenix's sphinx generator and associated
   tools, do not edit by hand.

   Copyright: (c) 2011-2020 by Total Control Software
   License:   wxWindows License

.. include:: headings.inc

.. currentmodule:: wx.lib.agw.ribbon.gallery

.. highlight:: python



.. _wx.lib.agw.ribbon.gallery.RibbonGallery:

==========================================================================================================================================
|phoenix_title|  **wx.lib.agw.ribbon.gallery.RibbonGallery**
==========================================================================================================================================

A ribbon gallery is like a :class:`ListBox`, but for bitmaps rather than strings.



|

|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>RibbonGallery</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.lib.agw.ribbon.gallery.RibbonGallery_inheritance.png" alt="Inheritance diagram of RibbonGallery" 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.lib.agw.ribbon.gallery.RibbonGallery.html" title="A ribbon gallery is like a ListBox, but for bitmaps rather than strings." alt="" coords="7,469,274,499"/> <area shape="rect" id="node2" href="wx.lib.agw.ribbon.control.RibbonControl.html" title="Base class for all the Ribbon stuff." alt="" coords="5,392,276,421"/> <area shape="rect" id="node3" href="wx.Control.html" title="This is the base class for a control or 'widget'." alt="" coords="97,315,185,344"/> <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="96,237,185,267"/> <area shape="rect" id="node5" href="wx.WindowBase.html" title="wx.WindowBase" alt="" coords="80,160,201,189"/> <area shape="rect" id="node6" href="wx.EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="85,83,197,112"/> <area shape="rect" id="node7" href="wx.Object.html" title="This is the root class of many of the wxWidgets classes." alt="" coords="41,5,123,35"/> <area shape="rect" id="node8" href="wx.Trackable.html" title="Add-on base class for a trackable object." alt="" coords="148,5,251,35"/> </map> 
   </p>
   </div>

|


|appearance| Control Appearance
===============================

|

.. figure:: _static/images/widgets/fullsize/wxmsw/wx.lib.agw.ribbon.gallery.ribbongallery.png
   :alt: wxMSW
   :figclass: floatleft

   **wxMSW**


.. figure:: _static/images/widgets/fullsize/wxmac/../no_appearance.png
   :alt: wxMAC
   :figclass: floatright

   **wxMAC**


.. figure:: _static/images/widgets/fullsize/wxgtk/wx.lib.agw.ribbon.gallery.ribbongallery.png
   :alt: wxGTK
   :figclass: floatcenter

   **wxGTK**


|




|super_classes| Known Superclasses
==================================

:class:`wx.lib.agw.ribbon.control.RibbonControl`

|


|method_summary| Methods Summary
================================

================================================================================ ================================================================================
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.__init__`                        Default class constructor.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.Append`                          Add an item to the gallery (with complex client data).
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.CalculateMinSize`                
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.Clear`                           Remove all items from the gallery.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.CommonInit`                      
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.DoGetBestSize`                   Gets the size which best suits the window: for a control, it would be the
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.DoGetNextLargerSize`             Implementation of :meth:`RibbonControl.GetNextLargerSize() <lib.agw.ribbon.control.RibbonControl.GetNextLargerSize>`.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.DoGetNextSmallerSize`            Implementation of :meth:`RibbonControl.GetNextSmallerSize() <lib.agw.ribbon.control.RibbonControl.GetNextSmallerSize>`.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.EnsureVisible`                   Scroll the gallery to ensure that the given item is visible.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.GetActiveItem`                   Get the currently active item, or ``None`` if there is none.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.GetCount`                        Get the number of items in the gallery.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.GetDefaultBorder`                Returns the default border style for :class:`RibbonGallery`.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.GetDownButtonState`              Get the state of the scroll down button.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.GetExtensionButtonState`         Get the state of the "extension" button.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.GetHoveredItem`                  Get the currently hovered item, or ``None`` if there is none.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.GetItem`                         Get an item by index.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.GetItemClientData`               Get the client data associated with a gallery item.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.GetSelection`                    Get the currently selected item, or ``None`` if there is none.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.GetUpButtonState`                Get the state of the scroll up button.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.IsEmpty`                         Query if the gallery has no items in it.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.IsHovered`                       Query is the mouse is currently hovered over the gallery.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.IsSizingContinuous`              Returns ``True`` if this window can take any size (greater than its minimum size),
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.Layout`                          Layout() -> bool
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.OnEraseBackground`               Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`RibbonGallery`.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.OnMouseDClick`                   Handles the ``wx.EVT_LEFT_DCLICK`` event for :class:`RibbonGallery`.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.OnMouseDown`                     Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`RibbonGallery`.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.OnMouseEnter`                    Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`RibbonGallery`.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.OnMouseLeave`                    Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`RibbonGallery`.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.OnMouseMove`                     Handles the ``wx.EVT_MOTION`` event for :class:`RibbonGallery`.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.OnMouseUp`                       Handles the ``wx.EVT_LEFT_UP`` event for :class:`RibbonGallery`.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.OnPaint`                         Handles the ``wx.EVT_PAINT`` event for :class:`RibbonGallery`.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.OnSize`                          Handles the ``wx.EVT_SIZE`` event for :class:`RibbonGallery`.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.Realize`                         Perform initial size and layout calculations after children have been added,
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.ScrollLines`                     Scroll the gallery contents by some amount.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.SetItemClientData`               Set the client data associated with a gallery item.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.SetSelection`                    Set the selection to the given item, or removes the selection if `item` == ``None``.
:meth:`~wx.lib.agw.ribbon.gallery.RibbonGallery.TestButtonHover`                 
================================================================================ ================================================================================


|


|api| Class API
===============


.. class:: RibbonGallery(RibbonControl)

   A ribbon gallery is like a :class:`ListBox`, but for bitmaps rather than strings.

   .. method:: __init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, agwStyle=0, name="RibbonGallery")

      Default class constructor.
      
      :param `parent`: pointer to a parent window, typically a :class:`~wx.lib.agw.ribbon.panel.RibbonPanel`;
      :param `id`: window identifier. If ``wx.ID_ANY``, will automatically create an
       identifier;
      :param `pos`: window position. ``wx.DefaultPosition`` indicates that wxPython
       should generate a default position for the window;
      :param `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;
      :param `agwStyle`: the AGW-specific window style, currently unused;
      :param `name`: the window name.


   .. method:: Append(self, bitmap, id, clientData=None)

      Add an item to the gallery (with complex client data).
      
      :param `bitmap`: the bitmap to display for the item. Note that all items must
       have equally sized bitmaps;
      :param `id`: id number to associate with the item. Not currently used for
       anything important;
      :param `clientData`: an object which contains data to associate with the item.
       The item takes ownership of this pointer, and will delete it when the item
       client data is changed to something else, or when the item is destroyed.


   .. method:: CalculateMinSize(self)


   .. method:: Clear(self)

      Remove all items from the gallery.


   .. method:: CommonInit(self, agwStyle)


   .. method:: 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()`.
      
      :return: An instance of :class:`wx.Size`.
      
      .. note:: Overridden from :class:`wx.Control`.


   .. method:: DoGetNextLargerSize(self, direction, relative_to)

      Implementation of :meth:`RibbonControl.GetNextLargerSize() <lib.agw.ribbon.control.RibbonControl.GetNextLargerSize>`.
      
      Controls which have non-continuous sizing must override this virtual function
      rather than :meth:`RibbonControl.GetNextLargerSize() <lib.agw.ribbon.control.RibbonControl.GetNextLargerSize>`.


   .. method:: DoGetNextSmallerSize(self, direction, relative_to)

      Implementation of :meth:`RibbonControl.GetNextSmallerSize() <lib.agw.ribbon.control.RibbonControl.GetNextSmallerSize>`.
      
      Controls which have non-continuous sizing must override this virtual function
      rather than :meth:`RibbonControl.GetNextSmallerSize() <lib.agw.ribbon.control.RibbonControl.GetNextSmallerSize>`.


   .. method:: EnsureVisible(self, item)

      Scroll the gallery to ensure that the given item is visible.
      
      :param `item`: an instance of :class:`RibbonGalleryItem`.


   .. method:: GetActiveItem(self)

      Get the currently active item, or ``None`` if there is none.
      
      The active item is the item being pressed by the user, and will thus become the
      selected item if the user releases the mouse button.


   .. method:: GetCount(self)

      Get the number of items in the gallery.


   .. method:: GetDefaultBorder(self)

      Returns the default border style for :class:`RibbonGallery`. 


   .. method:: GetDownButtonState(self)

      Get the state of the scroll down button.


   .. method:: GetExtensionButtonState(self)

      Get the state of the "extension" button.


   .. method:: GetHoveredItem(self)

      Get the currently hovered item, or ``None`` if there is none.
      
      The hovered item is the item underneath the mouse cursor.


   .. method:: GetItem(self, n)

      Get an item by index.
      
      :param `n`: the zero-based item in the gallery, which is an instance of :class:`RibbonGalleryItem`.


   .. method:: GetItemClientData(self, item)

      Get the client data associated with a gallery item.
      
      :param `item`: an instance of :class:`RibbonGalleryItem`.


   .. method:: GetSelection(self)

      Get the currently selected item, or ``None`` if there is none.
      
      The selected item is set by :meth:`~RibbonGallery.SetSelection`, or by the user clicking on an item.


   .. method:: GetUpButtonState(self)

      Get the state of the scroll up button.


   .. method:: IsEmpty(self)

      Query if the gallery has no items in it.


   .. method:: IsHovered(self)

      Query is the mouse is currently hovered over the gallery.
      
      :returns: ``True`` if the cursor is within the bounds of the gallery (not
       just hovering over an item), ``False`` otherwise.


   .. method:: IsSizingContinuous(self)

      Returns ``True`` if this window can take any size (greater than its minimum size),
      ``False`` if it can only take certain sizes.
      
      .. seealso:: :meth:`RibbonControl.GetNextSmallerSize() <lib.agw.ribbon.control.RibbonControl.GetNextSmallerSize>`,
       :meth:`RibbonControl.GetNextLargerSize() <lib.agw.ribbon.control.RibbonControl.GetNextLargerSize>`


   .. method:: Layout(self)

      Layout() -> bool
      
      Lays out the children of this window using the associated sizer.


   .. method:: OnEraseBackground(self, event)

      Handles the ``wx.EVT_ERASE_BACKGROUND`` event for :class:`RibbonGallery`.
      
      :param `event`: a :class:`EraseEvent` event to be processed.


   .. method:: OnMouseDClick(self, event)

      Handles the ``wx.EVT_LEFT_DCLICK`` event for :class:`RibbonGallery`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseDown(self, event)

      Handles the ``wx.EVT_LEFT_DOWN`` event for :class:`RibbonGallery`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseEnter(self, event)

      Handles the ``wx.EVT_ENTER_WINDOW`` event for :class:`RibbonGallery`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseLeave(self, event)

      Handles the ``wx.EVT_LEAVE_WINDOW`` event for :class:`RibbonGallery`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseMove(self, event)

      Handles the ``wx.EVT_MOTION`` event for :class:`RibbonGallery`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnMouseUp(self, event)

      Handles the ``wx.EVT_LEFT_UP`` event for :class:`RibbonGallery`.
      
      :param `event`: a :class:`MouseEvent` event to be processed.


   .. method:: OnPaint(self, event)

      Handles the ``wx.EVT_PAINT`` event for :class:`RibbonGallery`.
      
      :param `event`: a :class:`PaintEvent` event to be processed.


   .. method:: OnSize(self, event)

      Handles the ``wx.EVT_SIZE`` event for :class:`RibbonGallery`.
      
      :param `event`: a :class:`wx.SizeEvent` event to be processed.


   .. method:: Realize(self)

      Perform initial size and layout calculations after children have been added,
      and/or realize children.


   .. method:: ScrollLines(self, lines)

      Scroll the gallery contents by some amount.
      
      :param `lines`: Positive values scroll toward the end of the gallery, while
       negative values scroll toward the start.
      
      :returns: ``True`` if the gallery scrolled at least one pixel in the given
       direction, ``False`` if it did not scroll.
      
      .. note:: Reimplemented from :class:`wx.Window`.


   .. method:: SetItemClientData(self, item, data)

      Set the client data associated with a gallery item.
      
      :param `item`: an instance of :class:`RibbonGalleryItem`;
      :param `data`: any Python object.


   .. method:: SetSelection(self, item)

      Set the selection to the given item, or removes the selection if `item` == ``None``.
      
      Note that this not cause any events to be emitted.
      
      :param `item`: an instance of :class:`RibbonGalleryItem`, can also be ``None`` to remove the selection.


   .. method:: TestButtonHover(self, rect, pos, state)