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



.. _wx.ribbon.RibbonGallery:

==========================================================================================================================================
|phoenix_title|  **wx.ribbon.RibbonGallery**
==========================================================================================================================================

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

It displays a collection of bitmaps arranged in a grid and allows the user to choose one. As there are typically more bitmaps in a gallery than can be displayed in the space used for a ribbon, a gallery always has scroll buttons to allow the user to navigate through the entire gallery. It also has an "extension" button, the behaviour of which is outside the scope of the gallery control itself, though it typically displays some kind of dialog related to the gallery. 

^^ 





.. _RibbonGallery-events:

|events| Events Emitted by this Class
=====================================

Handlers bound for the following event types will receive a :ref:`wx.ribbon.RibbonGalleryEvent` parameter.


- EVT_RIBBONGALLERY_SELECTED: Triggered when the user selects an item from the gallery. Note that the ``ID`` is that of the gallery, not of the item.  
- EVT_RIBBONGALLERY_CLICKED: Similar to ``EVT_RIBBONGALLERY_SELECTED`` but triggered every time a gallery item is clicked, even if it is already selected. Note that the ``ID`` of the event is that of the gallery, not of the item, just as above. This event is available since wxWidgets 2.9.2.  
- EVT_RIBBONGALLERY_HOVER_CHANGED: Triggered when the item being hovered over by the user changes. The item in the event will be the new item being hovered, or ``None`` if there is no longer an item being hovered. Note that the ``ID`` is that of the gallery, not of the item. ^^ ^^ 




The following event handler macros redirect the events to member function handlers '**func**' with prototypes like: :ref:`wx.CommandEvent` 


- EVT_BUTTON: Triggered when the "extension" button of the gallery is pressed. ^^ 








|

|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.ribbon.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.ribbon.RibbonGallery.html" title="A ribbon gallery is like a wx.ListBox, but for bitmaps rather than strings." alt="" coords="19,392,192,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="18,315,193,344"/> <area shape="rect" id="node3" href="wx.Control.html" title="This is the base class for a control or 'widget'." alt="" coords="61,237,149,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="61,160,150,189"/> <area shape="rect" id="node5" href="wx.EvtHandler.html" title="A class that can handle events from the windowing system." alt="" coords="49,83,161,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,88,35"/> <area shape="rect" id="node7" href="wx.Trackable.html" title="Add-on base class for a trackable object." alt="" coords="113,5,215,35"/> </map> 
   </p>
   </div>

|


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

================================================================================ ================================================================================
:meth:`~wx.ribbon.RibbonGallery.__init__`                                        Default constructor.
:meth:`~wx.ribbon.RibbonGallery.Append`                                          Add an item to the gallery (with no client data).
:meth:`~wx.ribbon.RibbonGallery.Clear`                                           Remove all items from the gallery.
:meth:`~wx.ribbon.RibbonGallery.Create`                                          Create a gallery in two-step gallery construction.
:meth:`~wx.ribbon.RibbonGallery.EnsureVisible`                                   Scroll the gallery to ensure that the given item is visible.
:meth:`~wx.ribbon.RibbonGallery.GetActiveItem`                                   Get the currently active item, or ``None`` if there is none.
:meth:`~wx.ribbon.RibbonGallery.GetClassDefaultAttributes`                       
:meth:`~wx.ribbon.RibbonGallery.GetCount`                                        Get the number of items in the gallery.
:meth:`~wx.ribbon.RibbonGallery.GetDownButtonState`                              Get the state of the scroll down button.
:meth:`~wx.ribbon.RibbonGallery.GetExtensionButtonState`                         Get the state of the "extension" button.
:meth:`~wx.ribbon.RibbonGallery.GetHoveredItem`                                  Get the currently hovered item, or ``None`` if there is none.
:meth:`~wx.ribbon.RibbonGallery.GetItem`                                         Get an item by index.
:meth:`~wx.ribbon.RibbonGallery.GetItemClientData`                               Get the client object associated with a gallery item.
:meth:`~wx.ribbon.RibbonGallery.GetSelection`                                    Get the currently selected item, or ``None`` if there is none.
:meth:`~wx.ribbon.RibbonGallery.GetUpButtonState`                                Get the state of the scroll up button.
:meth:`~wx.ribbon.RibbonGallery.IsEmpty`                                         Query if the gallery has no items in it.
:meth:`~wx.ribbon.RibbonGallery.IsHovered`                                       Query is the mouse is currently hovered over the gallery.
:meth:`~wx.ribbon.RibbonGallery.ScrollLines`                                     Scroll the gallery contents by some amount.
:meth:`~wx.ribbon.RibbonGallery.ScrollPixels`                                    Scroll the gallery contents by some fine-grained amount.
:meth:`~wx.ribbon.RibbonGallery.SetItemClientData`                               Set the client object associated with a gallery item.
:meth:`~wx.ribbon.RibbonGallery.SetSelection`                                    Set the selection to the given item, or removes the selection if `item`  == ``None``.
================================================================================ ================================================================================


