PyXLL The Python Excel Add-In

Ribbon Functions ¶

These functions can be used to manipulate the Excel ribbon.

The ribbon can be updated at any time, for example as PyXLL is loading via the xl_on_open and xl_on_reload event handlers, or from a menu using using xl_menu.

See the section on customizing the ribbon for more details.

load_image ¶

load_image(name)

Loads an image file and returns it as a COM IPicture object suitable for use when customizing the ribbon.

This function can be set at the Ribbon image handler by setting the loadImage attribute on the customUI element in the ribbon XML file.

<customUI xmlns="http://schemas.microsoft.com/office/2006/01/customui"

            loadImage="pyxll.load_image">

    <ribbon>
        <tabs>
            <tab id="CustomTab" label="Custom Tab">
                <group id="Tools" label="Tools">
                    <button id="Reload"
                            size="large"
                            label="Reload PyXLL"
                            onAction="pyxll.reload"

                            image="reload.png"/>

                </group>
            </tab>
        </tabs>
    </ribbon>
</customUI>

Or it can be used when returning an image from a getImage callback.

Parameters:name (string) – Filename or resource location of the image file to load. This may be an absolute path or a resource location in the form module:resource.
Returns:A COM IPicture object (the exact type depends on the com_package setting in the config.

get_ribbon_xml ¶

get_ribbon_xml()

Returns the XML used to customize the Excel ribbon bar, as a string.

See the section on customizing the ribbon for more details.

set_ribbon_xml ¶

set_ribbon_xml(xml, reload=True)

Sets the XML used to customize the Excel ribbon bar.

Parameters:
  • xml – XML to set, as a string.
  • reload – If True, the ribbon bar will be reloaded using the new XML (does not reload PyXLL).

See the section on customizing the ribbon for more details.

set_ribbon_tab ¶

set_ribbon_tab(xml, tab_id=None, reload=True)

Sets a single tab in the ribbon using an XML fragment.

Instead of replacing the whole ribbon XML this function takes a tab element from the input XML and updates the ribbon XML with that tab.

If multiple tabs exist in the input XML, the first who’s id attribute matches tab_id is used (or simply the first tab element if tab_id is None).

If a tab already exists in the ribbon XML with the same id attribute then it is replaced, otherwise the new tab is appended to the tabs element.

Parameters:
  • xml – XML document containing at least one tab element.
  • tab_id – id of the tab element to set (or None to use the first tab element in the document).
  • reload – If True, the ribbon bar will be reloaded using the new XML (does not reload PyXLL).

remove_ribbon_tab ¶

remove_ribbon_tab(tab_id, reload=True)

Removes a single tab from the ribbon XML where the tab element’s id attribute matches tab_id.

Parameters:
  • tab_id – id of the tab element to remove.
  • reload – If True, the ribbon bar will be reloaded using the new XML (does not reload PyXLL).
Returns:

True if a tab was removed, False otherwise.

IRibbonControl ¶

class IRibbonControl

Many ribbon callbacks will be passed a control object as a IRibbonControl object.

The control object corresponds to the ribbon control item handling the action.

This class is a Python wrapper around the Excel COM type of the same name.

Id

Gets the ID of the control specified in the Ribbon XML markup customization file. Read-only.

Tag

Used to store arbitrary strings and fetch them at runtime. Read-only.

Context

Represents the active window containing the Ribbon user interface that triggers a callback procedure. Read-only.

IRibbonUI ¶

class IRibbonUI

Certain ribbon callbacks such as onLoad will be passed an IRibbonUI object.

This class is a Python wrapper around the Excel COM type of the same name.

Invalidate(self)

Invalidates the cached values for all of the controls of the Ribbon user interface.

InvalidateControl(self, control_id)

Invalidates the cached value for a single control on the Ribbon user interface.

Parameters:control_id – Id of the control to invalidate.
InvalidateControlMso(self, control_id)

Invalidating a control, repaints the screen and causes any callback procedures associated with that control to execute.

Parameters:control_id – Mso id of the control to invalidate.
ActivateTab(self, tab_id)

Activates the specified custom tab.

Parameters:tab_id – Id of the tab to activate.
ActivateTabMso(self, tab_id)

Activates the specified custom tab.

Parameters:tab_id – Mso id of the tab to activate.
ActivateTabQ(self, tab_id)

Activates the specified custom tab.

Parameters:tab_id – Fully qualified id of the tab to activate including the namespace.
© Copyright 2024 PyXLL Ltd