phoenix_title wx.lib.agw.ribbon.toolbar.RibbonToolBar

Base class for all the Ribbon stuff.


class_hierarchy Class Hierarchy

Inheritance diagram for class RibbonToolBar:

appearance Control Appearance


wxMSW

wxMSW

wxMAC

wxMAC

wxGTK

wxGTK


super_classes Known Superclasses

wx.lib.agw.ribbon.control.RibbonControl


method_summary Methods Summary

__init__

Default class constructor.

AddDropdownTool

Add a dropdown tool to the tool bar (simple version).

AddHybridTool

Add a hybrid tool to the tool bar (simple version).

AddSeparator

Adds a separator to the tool bar.

AddSimpleTool

Add a tool to the tool bar (simple version).

AddToggleTool

Add a toggle tool to the tool bar (simple version).

AddTool

Add a tool to the tool bar.

AppendGroup

ClearTools

Deletes all the tools in the toolbar.

CommonInit

DeleteTool

Removes the specified tool from the toolbar and deletes it.

DeleteToolByPos

This function behaves like DeleteTool but it deletes the tool at the

DoGetBestSize

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

DoGetNextLargerSize

Implementation of RibbonControl.GetNextLargerSize().

DoGetNextSmallerSize

Implementation of RibbonControl.GetNextSmallerSize().

EnableTool

Enables or disables a single tool on the bar.

FindById

Returns a pointer to the tool opaque structure by tool_id or None if

GetBestSizeForParentSize

Finds the best width and height given the parent’s width and height.

GetDefaultBorder

Returns the default border style for RibbonToolBar.

GetToolByPos

Returns a pointer to the tool opaque structure by pos or None if

GetToolClientData

Get any client data associated with the tool.

GetToolCount

Returns the number of tools in this RibbonToolBar.

GetToolEnabled

Called to determine whether a tool is enabled (responds to user input).

GetToolHelpString

Returns the tool short help string.

GetToolId

Returns the tool id for the specified input tool.

GetToolKind

Returns the kind of the given tool.

GetToolPos

Returns the tool position in the toolbar, or wx.NOT_FOUND if the tool is not found.

GetToolState

Gets the on/off state of a toggle tool.

InsertDropdownTool

Inserts a dropdown tool in the tool bar at the position specified by pos.

InsertGroup

InsertHybridTool

Inserts a hybrid tool in the tool bar at the position specified by pos.

InsertSeparator

Inserts a separator into the tool bar at the position specified by pos.

InsertToggleTool

Inserts a toggle tool in the tool bar at the position specified by pos.

InsertTool

Inserts a tool in the tool bar at the position specified by pos.

IsSizingContinuous

Returns True if this window can take any size (greater than its minimum size),

MakeDisabledBitmap

OnEraseBackground

Handles the wx.EVT_ERASE_BACKGROUND event for RibbonToolBar.

OnMouseDown

Handles the wx.EVT_LEFT_DOWN event for RibbonToolBar.

OnMouseEnter

Handles the wx.EVT_ENTER_WINDOW event for RibbonToolBar.

OnMouseLeave

Handles the wx.EVT_LEAVE_WINDOW event for RibbonToolBar.

OnMouseMove

Handles the wx.EVT_MOTION event for RibbonToolBar.

OnMouseUp

Handles the wx.EVT_LEFT_UP event for RibbonToolBar.

OnPaint

Handles the wx.EVT_PAINT event for RibbonToolBar.

OnSize

Handles the wx.EVT_SIZE event for RibbonToolBar.

Realize

Calculates tool layouts and positions.

SetRows

Set the number of rows to distribute tool groups over.

SetToolClientData

Sets the client data associated with the tool.

SetToolDisabledBitmap

Sets the bitmap to be used by the tool with the given ID when the tool is in a disabled state.

SetToolHelpString

Sets the tool short help string.

SetToolNormalBitmap

Sets the bitmap to be used by the tool with the given ID when the tool is enabled.

ToggleTool

Toggles on or off a single tool on the bar.

UpdateWindowUI

This function sends one or more UpdateUIEvent to the window.


api Class API

class RibbonToolBar(RibbonControl)

Base class for all the Ribbon stuff.


Methods

__init__(self, parent, id=wx.ID_ANY, pos=wx.DefaultPosition, size=wx.DefaultSize, style=0, name="RibbonToolBar")

Default class constructor.