|


|property_summary| Properties Summary
=====================================

================================================================================ ================================================================================
:attr:`~wx.ribbon.RibbonGallery.ActiveItem`                                      See :meth:`~wx.ribbon.RibbonGallery.GetActiveItem`
:attr:`~wx.ribbon.RibbonGallery.Count`                                           See :meth:`~wx.ribbon.RibbonGallery.GetCount`
:attr:`~wx.ribbon.RibbonGallery.DownButtonState`                                 See :meth:`~wx.ribbon.RibbonGallery.GetDownButtonState`
:attr:`~wx.ribbon.RibbonGallery.ExtensionButtonState`                            See :meth:`~wx.ribbon.RibbonGallery.GetExtensionButtonState`
:attr:`~wx.ribbon.RibbonGallery.HoveredItem`                                     See :meth:`~wx.ribbon.RibbonGallery.GetHoveredItem`
:attr:`~wx.ribbon.RibbonGallery.Selection`                                       See :meth:`~wx.ribbon.RibbonGallery.GetSelection` and :meth:`~wx.ribbon.RibbonGallery.SetSelection`
:attr:`~wx.ribbon.RibbonGallery.UpButtonState`                                   See :meth:`~wx.ribbon.RibbonGallery.GetUpButtonState`
================================================================================ ================================================================================


|


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


