Attributes Reference

ID attributes

Every control needs exactly one of id, idMso, or idQ.

Qualified IDs example:

<customUI xmlns="http://schemas.microsoft.com/office/2009/07/customui"
          xmlns:myaddin="MyAddInNamespace">
  <ribbon>
    <tabs>
      <tab idQ="myaddin:MyTab" label="Shared Tab">
        ...
      </tab>
    </tabs>
  </ribbon>
</customUI>

Another add-in can then add controls to myaddin:MyTab by referencing idQ="myaddin:MyTab".

Position attributes

Controls positioning within their parent container. These are mutually exclusive — use only one.

Label attributes

Image attributes

Only one of image, imageMso, or getImage may be specified.

Common imageMso values: RunMacro, FileSave, FileOpen, FilePrint, Undo, Redo, Cut, Copy, Paste, Bold, Italic, Underline, FormatCells, OptionsDialog, Refresh, Close, Help, HappyFace, SadFace, SelectAll, Find, Replace, Sort, Filter

Custom images with PyXLL: Set loadImage="pyxll.load_image" on the customUI root element, then use image="filename.png" on controls. pyxll.load_image handles PNG transparency correctly. For package resources use image="module:resource_name". Without pyxll.load_image, Excel's built-in image handler is used and PNG transparency may not render correctly.

Tooltip attributes

Keytip attributes

Visibility and enabled state

Show label

Size attribute (buttons and galleries in groups)

Callback values in PyXLL

In PyXLL, all callback attribute values are Python function name strings in module.function format. The module must be importable from the Python path:

<button id="myBtn" onAction="my_module.on_click"/>
<customUI loadImage="pyxll.load_image" onLoad="my_module.on_load"/>

The control parameter passed to most callbacks is an IRibbonControl object with:

• control.Id — the control's id attribute value
• control.Tag — the control's tag attribute value
• control.Context — the active window

The onLoad callback on customUI is the exception — it receives an IRibbonUI object (not IRibbonControl). Store it to invalidate control state:

_ribbon = None

def on_load(ribbon_ui):          # ribbon_ui is IRibbonUI
    global _ribbon
    _ribbon = ribbon_ui

def refresh():
    if _ribbon:
        _ribbon.Invalidate()
        # or: _ribbon.InvalidateControl("myControlId")
        # or: _ribbon.ActivateTab("myTabId")

Action callbacks

onAction signatures by control type:

# button, menu item:
def on_click(control):
    ...

# toggleButton, checkBox:
def on_toggle(control, pressed):   # pressed is True/False
    ...

# dropDown, gallery (when item selected):
def on_select(control, selectedId, selectedIndex):
    ...

Description attribute

Dynamic dropdown attributes

Used by dropDown, gallery, comboBox for dynamic item lists:

Dynamic menu content

String length limits