ActiveX Controls ¶

create_activex_control ¶

create_activex_control(control, name=None, sheet=None, width=None, height=None, top=None, left=None, timer_interval=0.1, bridge_cls=None)

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

Parameters:

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.

Returns:

ActiveXHost

ActiveXHost ¶

class ActiveXHost

Returned by create_activex_control.

Invalidate()

Reqeusts that Excel redraws the control.

AtxBridgeBase ¶

class AtxBridgeBase

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.

__init__(self, control)

Construct the ActiveX bridge. The control is the object passed to create_activex_control.

close(self)

Close the host ActiveX window.

Do not override

get_hwnd(self)

Return the window handle as an integer.

Required: Override in subclass

width(self, dpi)

Return the width of the control, in points.

Required: Override in subclass

height(self, dpi)

Return the height of the control, in points.

Required: Override in subclass

pre_attach(self, hwnd)

Called before the window is attached to the ActiveX control host window.

Optional: Can be overridden in subclass

post_attach(self, hwnd)

Called after the window is attached to the ActiveX control host window.

Optional: Can be overridden in subclass

on_close(self)

Called when the ActiveX control host window is closed.

Optional: Can be overridden in subclass

on_window_closed(self)

Called when control window received a WM_CLOSE Windows message.

Optional: Can be overridden in subclass

on_window_destroyed(self)

Called when control window received a WM_DESTROY Windows message.

Optional: Can be overridden in subclass

filter_message(self, hwnd, msg, wparam, lparam)

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.

Parameters:	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

process_message(self, hwnd, msg, wparam, lparam)

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.

Parameters:	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

translate_accelerator(self, hwnd, msg, wparam, lparam, modifier)

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).

Parameters:	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

on_timer(self)

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

Creating an ActiveX Control from a Worksheet Function ¶

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.