.. class:: wx.ribbon.RibbonGallery(RibbonControl)

   **Possible constructors**::

       RibbonGallery()
       
       RibbonGallery(parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize,
                     style=0)
       
   
   A ribbon gallery is like a ListBox, but for bitmaps rather than
   strings.



   .. 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 gallery.                   
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **__init__** `(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0)`
      
      Construct a ribbon gallery with the given parameters.                  
      
      
      
      
      :param `parent`: Parent window for the gallery (typically a :ref:`wx.ribbon.RibbonPanel`).   
      :type `parent`: wx.Window
      :param `id`: An identifier for the gallery.  ``ID_ANY``   is taken to mean a default.    
      :type `id`: wx.WindowID
      :param `pos`: Initial position of the gallery.   
      :type `pos`: wx.Point
      :param `size`: Initial size of the gallery.   
      :type `size`: wx.Size
      :param `style`: Gallery style, currently unused.   
      :type `style`: long
      
      
      
      
      
      
      
      
      
      
      
      
                        
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: Append(self, *args, **kw)



      |overload| Overloaded Implementations:

      :html:`<hr class="overloadsep" /><br />`

      
      **Append** `(self, bitmap, id)`
      
      Add an item to the gallery (with no client data).                  
      
      
      
      
      :param `bitmap`: The bitmap to display for the item. Note that all items must have equally sized bitmaps.   
      :type `bitmap`: wx.Bitmap
      :param `id`: ``ID`` number to associate with the item. Not currently used for anything important.   
      :type `id`: int
      
      
      
      
      
      
      
      
      :rtype: `RibbonGalleryItem`     
      
      
      
                        
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`

      
      **Append** `(self, bitmap, id, clientData)`
      
      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.   
      :type `bitmap`: wx.Bitmap
      :param `id`: ``ID`` number to associate with the item. Not currently used for anything important.   
      :type `id`: int
      :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.   
      :type `clientData`: ClientData
      
      
      
      
      
      
      
      
      
      
      :rtype: `RibbonGalleryItem`     
      
      
      
                        
      
      
      
      
      :html:`<hr class="overloadsep" /><br />`






   .. method:: Clear(self)

      Remove all items from the gallery.                   





   .. method:: Create(self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0)

      Create a gallery in two-step gallery 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:: EnsureVisible(self, item)

      Scroll the gallery to ensure that the given item is visible.                  


      :param `item`: 
      :type `item`: 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.                  

      :rtype: `RibbonGalleryItem`     








   .. staticmethod:: GetClassDefaultAttributes(variant=WINDOW_VARIANT_NORMAL)




      :param `variant`: 
      :type `variant`: wx.WindowVariant




      :rtype: `VisualAttributes`     








   .. method:: GetCount(self)

      Get the number of items in the gallery.                  

      :rtype: `int`








   .. method:: GetDownButtonState(self)

      Get the state of the scroll down button.                  

      :rtype: :ref:`wx.ribbon.RibbonGalleryButtonState`








   .. method:: GetExtensionButtonState(self)

      Get the state of the "extension" button.                  

      :rtype: :ref:`wx.ribbon.RibbonGalleryButtonState`








   .. method:: GetHoveredItem(self)

      Get the currently hovered item, or ``None`` if there is none.                  

      The hovered item is the item underneath the mouse cursor.                  

      :rtype: `RibbonGalleryItem`     








   .. method:: GetItem(self, n)

      Get an item by index.                  


      :param `n`: 
      :type `n`: int




      :rtype: `RibbonGalleryItem`     








   .. method:: GetItemClientData(self, item)

      Get the client object associated with a gallery item.                  


      :param `item`: 
      :type `item`: RibbonGalleryItem




      :rtype: `ClientData`     








   .. method:: GetSelection(self)

      Get the currently selected item, or ``None`` if there is none.                  

      The selected item is set by :meth:`SetSelection` , or by the user clicking on an item.                  

      :rtype: `RibbonGalleryItem`     








   .. method:: GetUpButtonState(self)

      Get the state of the scroll up button.                  

      :rtype: :ref:`wx.ribbon.RibbonGalleryButtonState`








   .. method:: IsEmpty(self)

      Query if the gallery has no items in it.                  

      :rtype: `bool`








   .. method:: IsHovered(self)

      Query is the mouse is currently hovered over the gallery.                  

                

      :rtype: `bool`







      :returns: 

         ``True`` if the cursor is within the bounds of the gallery (not just hovering over an item), ``False`` otherwise.   








   .. 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.  
      :type `lines`: int






      :rtype: `bool`



                  



      :returns: 

         ``True`` if the gallery scrolled at least one pixel in the given direction, ``False`` if it did not scroll.   








   .. method:: ScrollPixels(self, pixels)

      Scroll the gallery contents by some fine-grained amount.                  




      :param `pixels`: Positive values scroll toward the end of the gallery, while negative values scroll toward the start.  
      :type `pixels`: int






      :rtype: `bool`



                  



      :returns: 

         ``True`` if the gallery scrolled at least one pixel in the given direction, ``False`` if it did not scroll.   








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

      Set the client object associated with a gallery item.                  


      :param `item`: 
      :type `item`: RibbonGalleryItem
      :param `data`: 
      :type `data`: ClientData







   .. 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`: 
      :type `item`: RibbonGalleryItem







   .. attribute:: ActiveItem

      See :meth:`~wx.ribbon.RibbonGallery.GetActiveItem`


   .. attribute:: Count

      See :meth:`~wx.ribbon.RibbonGallery.GetCount`


   .. attribute:: DownButtonState

      See :meth:`~wx.ribbon.RibbonGallery.GetDownButtonState`


   .. attribute:: ExtensionButtonState

      See :meth:`~wx.ribbon.RibbonGallery.GetExtensionButtonState`


   .. attribute:: HoveredItem

      See :meth:`~wx.ribbon.RibbonGallery.GetHoveredItem`


   .. attribute:: Selection

      See :meth:`~wx.ribbon.RibbonGallery.GetSelection` and :meth:`~wx.ribbon.RibbonGallery.SetSelection`


   .. attribute:: UpButtonState

      See :meth:`~wx.ribbon.RibbonGallery.GetUpButtonState`