New in PyXLL 5.9
See ActiveX Controls for more information about ActiveX controls in PyXLL.
Creates an ActiveX control a Python UI control object.
The control object can be any of the following:
tkinter.Toplevel
PySide2.QtWidgets.QWidget
PySide6.QtWidgets.QWidget
PyQt5.QtWidgets.QWidget
PyQt6.QtWidgets.QWidget
wx.Frame
control – UI control of one of the supported types.
name – Name of the ActiveX control to be created.
width – Initial width of the control in points.
height – Initial height of the control in points.
top – Initial top position of the control in points.
left – Initial left position of the control in points.
timer_interval –
Time in seconds between calls to AtxBridgeBase.on_timer.
The ActiveX bridge classes are what integrate the Python UI toolkit with the Excel Windows message loop. They use on_timer to poll their own message queues. If you are finding the panel is not responsive enough you can reduce the timer interval with this setting.
This can also be defaulted by setting activex_timer_interval in the PYXLL section
of the pyxll.cfg config file.
bridge_cls – Class to use for integrating the control into Excel. If None this will be selected automatically based on the type of control.
Base class of bridges between the Python UI toolkits and PyXLL’s ActiveX control.
This can be used to add support for UI toolkits other than the standard ones supported by PyXLL.
Construct the ActiveX bridge. The control is the object
passed to create_activex_control.
Called before the window is attached to the ActiveX control host window.
Optional: Can be overridden in subclass
Called after the window is attached to the ActiveX control host window.
Optional: Can be overridden in subclass
Called when the ActiveX control host window is closed.
Optional: Can be overridden in subclass
Called when control window received a WM_CLOSE Windows message.
Optional: Can be overridden in subclass
Called when control window received a WM_DESTROY Windows message.
Optional: Can be overridden in subclass
Called when the ActiveX control host window received a Windows message.
Should return True if the message should be filtered and not passed
to the window’s message handler, or False otherwise.
hwnd – Window handle
msg – Windows message id
wparam – wparam passed with the message
lparam – lparam passed with the message
Optional: Can be overridden in subclass
Called when the ActiveX control host window received a Windows message.
Should return True if the message was handled and shouldn’t be processed
further, or False otherwise.
hwnd – Window handle
msg – Windows message id
wparam – wparam passed with the message
lparam – lparam passed with the message
Optional: Can be overridden in subclass
Called when the ActiveX control host control’s TranslateAccelerator Windows method is called.
This can be used to convert key presses into commands or events to pass to the UI toolkit control.
Should return True if the message was handled and shouldn’t be processed
further, or False otherwise.
Returning None is equivalent to returning (0, False).
hwnd – Window handle
msg – Windows message id
wparam – wparam passed with the message
lparam – lparam passed with the message
modifier – If the message is a WM_KEYDOWN message, the modifier will be set to indicate any key modifiers currently pressed. 0x0 = no key modifiers, 0x1 = Shift key pressed, 0x2 = Control key pressed, 0x4 = Alt key pressed.
Optional: Can be overridden in subclass
If this method is overridden then it will be called periodically and can be used to poll the UI toolkit’s message loop.
The interval between calls can be set by passing timer_interval to create_activex_control
or by setting activex_timer_interval in the PYXLL section of the pyxll.cfg config file.
Optional: Can be overridden in subclass
Sometimes you will want to create an ActiveX control when a worksheet function is called, instead of when a ribbon button or macro function is called.
For example, if you want an ActiveX control to be created each time a workbook is
opened one easy way to do that is to use a worksheet function using the recalc_on_open
argument to the xl_func decorator. That way, whenever the workbook is opened
the function will be called and can create the control.
However, in order to create the ActiveX control when the function is called you need
to also use schedule_call. You can’t make changes to the worksheet while
Excel is calculating and so instead you must use schedule_call to schedule
another function to be called after Excel has finished calculating.
Additionally, you should pass name to create_activex_control so that
when the control is created, it re-uses any existing control with the same name rather
than creating a new control every time it is called.
For example:
from pyxll import xl_func, schedule_call
@xl_func(recalc_on_open=True)
def create_my_control():
# This inner function will be called after Excel has finished calculating
def inner_func():
# Create your widget using whichever supported UI toolkit you prefer
widget = your_code_to_create_the_widget()
# Using the same name each time means that only one control will be used,
# even if this function is called multiple times.
create_activex_control(widget, name="My Custom Control")
# Calling our inner_func function once Excel has finished calculating
schedule_call(inner_func)
See Recalculating On Open for more details about how the recalc_on_open option works.
