phoenix_title wx.lib.agw.ribbon.bar.RibbonBar

Top-level control in a ribbon user interface.


class_hierarchy Class Hierarchy

Inheritance diagram of RibbonBar


appearance Control Appearance


wxMSW

wxMSW

wxGTK

wxGTK

wxMAC

wxMAC


super_classes Known Superclasses

wx.lib.agw.ribbon.control.RibbonControl


method_summary Methods Summary

__init__

Default constructor.

AddPage

Adds a page to the RibbonBar.

CommonInit

Common initialization procedures.

DismissExpandedPanel

Dismiss the expanded panel of the currently active page.

DoEraseBackground

Does the initial painting of stuff from the OnPaint event.

DoGetBestSize

Gets the size which best suits the window: for a control, it would be the

DoMouseButtonCommon

Common methods for all the mouse move/click events.

GetActivePage

Get the index of the active page.

GetAGWWindowStyleFlag

Returns the RibbonBar window style flag.

GetDefaultBorder

Returns the default border style for RibbonBar.

GetPage

Get a page by index.

HasMultiplePages

This method should be overridden to return true if this window has multiple pages.

HitTestTabs

Hit test method for RibbonBar, testing where the given (in client coordinates)

OnEraseBackground

Handles the wx.EVT_ERASE_BACKGROUND event for RibbonBar.

OnMouseDoubleClick

Handles the wx.EVT_LEFT_DCLICK event for RibbonBar.

OnMouseLeave

Handles the wx.EVT_LEAVE_WINDOW event for RibbonBar.

OnMouseLeftDown

Handles the wx.EVT_LEFT_DOWN event for RibbonBar.

OnMouseLeftUp

Handles the wx.EVT_LEFT_UP event for RibbonBar.

OnMouseMiddleDown

Handles the wx.EVT_MIDDLE_DOWN event for RibbonBar.

OnMouseMiddleUp

Handles the wx.EVT_MIDDLE_UP event for RibbonBar.

OnMouseMove

Handles the wx.EVT_MOTION event for RibbonBar.

OnMouseRightDown

Handles the wx.EVT_RIGHT_DOWN event for RibbonBar.

OnMouseRightUp

Handles the wx.EVT_RIGHT_UP event for RibbonBar.

OnPaint

Handles the wx.EVT_PAINT event for RibbonBar.

OnSize

Handles the wx.EVT_SIZE event for RibbonBar.

OrderPageTabInfoBySmallWidthAsc

Realize

Perform initial layout and size calculations of the bar and its children.

RecalculateMinSize

Recalculates the RibbonBar minimum size.

RecalculateTabSizes

Recalculates the RibbonBar tab sizes.

RefreshTabBar

Repaints the tab area in RibbonBar.

RepositionPage

ScrollTabBar

Scrolls the tab area left/right/up/down by the specified amount.

SetActivePage

See comments on SetActivePageByIndex and SetActivePageByPage.

SetActivePageByIndex

Set the active page by index, without triggering any events.

SetActivePageByPage

Set the active page, without triggering any events.

SetAGWWindowStyleFlag

Sets the window style for RibbonBar.

SetArtProvider

Set the art provider to be used be the ribbon bar.

SetTabCtrlMargins

Set the margin widths (in pixels) on the left and right sides of the tab bar

ShowPanels

Shows or hides the panels inside RibbonBar.

api Class API

class RibbonBar(RibbonControl)

Top-level control in a ribbon user interface.


Methods

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, agwStyle=RIBBON_BAR_DEFAULT_STYLE, validator=wx.DefaultValidator, name='RibbonBar')

Default constructor.

Parameters:

  • parent (wx.Window) – pointer to a parent window, must not be None;

  • 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 –

    the AGW-specific window style. This can be a combination of the following bits:

    Window Styles

    Hex Value

    Description

    RIBBON_BAR_DEFAULT_STYLE

    0x9

    Defined as RIBBON_BAR_FLOW_HORIZONTAL | RIBBON_BAR_SHOW_PAGE_LABELS | RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS

    RIBBON_BAR_FOLDBAR_STYLE

    0x1e

    Defined as RIBBON_BAR_FLOW_VERTICAL | RIBBON_BAR_SHOW_PAGE_ICONS | RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS | RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS

    RIBBON_BAR_SHOW_PAGE_LABELS

    0x1

    Causes labels to be shown on the tabs in the ribbon bar.

    RIBBON_BAR_SHOW_PAGE_ICONS

    0x2

    Causes icons to be shown on the tabs in the ribbon bar.

    RIBBON_BAR_FLOW_HORIZONTAL

    0x0

    Causes panels within pages to stack horizontally.

    RIBBON_BAR_FLOW_VERTICAL

    0x4

    Causes panels within pages to stack vertically.

    RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS

    0x8

    Causes extension buttons to be shown on panels (where the panel has such a button).

    RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS

    0x10

    Causes minimise buttons to be shown on panels (where the panel has such a button).

    RIBBON_BAR_ALWAYS_SHOW_TABS

    0x20

    Always shows the tabs area even when only one tab is added.

  • validator (wx.Validator) – the window validator;

  • name (string) – the window name.