Parameters:
  • parent – pointer to a parent window, typically a RibbonPanel;

  • id – window identifier. If wx.ID_ANY, will automatically create an identifier;

  • pos – window position. wx.DefaultPosition indicates that wxPython should generate a default position for the window;

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

  • style – window style, currently unused.

  • name – the window name.



AddDropdownTool(self, tool_id, bitmap, help_string="")

Add a dropdown tool to the tool bar (simple version).

Parameters:
  • tool_id – id of the new tool (used for event callbacks);

  • bitmap – large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar;

  • help_string – the UI help string to associate with the new button.

See also

AddTool



AddHybridTool(self, tool_id, bitmap, help_string="")

Add a hybrid tool to the tool bar (simple version).

Parameters:
  • tool_id – id of the new tool (used for event callbacks);

  • bitmap – large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar;

  • help_string – the UI help string to associate with the new button.

See also

AddTool



AddSeparator(self)

Adds a separator to the tool bar.

Separators are used to separate tools into groups. As such, a separator is not explicitly drawn, but is visually seen as the gap between tool groups.



AddSimpleTool(self, tool_id, bitmap, help_string, kind=RIBBON_BUTTON_NORMAL)

Add a tool to the tool bar (simple version).

Parameters:
  • tool_id – id of the new tool (used for event callbacks);

  • bitmap – large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar;

  • help_string – the UI help string to associate with the new button;

  • kind – the kind of button to add.



AddToggleTool(self, tool_id, bitmap, help_string="")

Add a toggle tool to the tool bar (simple version).

Parameters:
  • tool_id – id of the new tool (used for event callbacks);

  • bitmap – large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar;

  • help_string – the UI help string to associate with the new button.

See also

AddTool



AddTool(self, tool_id, bitmap, bitmap_disabled=wx.NullBitmap, help_string="", kind=RIBBON_BUTTON_NORMAL, client_data=None)

Add a tool to the tool bar.

Parameters:
  • tool_id – id of the new tool (used for event callbacks);

  • bitmap – bitmap to use as the foreground for the new tool. Does not have to be the same size as other tool bitmaps, but should be similar as otherwise it will look visually odd;

  • bitmap_disabled – bitmap to use when the tool is disabled. If left as NullBitmap, then a bitmap will be automatically generated from bitmap;

  • help_string – the UI help string to associate with the new tool;

  • kind – the kind of tool to add;

  • client_data – client data to associate with the new tool.

Returns:

An opaque pointer which can be used only with other tool bar methods.



AppendGroup(self)


ClearTools(self)

Deletes all the tools in the toolbar.

New in version 0.9.5.



CommonInit(self, style)


DeleteTool(self, tool_id)

Removes the specified tool from the toolbar and deletes it.

Parameters:

tool_id – id of the tool to delete.

Returns:

True if the tool was deleted, False otherwise.

See also

DeleteToolByPos

New in version 0.9.5.



DeleteToolByPos(self, pos)

This function behaves like DeleteTool but it deletes the tool at the specified position pos and not the one with the given id.

Useful to delete separators.

Parameters:

pos – zero-based position of the tool to delete.

Returns:

True if the tool was deleted, False otherwise.

See also

DeleteTool

New in version 0.9.5.



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.



DoGetNextLargerSize(self, direction, relative_to)

Implementation of RibbonControl.GetNextLargerSize().

Controls which have non-continuous sizing must override this virtual function rather than RibbonControl.GetNextLargerSize().



DoGetNextSmallerSize(self, direction, relative_to)

Implementation of RibbonControl.GetNextSmallerSize().

Controls which have non-continuous sizing must override this virtual function rather than RibbonControl.GetNextSmallerSize().



EnableTool(self, tool_id, enable=True)

Enables or disables a single tool on the bar.

Parameters:
  • tool_id – id of the tool in question, as passed to AddTool;

  • enableTrue to enable the tool, False to disable it.

New in version 0.9.5.



FindById(self, tool_id)

Returns a pointer to the tool opaque structure by tool_id or None if no corresponding tool is found.

Parameters:

tool_id – id of the tool to find.

New in version 0.9.5.



GetBestSizeForParentSize(self, parentSize)

Finds the best width and height given the parent’s width and height.



GetDefaultBorder(self)

Returns the default border style for RibbonToolBar.



GetToolByPos(self, pos)

Returns a pointer to the tool opaque structure by pos or None if no corresponding tool is found.

Parameters:

pos – zero-based position of the tool to retrieve.

Returns:

An instance of RibbonToolBarToolBase if the tool was found, None if it was not found.

New in version 0.9.5.



GetToolClientData(self, tool_id)

