Custom Task Panes¶

create_ctp¶

create_ctp(control, title=None, width=None, height=None, position=CTPDockPositionRight, position_restrict=CTPDockPositionRestrictNone, top=None, left=None, timer_interval=0.1, bridge_cls=None)

Creates a Custom Task Pane from a 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.

• title – Title of the custom task pane to be created.

• width – Initial width of the custom task pane in points.

• height – Initial height of the custom task pane in points.

• position –

  Where to display the custom task pane. Can be any of:

  • CTPDockPositionLeft

  • CTPDockPositionTop

  • CTPDockPositionRight

  • CTPDockPositionBottom

  • CTPDockPositionFloating

• position_restrict –

  Restrict how the user can reposition the custom task pane. Can be any of:

  • CTPDockPositionRestrictNone

  • CTPDockPositionRestrictNoChange

  • CTPDockPositionRestrictNoHorizontal

  • CTPDockPositionRestrictNoVertical

  New in PyXLL 5.5

• top – Initial top position of custom task pane (only used if floating). New in PyXLL 5.2

• left – Initial left position of custom task pane (only used if floating). New in PyXLL 5.2

• timer_interval –

  Time in seconds between calls to CTPBridgeBase.on_timer.

  The CTP 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 ctp_timer_interval in the PYXLL section of the pyxll.cfg config file.

  New in PyXLL 5.1

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

CustomTaskPane (New in PyXLL 5.5)

CustomTaskPane¶

class CustomTaskPane

Wrapper around the Excel COM _CustomTaskPane type.

Returned by create_ctp.

New in PyXLL 5.5

Title

Gets the title of a CustomTaskPane object. Read-only.

Application

Gets the Application object of the host application. Read-only.

Window

Gets the parent window object of the _CustomTaskPane object. Read-only.

Visible

True if the specified _CustomTaskPane object is visible. Read-only.

ContentControl

Gets the Microsoft ActiveX® control instance displayed in the custom task pane frame. Read-only.

Height

Gets or sets the height of the CustomTaskPane object (in points). Read/write.

Width

Gets or sets the width of the task pane specified by the CustomTaskPane object. Read/write.

DockPosition

Gets or sets a value specifying the docked position of a _CustomTaskPane object. Read/write.

Permitted values are:

• CTPDockPositionLeft

• CTPDockPositionTop

• CTPDockPositionRight

• CTPDockPositionBottom

• CTPDockPositionFloating

DockPositionRestrict

Gets or sets a value specifying a restriction on the orientation of a _CustomTaskPane object. Read/write.

Permitted values are:

• CTPDockPositionRestrictNone

• CTPDockPositionRestrictNoChange

• CTPDockPositionRestrictNoHorizontal

• CTPDockPositionRestrictNoVertical

Delete()

Deletes the custom task pane.

CTPBridgeBase¶

class CTPBridgeBase

Base class of bridges between the Python UI toolkits and PyXLL’s Custom Task Panes.

This can be used to add support for UI toolkits other than the standard ones supported by PyXLL.

__init__(self, control)

Construct the custom task pane bridge. The control is the object passed to create_ctp.

close(self)

Close the host CTP window.

Do not override

get_hwnd(self)

Return the window handle as an integer.

Required: Override in subclass

get_title(self)

Return the window title as a string.

Optional: Can be overridden in subclass

pre_attach(self, hwnd)

Called before the window is attached to the Custom Task Pane host window.

Optional: Can be overridden in subclass

post_attach(self, hwnd)

Called after the window is attached to the Custom Task Pane host window.

Optional: Can be overridden in subclass

on_close(self)

Called when the Custom Task Pane 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

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

Called when the Custom Task Panel host window received a Windows message.

Should return a tuple of (result, handled) where the result is an integer and handled is a bool indicating whether the message has been handled or not. Messages that have been handled will not be passed to the default message handler.

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

Optional: Can be overridden in subclass

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

Called when the Custom Task Panel 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 a tuple of (result, handled) where the result is an integer and handled is a bool indicating whether the message has been handled or not. Messages that have been handled will not be passed to the default message handler.

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_ctp or by setting ctp_timer_interval in the PYXLL section of the pyxll.cfg config file.

Optional: Can be overridden in subclass

CTPDockPositionLeft = 0

CTPDockPositionTop = 1

CTPDockPositionRight = 2

CTPDockPositionBottom = 3

CTPDockPositionFloating = 4

CTPDockPositionRestrictNone = 0

CTPDockPositionRestrictNoChange = 1

CTPDockPositionRestrictNoHorizontal = 2

CTPDockPositionRestrictNoVertical = 3