AddPage(self, page)

Adds a page to the RibbonBar.

Parameters:

page – an instance of RibbonPage.


CommonInit(self, agwStyle)

Common initialization procedures.

Parameters:

agwStyle (integer) – the AGW-specific window style.

See also

SetAGWWindowStyleFlag for a list of valid window styles.


DismissExpandedPanel(self)

Dismiss the expanded panel of the currently active page.

Calls and returns the value from RibbonPage.DismissExpandedPanel() for the currently active page, or False if there is no active page.


DoEraseBackground(self, dc)

Does the initial painting of stuff from the OnPaint event.

Parameters:

dc – an instance of wx.DC.


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.


DoMouseButtonCommon(self, event, tab_event_type)

Common methods for all the mouse move/click events.

Parameters:

  • event – a MouseEvent event to be processed;

  • tab_event_type (integer) – one of the RibbonBar events.


GetActivePage(self)

Get the index of the active page.

In the rare case of no page being active, -1 is returned.


GetAGWWindowStyleFlag(self)

Returns the RibbonBar window style flag.

See also

SetAGWWindowStyleFlag for a list of valid window styles.


GetDefaultBorder(self)

Returns the default border style for RibbonBar.


GetPage(self, n)

Get a page by index.

None will be returned if the given index is out of range.

Parameters:

n (integer) – the zero-based index indicating the page position.


HasMultiplePages(self)

This method should be overridden to return true if this window has multiple pages.

All standard class with multiple pages such as Notebook, Listbook and Treebook already override it to return true and user-defined classes with similar behaviour should also do so, to allow the library to handle such windows appropriately.


HitTestTabs(self, position)

Hit test method for RibbonBar, testing where the given (in client coordinates) point lies.

Parameters:

position – an instance of wx.Point in client coordinates.

Returns:

a tuple containing the tab index and the RibbonPage if the HitTestTabs successfully found such combination, or a tuple (-1, None) if no tab has been hit.


OnEraseBackground(self, event)

Handles the wx.EVT_ERASE_BACKGROUND event for RibbonBar.

Parameters:

event – a EraseEvent event to be processed.


OnMouseDoubleClick(self, event)

Handles the wx.EVT_LEFT_DCLICK event for RibbonBar.

Parameters:

event – a MouseEvent event to be processed.


OnMouseLeave(self, event)

Handles the wx.EVT_LEAVE_WINDOW event for RibbonBar.

Parameters:

event – a MouseEvent event to be processed.


OnMouseLeftDown(self, event)

Handles the wx.EVT_LEFT_DOWN event for RibbonBar.

Parameters:

event – a MouseEvent event to be processed.


OnMouseLeftUp(self, event)

Handles the wx.EVT_LEFT_UP event for RibbonBar.

Parameters:

event – a MouseEvent event to be processed.


OnMouseMiddleDown(self, event)

Handles the wx.EVT_MIDDLE_DOWN event for RibbonBar.

Parameters:

event – a MouseEvent event to be processed.


OnMouseMiddleUp(self, event)

Handles the wx.EVT_MIDDLE_UP event for RibbonBar.

Parameters:

event – a MouseEvent event to be processed.


OnMouseMove(self, event)

Handles the wx.EVT_MOTION event for RibbonBar.

Parameters:

event – a MouseEvent event to be processed.


OnMouseRightDown(self, event)

Handles the wx.EVT_RIGHT_DOWN event for RibbonBar.

Parameters:

event – a MouseEvent event to be processed.


OnMouseRightUp(self, event)

Handles the wx.EVT_RIGHT_UP event for RibbonBar.

Parameters:

event – a MouseEvent event to be processed.


OnPaint(self, event)

Handles the wx.EVT_PAINT event for RibbonBar.

Parameters:

event – a PaintEvent event to be processed.


OnSize(self, event)