Get any client data associated with the tool.

Parameters:

tool_id – id of the tool in question, as passed to AddTool.

Returns:

Client data (any Python object), or None if there is none.

New in version 0.9.5.



GetToolCount(self)

Returns the number of tools in this RibbonToolBar.

New in version 0.9.5.



GetToolEnabled(self, tool_id)

Called to determine whether a tool is enabled (responds to user input).

Parameters:

tool_id – id of the tool in question, as passed to AddTool.

Returns:

True if the tool was found and it is enabled, False otherwise.

New in version 0.9.5.



GetToolHelpString(self, tool_id)

Returns the tool short help string.

Parameters:

tool_id – id of the tool in question, as passed to AddTool.

New in version 0.9.5.



GetToolId(self, tool)

Returns the tool id for the specified input tool.

Parameters:

tool – an instance of RibbonToolBarToolBase.

New in version 0.9.5.



GetToolKind(self, tool_id)

Returns the kind of the given tool.

Parameters:

tool_id – id of the tool in question, as passed to AddTool.

New in version 0.9.5.



GetToolPos(self, tool_id)

Returns the tool position in the toolbar, or wx.NOT_FOUND if the tool is not found.

Parameters:

tool_id – id of the tool in question, as passed to AddTool.

New in version 0.9.5.



GetToolState(self, tool_id)

Gets the on/off state of a toggle tool.

Parameters:

tool_id – id of the tool in question, as passed to AddTool.

Returns:

True if the tool is toggled on, False otherwise.

See also

ToggleTool

New in version 0.9.5.



InsertDropdownTool(self, pos, tool_id, bitmap, help_string="")

Inserts a dropdown tool in the tool bar at the position specified by pos.

Parameters:
  • pos – the position of the new tool in the toolbar (zero-based);

  • tool_id – id of the new tool (used for event callbacks);

  • bitmap – large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar;

  • help_string – the UI help string to associate with the new button.

See also

AddTool, InsertTool

New in version 0.9.5.



InsertGroup(self, pos)


InsertHybridTool(self, pos, tool_id, bitmap, help_string="")

Inserts a hybrid tool in the tool bar at the position specified by pos.

Parameters:
  • pos – the position of the new tool in the toolbar (zero-based);

  • tool_id – id of the new tool (used for event callbacks);

  • bitmap – large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar;

  • help_string – the UI help string to associate with the new button.

See also

AddTool, InsertTool

New in version 0.9.5.



InsertSeparator(self, pos)

Inserts a separator into the tool bar at the position specified by pos.

Separators are used to separate tools into groups. As such, a separator is not explicitly drawn, but is visually seen as the gap between tool groups.

Parameters:

pos – the position of the new tool in the toolbar (zero-based).

New in version 0.9.5.



InsertToggleTool(self, pos, tool_id, bitmap, help_string="")

Inserts a toggle tool in the tool bar at the position specified by pos.

Parameters:
  • pos – the position of the new tool in the toolbar (zero-based);

  • tool_id – id of the new tool (used for event callbacks);

  • bitmap – large bitmap of the new button. Must be the same size as all other large bitmaps used on the button bar;

  • help_string – the UI help string to associate with the new button.

See also

AddTool, InsertTool

New in version 0.9.5.



InsertTool(self, pos, tool_id, bitmap, bitmap_disabled=wx.NullBitmap, help_string="", kind=RIBBON_BUTTON_NORMAL, client_data=None)

Inserts a tool in the tool bar at the position specified by pos.

Parameters:
  • pos – the position of the new tool in the toolbar (zero-based);

  • tool_id – id of the new tool (used for event callbacks);

  • bitmap – bitmap to use as the foreground for the new tool. Does not have to be the same size as other tool bitmaps, but should be similar as otherwise it will look visually odd;

  • bitmap_disabled – bitmap to use when the tool is disabled. If left as NullBitmap, then a bitmap will be automatically generated from bitmap;

  • help_string – the UI help string to associate with the new tool;

  • kind – the kind of tool to add;

  • client_data – client data to associate with the new tool.

Returns:

An opaque pointer which can be used only with other tool bar methods.

See also

AddTool, AddDropdownTool, AddHybridTool, AddSeparator

New in version 0.9.5.



IsSizingContinuous(self)

Returns True if this window can take any size (greater than its minimum size), False if it can only take certain sizes.

See also

RibbonControl.GetNextSmallerSize(), RibbonControl.GetNextLargerSize()



MakeDisabledBitmap(self, original)


