Phoenix Logo

phoenix_title wx.ribbon.RibbonGallery

A ribbon gallery is like a 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.

events Events Emitted by this Class

Handlers bound for the following event types will receive a 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: wx.CommandEvent

  • EVT_BUTTON: Triggered when the “extension” button of the gallery is pressed.

class_hierarchy Class Hierarchy

Inheritance diagram for class RibbonGallery:


method_summary Methods Summary

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

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.


Methods



__init__(self, *args, **kw)

overload Overloaded Implementations:



__init__ (self)

Default constructor.

With this constructor, Create should be called in order to create the gallery.



__init__ (self, parent, id=ID_ANY, pos=DefaultPosition, size=DefaultSize, style=0)

Construct a ribbon gallery with the given parameters.

Parameters:
  • parent (wx.Window) – Parent window for the gallery (typically a wx.ribbon.RibbonPanel).
  • id (wx.WindowID) – An identifier for the gallery. ID_ANY is taken to mean a default.
  • pos (wx.Point) – Initial position of the gallery.
  • size (wx.Size) – Initial size of the gallery.
  • style (long) – Gallery style, currently unused.





Append(self, *args, **kw)

overload Overloaded Implementations:



Append (self, bitmap, id)

Add an item to the gallery (with no client data).

Parameters:
  • bitmap (wx.Bitmap) – The bitmap to display for the item. Note that all items must have equally sized bitmaps.
  • id (int) – ID number to associate with the item. Not currently used for anything important.
Return type:

RibbonGalleryItem



Append (self, bitmap, id, clientData)

Add an item to the gallery (with complex client data)

Parameters:
  • bitmap (wx.Bitmap) – The bitmap to display for the item. Note that all items must have equally sized bitmaps.
  • id (int) – ID number to associate with the item. Not currently used for anything important.
  • clientData (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.
Return type:

RibbonGalleryItem





Clear(self)

Remove all items from the gallery.



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.

Parameters:
Return type:

bool



EnsureVisible(self, item)

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

Parameters:item (RibbonGalleryItem) –


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.

Return type:RibbonGalleryItem


GetCount(self)

Get the number of items in the gallery.

Return type:int


GetDownButtonState(self)

Get the state of the scroll down button.

Return type: wx.ribbon.RibbonGalleryButtonState


GetExtensionButtonState(self)

Get the state of the “extension” button.

Return type: wx.ribbon.RibbonGalleryButtonState


GetHoveredItem(self)

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

The hovered item is the item underneath the mouse cursor.

Return type:RibbonGalleryItem


GetItem(self, n)

Get an item by index.

Parameters:n (int) –
Return type:RibbonGalleryItem


GetItemClientData(self, item)

Get the client object associated with a gallery item.

Parameters:item (RibbonGalleryItem) –
Return type:ClientData


GetSelection(self)

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

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

Return type:RibbonGalleryItem


GetUpButtonState(self)

Get the state of the scroll up button.

Return type: wx.ribbon.RibbonGalleryButtonState


IsEmpty(self)

Query if the gallery has no items in it.

Return type:bool


IsHovered(self)

Query is the mouse is currently hovered over the gallery.

Return type:bool
Returns:True if the cursor is within the bounds of the gallery (not just hovering over an item), False otherwise.


ScrollLines(self, lines)

Scroll the gallery contents by some amount.

Parameters:lines (int) – Positive values scroll toward the end of the gallery, while negative values scroll toward the start.
Return type:bool
Returns:True if the gallery scrolled at least one pixel in the given direction, False if it did not scroll.


ScrollPixels(self, pixels)

Scroll the gallery contents by some fine-grained amount.

Parameters:pixels (int) – Positive values scroll toward the end of the gallery, while negative values scroll toward the start.
Return type:bool
Returns:True if the gallery scrolled at least one pixel in the given direction, False if it did not scroll.


SetItemClientData(self, item, data)

Set the client object associated with a gallery item.

Parameters:


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.

Parameters:item (RibbonGalleryItem) –

Properties



ActiveItem

See GetActiveItem



Count

See GetCount



DownButtonState

See GetDownButtonState



ExtensionButtonState

See GetExtensionButtonState



HoveredItem

See GetHoveredItem



Selection

See GetSelection and SetSelection



UpButtonState

See GetUpButtonState