Handles the wx.EVT_SIZE event for RibbonBar.

Parameters:

event – a wx.SizeEvent event to be processed.


OrderPageTabInfoBySmallWidthAsc(self, first, second)

Realize(self)

Perform initial layout and size calculations of the bar and its children.

This must be called after all of the bar’s children have been created (and their children created, etc.) - if it is not, then windows may not be laid out or sized correctly. Also calls RibbonPage.Realize() on each child page.

Note

Reimplemented from RibbonControl.


RecalculateMinSize(self)

Recalculates the RibbonBar minimum size.


RecalculateTabSizes(self)

Recalculates the RibbonBar tab sizes.


RefreshTabBar(self)

Repaints the tab area in RibbonBar.


RepositionPage(self, page)

ScrollTabBar(self, amount)

Scrolls the tab area left/right/up/down by the specified amount.

Parameters:

amount (integer) – the amount by which the tab area is scrolled, in pixels.


SetActivePage(self, page)

See comments on SetActivePageByIndex and SetActivePageByPage.


SetActivePageByIndex(self, page)

Set the active page by index, without triggering any events.

Parameters:

page (integer) – The zero-based index of the page to activate.

Returns:

True if the specified page is now active, False if it could not be activated (for example because the page index is invalid).


SetActivePageByPage(self, page)

Set the active page, without triggering any events.

Parameters:

page – the page to activate, an instance of RibbonPage.

Returns:

True if the specified page is now active, False if it could not be activated (for example because the given page is not a child of the ribbon bar).


SetAGWWindowStyleFlag(self, agwStyle)

Sets the window style for RibbonBar.

Parameters:

agwStyle (integer) – can be a combination of the following bits:

Window Styles

Hex Value

Description

RIBBON_BAR_DEFAULT_STYLE

0x9

Defined as RIBBON_BAR_FLOW_HORIZONTAL | RIBBON_BAR_SHOW_PAGE_LABELS | RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS

RIBBON_BAR_FOLDBAR_STYLE

0x1e

Defined as RIBBON_BAR_FLOW_VERTICAL | RIBBON_BAR_SHOW_PAGE_ICONS | RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS | RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS

RIBBON_BAR_SHOW_PAGE_LABELS

0x1

Causes labels to be shown on the tabs in the ribbon bar.

RIBBON_BAR_SHOW_PAGE_ICONS

0x2

Causes icons to be shown on the tabs in the ribbon bar.

RIBBON_BAR_FLOW_HORIZONTAL

0x0

Causes panels within pages to stack horizontally.

RIBBON_BAR_FLOW_VERTICAL

0x4

Causes panels within pages to stack vertically.

RIBBON_BAR_SHOW_PANEL_EXT_BUTTONS

0x8

Causes extension buttons to be shown on panels (where the panel has such a button).

RIBBON_BAR_SHOW_PANEL_MINIMISE_BUTTONS

0x10

Causes minimise buttons to be shown on panels (where the panel has such a button).

RIBBON_BAR_ALWAYS_SHOW_TABS

0x20

Always shows the tabs area even when only one tab is added.

Note

Please note that some styles cannot be changed after the window creation and that Refresh() might need to be be called after changing the others for the change to take place immediately.


SetArtProvider(self, art)

Set the art provider to be used be the ribbon bar.

Also sets the art provider on all current RibbonPage children, and any RibbonPage children added in the future.

Note that unlike most other ribbon controls, the ribbon bar creates a default art provider when initialised, so an explicit call to SetArtProvider is not required if the default art provider is sufficient. Also unlike other ribbon controls, the ribbon bar takes ownership of the given pointer, and will delete it when the art provider is changed or the bar is destroyed.

If this behaviour is not desired, then clone the art provider before setting it.

Parameters:

art – an art provider.

Note

Reimplemented from RibbonControl.


SetTabCtrlMargins(self, left, right)

Set the margin widths (in pixels) on the left and right sides of the tab bar region of the ribbon bar.

These margins will be painted with the tab background, but tabs and scroll buttons will never be painted in the margins. The left margin could be used for rendering something equivalent to the “Office Button”, though this is not currently implemented. The right margin could be used for rendering a help button, and/or MDI buttons, but again, this is not currently implemented.

Parameters:

  • left (integer) – the left margin (in pixels);

  • right (integer) – the right margin (in pixels).


ShowPanels(self, show=True)

Shows or hides the panels inside RibbonBar.

Parameters:

show (bool) – True to show the panels, False to hide them.