OnEraseBackground(self, event)

Handles the wx.EVT_ERASE_BACKGROUND event for RibbonToolBar.

Parameters:

event – a EraseEvent event to be processed.



OnMouseDown(self, event)

Handles the wx.EVT_LEFT_DOWN event for RibbonToolBar.

Parameters:

event – a MouseEvent event to be processed.



OnMouseEnter(self, event)

Handles the wx.EVT_ENTER_WINDOW event for RibbonToolBar.

Parameters:

event – a MouseEvent event to be processed.



OnMouseLeave(self, event)

Handles the wx.EVT_LEAVE_WINDOW event for RibbonToolBar.

Parameters:

event – a MouseEvent event to be processed.



OnMouseMove(self, event)

Handles the wx.EVT_MOTION event for RibbonToolBar.

Parameters:

event – a MouseEvent event to be processed.



OnMouseUp(self, event)

Handles the wx.EVT_LEFT_UP event for RibbonToolBar.

Parameters:

event – a MouseEvent event to be processed.



OnPaint(self, event)

Handles the wx.EVT_PAINT event for RibbonToolBar.

Parameters:

event – a PaintEvent event to be processed.



OnSize(self, event)

Handles the wx.EVT_SIZE event for RibbonToolBar.

Parameters:

event – a wx.SizeEvent event to be processed.



Realize(self)

Calculates tool layouts and positions.

Must be called after tools are added to the tool bar, as otherwise the newly added tools will not be displayed.

Note

Reimplemented from RibbonControl.



SetRows(self, nMin, nMax)

Set the number of rows to distribute tool groups over.

Tool groups can be distributed over a variable number of rows. The way in which groups are assigned to rows is not specified, and the order of groups may change, but they will be distributed in such a way as to minimise the overall size of the tool bar.

Parameters:
  • nMin – the minimum number of rows to use;

  • nMax – the maximum number of rows to use (defaults to nMin).



SetToolClientData(self, tool_id, clientData)

Sets the client data associated with the tool.

Parameters:
  • tool_id – id of the tool in question, as passed to AddTool;

  • clientData – any Python object.

New in version 0.9.5.



SetToolDisabledBitmap(self, tool_id, bitmap)

Sets the bitmap to be used by the tool with the given ID when the tool is in a disabled state.

Parameters:
  • tool_id – id of the tool in question, as passed to AddTool;

  • bitmap – an instance of wx.Bitmap.

New in version 0.9.5.



SetToolHelpString(self, tool_id, helpString)

Sets the tool short help string.

Parameters:
  • tool_id – id of the tool in question, as passed to AddTool;

  • helpString – a string for the help.

New in version 0.9.5.



SetToolNormalBitmap(self, tool_id, bitmap)

Sets the bitmap to be used by the tool with the given ID when the tool is enabled.

Parameters:
  • tool_id – id of the tool in question, as passed to AddTool;

  • bitmap – an instance of wx.Bitmap.

New in version 0.9.5.



ToggleTool(self, tool_id, checked=True)

Toggles on or off a single tool on the bar.

Parameters:
  • tool_id – id of the tool in question, as passed to AddTool;

  • checkedTrue to toggle on the tool, False to toggle it off.

New in version 0.9.5.



UpdateWindowUI(self, flags)

This function sends one or more UpdateUIEvent to the window.

The particular implementation depends on the window; for example a ToolBar will send an update UI event for each toolbar button, and a wx.Frame will send an update UI event for each menubar menu item.

You can call this function from your application to ensure that your UI is up-to-date at this point (as far as your UpdateUIEvent handlers are concerned). This may be necessary if you have called UpdateUIEvent.SetMode or UpdateUIEvent.SetUpdateInterval to limit the overhead that wxWidgets incurs by sending update UI events in idle time.

Parameters:

flags (integer) – should be a bitlist of one or more of wx.UPDATE_UI_NONE, wx.UPDATE_UI_RECURSE or wx.UPDATE_UI_FROMIDLE.

If you are calling this function from an OnInternalIdle or OnIdle function, make sure you pass the wx.UPDATE_UI_FROMIDLE flag, since this tells the window to only update the UI elements that need to be updated in idle time. Some windows update their elements only when necessary, for example when a menu is about to be shown. The following is an example of how to call UpdateWindowUI from an idle function:

def OnInternalIdle(self):

    if wx.UpdateUIEvent.CanUpdate(self):
        self.UpdateWindowUI(wx.UPDATE_UI_FROMIDLE)

New in version 0.9.5.