activex

Load ActiveX controls in an application window.

The following classes are available to interact with ActiveX controls

• Application
• Icon
• Menu
• MenuGroup
• MenuItem

and the following enumerations

• Colour
• ExtendedWindowStyle
• MenuFlag
• MessageBoxOption
• ShowWindow
• WindowClassStyle
• WindowPosition
• WindowStyle

Application

Application(
    *,
    background=Colour.WHITE,
    class_style=WindowClassStyle.NONE,
    icon=None,
    title="ActiveX",
    window_style=WindowStyle.OVERLAPPEDWINDOW,
)

Create the main application window to display ActiveX controls.

Parameters:

Name	Type	Description	Default
background	Colour	The background colour of the main window.	WHITE
class_style	WindowClassStyle	The class style(s). Can be any combination (bitwise OR) of WindowClassStyle values.	NONE
icon	Icon | None	The application icon.	None
title	str	The text to display in the titlebar (if one is visible).	'ActiveX'
window_style	WindowStyle	The window style(s). Can be any combination (bitwise OR) of WindowStyle values.	OVERLAPPEDWINDOW

Source code in src/msl/loadlib/activex.py

def __init__(
    self,
    *,
    background: Colour = Colour.WHITE,
    class_style: WindowClassStyle = WindowClassStyle.NONE,
    icon: Icon | None = None,
    title: str = "ActiveX",
    window_style: WindowStyle = WindowStyle.OVERLAPPEDWINDOW,
) -> None:
    """Create the main application window to display ActiveX controls.

    Args:
        background: The background colour of the main window.
        class_style: The class style(s). Can be any combination (bitwise OR)
            of [WindowClassStyle][msl.loadlib.activex.WindowClassStyle] values.
        icon: The application icon.
        title: The text to display in the titlebar (if one is visible).
        window_style: The window style(s). Can be any combination (bitwise OR)
            of [WindowStyle][msl.loadlib.activex.WindowStyle] values.
    """
    super().__init__()
    self._atom: wt.ATOM | None = None
    self._icon: Icon | None = icon  # prevent an icon from being garbage collected
    self._events: list[Any] = []  # actually list[_AdviseConnection]
    self._msg_handlers: list[Callable[[int, int, int, int], None]] = []

    if not windll_initialised:
        msg = "An ActiveX application is not supported on this platform"
        raise OSError(msg)

    h_icon = icon.hicon if isinstance(icon, Icon) else user32.LoadIconW(None, wt.LPCWSTR(IDI_APPLICATION))

    self._window: WNDCLASSEXW = WNDCLASSEXW()
    self._window.cbSize = ctypes.sizeof(WNDCLASSEXW)
    self._window.style = class_style
    self._window.lpfnWndProc = WNDPROC(self._window_procedure)
    self._window.cbClsExtra = 0
    self._window.cbWndExtra = 0
    self._window.hInstance = kernel32.GetModuleHandleW(None)
    self._window.hIcon = h_icon
    self._window.hCursor = user32.LoadCursorW(None, wt.LPCWSTR(IDC_ARROW))
    self._window.hbrBackground = gdi32.GetStockObject(background)
    self._window.lpszMenuName = f"ActiveXMenu{id(self._window)}"  # make the name unique
    self._window.lpszClassName = f"ActiveXClass{id(self._window)}"
    self._window.hIconSm = h_icon

    self._atom = user32.RegisterClassExW(self._window)

    self._menu: Menu = Menu()

    self._hwnd: int = _create_window(
        class_name=self._window.lpszClassName,
        window_name=title,
        style=window_style,
        instance=self._window.hInstance,
    )

    self._thread_id: int = user32.GetWindowThreadProcessId(self._hwnd, None)

    # calling AtlAxWinInit initializes ATL's control hosting code
    # by registering the "AtlAxWin" window class so that this window
    # class is available to the CreateWindowExW function
    if not atl.AtlAxWinInit():
        msg = "Cannot register the 'AtlAxWin' window class"
        raise OSError(msg)

hwnd property

hwnd

int — The handle to the main application window.

menu property

menu

Menu — The menu instance.

thread_id property

thread_id

int — The identifier of the thread that created the main application window.

add_message_handler

add_message_handler(handler)

Add a custom handler for processing window messages.

Messages correspond to events from the user and from the operating system.

Parameters:

Name	Type	Description	Default
handler	Callable[[int, int, int, int], None]	A function that processes messages sent to the main window. The function must accept four positional arguments (all integer values) and the returned object is ignored. See WindowProc for more details about the input arguments to the handler.	required

Source code in src/msl/loadlib/activex.py

def add_message_handler(self, handler: Callable[[int, int, int, int], None]) -> None:
    """Add a custom handler for processing window messages.

    Messages correspond to events from the user and from the operating system.

    Args:
        handler: A function that processes messages sent to the main window.
            The function must accept four positional arguments (all integer values)
            and the returned object is ignored. See
            [WindowProc](https://learn.microsoft.com/en-us/windows/win32/learnwin32/writing-the-window-procedure){:target="_blank"}
            for more details about the input arguments to the `handler`.
    """
    self._msg_handlers.append(handler)

close

close()

Close the application.

Source code in src/msl/loadlib/activex.py

def close(self) -> None:
    """Close the application."""
    user32.PostMessageW(self._hwnd, WM_DESTROY, 0, 0)

handle_events

handle_events(source, sink=None, *, interface=None)

Handle ActiveX events (see GetEvents).

Parameters:

Name	Type	Description	Default
source	Any	An ActiveX object that emits events.	required
sink	Any	The object that handles the events. The sink must define methods with the same names as the ActiveX event names. If not specified, the Application instance is used as the sink.	None
interface	Any	The COM interface to use.	None

Returns:

Type	Description
Any	An _AdviseConnection object from comtypes.

Source code in src/msl/loadlib/activex.py

def handle_events(self, source: Any, sink: Any = None, *, interface: Any = None) -> Any:
    """Handle ActiveX events (see [GetEvents][]{:target="_blank"}).

    Args:
        source: An ActiveX object that emits events.
        sink: The object that handles the events. The `sink` must
            define methods with the same names as the ActiveX event names. If not
            specified, the [Application][msl.loadlib.activex.Application] instance
            is used as the `sink`.
        interface: The COM interface to use.

    Returns:
        An `_AdviseConnection` object from `comtypes`.
    """
    assert client is not None  # noqa: S101
    cxn = client.GetEvents(source, sink or self, interface=interface)  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]
    self._events.append(cxn)
    return cxn  # pyright: ignore[reportUnknownVariableType]

load

load(
    activex_id,
    *,
    parent=None,
    x=0,
    y=0,
    width=0,
    height=0,
    style=WindowStyle.VISIBLE | WindowStyle.CHILD,
    ex_style=ExtendedWindowStyle.LEFT,
)

Load an ActiveX library.

Parameters:

Name	Type	Description	Default
activex_id	str	ProgID or CLSID of the ActiveX object.	required
parent	int | None	The handle to the parent window that the ActiveX object will belong to. Default is the main application window.	None
x	int	Horizontal position of the ActiveX object in the parent window.	0
y	int	Vertical position of the ActiveX object in the parent window.	0
width	int	Width (in pixels) of the ActiveX object.	0
height	int	Height (in pixels) of the ActiveX object.	0
style	WindowStyle	Style of the window that is created to contain the ActiveX object. Can be any combination (bitwise OR) of WindowStyle values.	VISIBLE | CHILD
ex_style	ExtendedWindowStyle	Extended style of the window that is created to contain the ActiveX object. Can be any combination (bitwise OR) of ExtendedWindowStyle values.	LEFT

Returns:

Type	Description
Any	The interface pointer to the ActiveX library.

Source code in src/msl/loadlib/activex.py

def load(  # noqa: PLR0913
    self,
    activex_id: str,
    *,
    parent: int | None = None,
    x: int = 0,
    y: int = 0,
    width: int = 0,
    height: int = 0,
    style: WindowStyle = WindowStyle.VISIBLE | WindowStyle.CHILD,
    ex_style: ExtendedWindowStyle = ExtendedWindowStyle.LEFT,
) -> Any:
    """Load an ActiveX library.

    Args:
        activex_id: ProgID or CLSID of the ActiveX object.
        parent: The handle to the parent window that the ActiveX object
            will belong to. Default is the main application window.
        x: Horizontal position of the ActiveX object in the parent window.
        y: Vertical position of the ActiveX object in the parent window.
        width: Width (in pixels) of the ActiveX object.
        height: Height (in pixels) of the ActiveX object.
        style: Style of the window that is created to contain the ActiveX
            object. Can be any combination (bitwise OR) of
            [WindowStyle][msl.loadlib.activex.WindowStyle] values.
        ex_style: Extended style of the window that is created to contain
            the ActiveX object. Can be any combination (bitwise OR) of
            [ExtendedWindowStyle][msl.loadlib.activex.ExtendedWindowStyle] values.

    Returns:
        The interface pointer to the ActiveX library.
    """
    if comtypes is None:
        msg = "comtypes must be installed to load an ActiveX library"
        raise OSError(msg)

    try:
        window_name = str(comtypes.GUID.from_progid(activex_id))  # pyright: ignore[reportUnknownMemberType,reportUnknownArgumentType]
    except (TypeError, OSError):
        window_name = None

    if not window_name:
        msg = f"Cannot find an ActiveX library with ID {activex_id!r}"
        raise OSError(msg)

    if parent is None:
        parent = self._hwnd

    hwnd = _create_window(
        class_name="AtlAxWin",
        window_name=window_name,
        style=style,
        ex_style=ex_style,
        x=x,
        y=y,
        width=width,
        height=height,
        parent=parent,
        instance=kernel32.GetModuleHandleW(None),
    )

    unknown = ctypes.POINTER(comtypes.IUnknown)()  # pyright: ignore[reportUnknownMemberType, reportUnknownArgumentType, reportDeprecated]
    ret = atl.AtlAxGetControl(hwnd, ctypes.byref(unknown))
    if ret != 0:
        msg = f"AtlAxGetControl {ctypes.WinError()}"
        raise OSError(msg)
    assert client is not None  # noqa: S101
    return client.GetBestInterface(unknown)  # pyright: ignore[reportUnknownMemberType,reportUnknownVariableType]

message_box staticmethod

message_box(
    *,
    hwnd=None,
    language_id=0,
    options=MessageBoxOption.OK,
    text="",
    title="",
)

Display a modal dialog box (see MessageBoxExW).

Parameters:

Name	Type	Description	Default
hwnd	int | None	A handle to the owner window of the message box to be created.	None
language_id	int	The language for the text displayed in the message box button(s).	0
options	MessageBoxOption	The contents and behaviour of the dialog box. Can be any combination (bitwise OR) of MessageBoxOption values.	OK
text	str	The message to be displayed.	''
title	str	The dialog box title.	''

Returns:

Type	Description
int	An indication of how the message box was closed.

Source code in src/msl/loadlib/activex.py

@staticmethod
def message_box(
    *,
    hwnd: int | None = None,
    language_id: int = 0,
    options: MessageBoxOption = MessageBoxOption.OK,
    text: str = "",
    title: str = "",
) -> int:
    """Display a modal dialog box (see [MessageBoxExW]{:target="_blank"}).

    [MessageBoxExW]: https://learn.microsoft.com/en-us/windows/win32/api/winuser/nf-winuser-messageboxexw

    Args:
        hwnd: A handle to the owner window of the message box to be created.
        language_id: The language for the text displayed in the message box button(s).
        options: The contents and behaviour of the dialog box. Can be any combination
            (bitwise OR) of [MessageBoxOption][msl.loadlib.activex.MessageBoxOption] values.
        text: The message to be displayed.
        title: The dialog box title.

    Returns:
        An indication of how the message box was closed.
    """
    ret: int = user32.MessageBoxExW(hwnd, text, title, options, language_id)
    return ret

run staticmethod

run()

Run the application.

This is a blocking call. Create and run the application in a separate thread if you want to execute other code while the application is running.

Source code in src/msl/loadlib/activex.py

@staticmethod
def run() -> None:
    """Run the application.

    This is a blocking call. Create and run the application in a separate
    thread if you want to execute other code while the application is running.
    """
    msg = wt.MSG()
    try:
        while user32.GetMessageW(msg, None, 0, 0) != 0:
            user32.TranslateMessage(msg)
            user32.DispatchMessageW(msg)
    except KeyboardInterrupt:
        pass

set_window_position

set_window_position(
    x, y, width, height, *, flags=WindowPosition.NONE
)

Set the position of the main window.

Parameters:

Name	Type	Description	Default
x	int	The new position of the left side of the window.	required
y	int	The new position of the top of the window.	required
width	int	The new width (in pixels) of the window.	required
height	int	The new height (in pixels) of the window.	required
flags	WindowPosition	The window sizing and positioning flags. Can be any combination (bitwise OR) of WindowPosition values.	NONE

Source code in src/msl/loadlib/activex.py

def set_window_position(
    self, x: int, y: int, width: int, height: int, *, flags: WindowPosition = WindowPosition.NONE
) -> None:
    """Set the position of the main window.

    Args:
        x: The new position of the left side of the window.
        y: The new position of the top of the window.
        width: The new width (in pixels) of the window.
        height: The new height (in pixels) of the window.
        flags: The window sizing and positioning flags. Can be any combination
            (bitwise OR) of [WindowPosition][msl.loadlib.activex.WindowPosition] values.
    """
    user32.SetWindowPos(self._hwnd, None, x, y, width, height, flags)

set_window_size

set_window_size(width, height)

Set the size of the main window.

Parameters:

Name	Type	Description	Default
width	int	The new width (in pixels) of the window.	required
height	int	The new height (in pixels) of the window.	required

Source code in src/msl/loadlib/activex.py

def set_window_size(self, width: int, height: int) -> None:
    """Set the size of the main window.

    Args:
        width: The new width (in pixels) of the window.
        height: The new height (in pixels) of the window.
    """
    # SWP_NOMOVE Retains the current position (ignores X and Y parameters)
    self.set_window_position(0, 0, width, height, flags=WindowPosition.NOMOVE)

set_window_title

set_window_title(title)

Set the text to display in the window's title bar.

Parameters:

Name	Type	Description	Default
title	str	The title bar text.	required

Source code in src/msl/loadlib/activex.py

def set_window_title(self, title: str) -> None:
    """Set the text to display in the window's title bar.

    Args:
        title: The title bar text.
    """
    user32.SetWindowTextW(self._hwnd, title)

show

show(command=ShowWindow.NORMAL)

Show the main application window.

Parameters:

Name	Type	Description	Default
command	ShowWindow	Controls how the window is shown.	NORMAL

Source code in src/msl/loadlib/activex.py

def show(self, command: ShowWindow = ShowWindow.NORMAL) -> None:
    """Show the main application window.

    Args:
        command: Controls how the window is shown.
    """
    user32.SetMenu(self._hwnd, self._menu.hmenu)
    user32.ShowWindow(self._hwnd, command)
    user32.UpdateWindow(self._hwnd)

unhandle_events

unhandle_events(*advise_connection)

Stop handling ActiveX events.

Added in version 1.1

Parameters:

Name	Type	Description	Default
advise_connection	Any	The event connection(s) to stop listening to. The object is one that is returned by handle_events. If no arguments are specified, stops handling all ActiveX events. It is also necessary to delete (del) the connection variable(s) in the calling program (and maybe invoke the Python garbage collector) if events are still firing.	()

Source code in src/msl/loadlib/activex.py

def unhandle_events(self, *advise_connection: Any) -> None:
    """Stop handling ActiveX events.

    !!! note "Added in version 1.1"

    Args:
        advise_connection: The event connection(s) to stop listening to. The object is one that
            is returned by [handle_events][msl.loadlib.activex.Application.handle_events]. If no
            arguments are specified, stops handling all ActiveX events. It is also necessary to
            delete ([del][]) the connection variable(s) in the calling program (and maybe invoke
            the Python garbage collector) if events are still firing.
    """
    if not advise_connection:
        for event in self._events:
            event.disconnect()
        self._events.clear()
        return

    for ac in advise_connection:
        ac.disconnect()
        self._events.remove(ac)

wait_for_events

wait_for_events(timeout)

Wait for ActiveX events to occur (see PumpEvents).

Added in version 1.1

Parameters:

Name	Type	Description	Default
timeout	float	The number of seconds to wait for events to occur.	required

Source code in src/msl/loadlib/activex.py

def wait_for_events(self, timeout: float) -> None:
    """Wait for ActiveX events to occur (see [PumpEvents][]{:target="_blank"}).

    !!! note "Added in version 1.1"

    Args:
        timeout: The number of seconds to wait for events to occur.
    """
    assert client is not None  # noqa: S101
    client.PumpEvents(timeout)  # pyright: ignore[reportUnknownMemberType]

Colour

Bases: IntEnum

Background colour.

Attributes:

Name	Type	Description
WHITE	int	0
LIGHT_GREY	int	1
GREY	int	2
DARK_GREY	int	3
BLACK	int	4

ExtendedWindowStyle

Bases: IntFlag

Extended window style flags.

Attributes:

Name	Type	Description
DLGMODALFRAME	int	0x00000001
NOPARENTNOTIFY	int	0x00000004
TOPMOST	int	0x00000008
ACCEPTFILES	int	0x00000010
TRANSPARENT	int	0x00000020
MDICHILD	int	0x00000040
TOOLWINDOW	int	0x00000080
WINDOWEDGE	int	0x00000100
CLIENTEDGE	int	0x00000200
CONTEXTHELP	int	0x00000400
RIGHT	int	0x00001000
LEFT	int	0x00000000
RTLREADING	int	0x00002000
LTRREADING	int	0x00000000
LEFTSCROLLBAR	int	0x00004000
RIGHTSCROLLBAR	int	0x00000000
CONTROLPARENT	int	0x00010000
STATICEDGE	int	0x00020000
APPWINDOW	int	0x00040000
LAYERED	int	0x00080000
NOINHERITLAYOUT	int	0x00100000
NOREDIRECTIONBITMAP	int	0x00200000
LAYOUTRTL	int	0x00400000
COMPOSITED	int	0x02000000
NOACTIVATE	int	0x08000000
OVERLAPPEDWINDOW	int	WINDOWEDGE | CLIENTEDGE
PALETTEWINDOW	int	WINDOWEDGE | TOOLWINDOW | TOPMOST

Icon

Icon(file, *, index=0, hinstance=None)

Extract an icon from an executable file, DLL or icon file.

Parameters:

Name	Type	Description	Default
file	PathLike	The path to an executable file, DLL or icon file.	required
index	int	The zero-based index of the icon to extract.	0
hinstance	int | None	Handle to the instance of the calling application.	None

Source code in src/msl/loadlib/activex.py

def __init__(self, file: PathLike, *, index: int = 0, hinstance: int | None = None) -> None:
    """Extract an icon from an executable file, DLL or icon file.

    Args:
        file: The path to an executable file, DLL or icon file.
        index: The zero-based index of the icon to extract.
        hinstance: Handle to the instance of the calling application.
    """
    self._hicon: int | None = None

    if not windll_initialised:
        msg = "Loading an icon is not supported on this platform"
        raise OSError(msg)

    if index < 0:
        msg = "A negative index is not supported"
        raise ValueError(msg)

    if hinstance is None:
        hinstance = kernel32.GetModuleHandleW(None)

    self._file: str = os.fsdecode(file)
    self._index: int = index
    self._hicon = shell32.ExtractIconW(hinstance, file, index)

hicon property

hicon

int | None — The handle to the icon or None if an icon was not found in the file.

destroy

destroy()

Destroys the icon and frees any memory the icon occupied.

Source code in src/msl/loadlib/activex.py

def destroy(self) -> None:
    """Destroys the icon and frees any memory the icon occupied."""
    if self._hicon is not None and self._hicon > 0:
        user32.DestroyIcon(self._hicon)
        self._hicon = None

Menu

Menu()

A menu associated with the main application window.

Warning

Do not instantiate directly. Use the Application.menu property to access the menu instance.

Source code in src/msl/loadlib/activex.py

def __init__(self) -> None:
    """A menu associated with the main application window.

    !!! warning
        Do not instantiate directly. Use the
        [Application.menu][msl.loadlib.activex.Application.menu]
        property to access the menu instance.
    """
    self._hmenu: int = user32.CreateMenu()

hmenu property

hmenu

int — The handle to the main menu.

append

append(
    hmenu,
    text,
    *,
    callback=None,
    data=None,
    flags=MenuFlag.STRING,
)

Create a new MenuItem and append it to a popup menu.

Parameters:

Name	Type	Description	Default
hmenu	int	The handle of a popup menu to append the new menu item to.	required
text	str	The content of the new menu item.	required
callback	Callable[[MenuItem], None] | None	A callable object that will be called when this menu item is selected. The callable object will receive the MenuItem instance as an argument and the returned object is ignored.	None
data	Any	User data associated with the menu item.	None
flags	MenuFlag	Controls the appearance and behaviour of the new menu item. Can be any combination (bitwise OR) of MenuFlag values.	STRING

Returns:

Type	Description
MenuItem	The menu item that was appended.

Source code in src/msl/loadlib/activex.py

def append(
    self,
    hmenu: int,
    text: str,
    *,
    callback: Callable[[MenuItem], None] | None = None,
    data: Any = None,
    flags: MenuFlag = MenuFlag.STRING,
) -> MenuItem:
    """Create a new [MenuItem][msl.loadlib.activex.MenuItem] and append it to a popup menu.

    Args:
        hmenu: The handle of a popup menu to append the new menu item to.
        text: The content of the new menu item.
        callback: A callable object that will be called when this menu item is selected.
            The callable object will receive the [MenuItem][msl.loadlib.activex.MenuItem]
            instance as an argument and the returned object is ignored.
        data: User data associated with the menu item.
        flags: Controls the appearance and behaviour of the new menu item. Can be any
            combination (bitwise OR) of [MenuFlag][msl.loadlib.activex.MenuFlag] values.

    Returns:
        The menu item that was appended.
    """
    return MenuItem(hmenu=hmenu, text=text, callback=callback, flags=flags, data=data)

append_group

append_group(hmenu, menu_group)

Append a group of menu items to a popup menu.

Parameters:

Name	Type	Description	Default
hmenu	int	The handle of a popup menu to append the group to.	required
menu_group	MenuGroup	A group of menu items.	required

Source code in src/msl/loadlib/activex.py

def append_group(self, hmenu: int, menu_group: MenuGroup) -> None:
    """Append a group of menu items to a popup menu.

    Args:
        hmenu: The handle of a popup menu to append the group to.
        menu_group: A group of menu items.
    """
    # all future item's appended to the group will have the same hmenu value
    menu_group._hmenu = hmenu  # pyright: ignore[reportPrivateUsage]  # noqa: SLF001

    # use menu_group._items to include the group's separator's
    for item in menu_group._items:  # pyright: ignore[reportPrivateUsage]  # noqa: SLF001
        item._hmenu = hmenu  # pyright: ignore[reportPrivateUsage]  # noqa: SLF001
        _maybe_append_item_to_menu(item)

append_separator

append_separator(hmenu)

Append a horizontal dividing line to a popup menu.

Parameters:

Name	Type	Description	Default
hmenu	int	The handle to a popup menu.	required

Source code in src/msl/loadlib/activex.py

def append_separator(self, hmenu: int) -> None:
    """Append a horizontal dividing line to a popup menu.

    Args:
        hmenu: The handle to a popup menu.
    """
    user32.AppendMenuW(hmenu, MenuFlag.SEPARATOR, next(_id), None)

create

create(text)

Create a new popup menu and append it to the main menu.

Parameters:

Name	Type	Description	Default
text	str	The text to display for the popup menu.	required

Returns:

Type	Description
int	The handle to the popup menu that was created.

Source code in src/msl/loadlib/activex.py

def create(self, text: str) -> int:
    """Create a new popup menu and append it to the main menu.

    Args:
        text: The text to display for the popup menu.

    Returns:
        The handle to the popup menu that was created.
    """
    flags = MenuFlag.STRING | MenuFlag.POPUP
    h: int = user32.CreatePopupMenu()
    user32.AppendMenuW(self._hmenu, flags, h, text)
    return h

MenuFlag

Bases: IntFlag

Menu item flags.

Attributes:

Name	Type	Description
BITMAP	int	0x00000004
CHECKED	int	0x00000008
DISABLED	int	0x00000002
ENABLED	int	0x00000000
GRAYED	int	0x00000001
MENUBARBREAK	int	0x00000020
MENUBREAK	int	0x00000040
OWNERDRAW	int	0x00000100
POPUP	int	0x00000010
SEPARATOR	int	0x00000800
STRING	int	0x00000000
UNCHECKED	int	0x00000000

MenuGroup

MenuGroup(name='')

A group of MenuItems.

Only one item in the group may have a check mark to indicate that a particular item is selected.

Parameters:

Name	Type	Description	Default
name	str	A name to associate with the group.	''

Source code in src/msl/loadlib/activex.py

def __init__(self, name: str = "") -> None:
    """A group of [MenuItem][msl.loadlib.activex.MenuItem]s.

    Only one item in the group may have a check mark to indicate
    that a particular item is selected.

    Args:
        name: A name to associate with the group.
    """
    self._name: str = name
    self._items: list[MenuItem] = []
    self._hmenu: int = -1

checked property writable

checked

MenuItem | None — The menu item in the group that is checked.

hmenu property

hmenu

int — The handle to the Menu that the menu group belongs to.

Added in version 1.1

name property

name

str — The name of the menu group.

append

append(
    text, *, callback=None, data=None, flags=MenuFlag.STRING
)

Create a new MenuItem and append it to the group.

Parameters:

Name	Type	Description	Default
text	str	The content of the new menu item.	required
callback	Callable[[MenuItem], None] | None	A callable object that will be called when this menu item is selected. The callable object will receive the MenuItem instance as an argument and the returned object is ignored.	None
data	Any	User data associated with the menu item.	None
flags	MenuFlag	Controls the appearance and behaviour of the new menu item. Can be any combination (bitwise OR) of MenuFlag values.	STRING

Returns:

Type	Description
MenuItem	The menu item that was appended to the group.

Source code in src/msl/loadlib/activex.py

def append(
    self,
    text: str,
    *,
    callback: Callable[[MenuItem], None] | None = None,
    data: Any = None,
    flags: MenuFlag = MenuFlag.STRING,
) -> MenuItem:
    """Create a new [MenuItem][msl.loadlib.activex.MenuItem] and append it to the group.

    Args:
        text: The content of the new menu item.
        callback: A callable object that will be called when this menu item is selected.
            The callable object will receive the [MenuItem][msl.loadlib.activex.MenuItem]
            instance as an argument and the returned object is ignored.
        data: User data associated with the menu item.
        flags: Controls the appearance and behaviour of the new menu item. Can be any
            combination (bitwise OR) of [MenuFlag][msl.loadlib.activex.MenuFlag] values.

    Returns:
        The menu item that was appended to the group.
    """
    item = MenuItem(hmenu=self._hmenu, text=text, callback=callback, flags=flags, data=data)
    self._items.append(item)
    return item

append_separator

append_separator()

Append a horizontal dividing line to the group.

Source code in src/msl/loadlib/activex.py

def append_separator(self) -> None:
    """Append a horizontal dividing line to the group."""
    self._items.append(MenuItem(hmenu=self._hmenu, text=None, callback=None, flags=MenuFlag.SEPARATOR, data=None))

MenuItem

MenuItem(**kwargs)

A menu item that belongs to a popup menu.

Warning

Do not instantiate this class directly. Use MenuGroup.append or Menu.append to create a new menu item.

Source code in src/msl/loadlib/activex.py

def __init__(self, **kwargs: Any) -> None:
    """A menu item that belongs to a popup menu.

    !!! warning
        Do not instantiate this class directly. Use
        [MenuGroup.append][msl.loadlib.activex.MenuGroup.append]
        or [Menu.append][msl.loadlib.activex.Menu.append]
        to create a new menu item.
    """
    self._id: int = next(_id)
    self._checked: bool = False

    self._hmenu: int = kwargs["hmenu"]
    self._text: str = kwargs["text"]
    self._callback: Callable[[MenuItem], None] | None = kwargs["callback"]
    self._flags: int = kwargs["flags"]

    self.data: Any = kwargs["data"]
    """[Any][typing.Any] — User-defined data associated with the menu item."""

    _maybe_append_item_to_menu(self)

callback property

callback

Callable[[MenuItem], None] | None — The function to call when the menu item is clicked.

The function receives an instance of the MenuItem that was selected as an argument and the return type is None.

checked property writable

checked

bool — Whether the menu item's check mark is shown.

data instance-attribute

data

Any — User-defined data associated with the menu item.

flags property

flags

int — The flags that were used to create the menu item.

hmenu property

hmenu

int — The handle to the popup menu that the menu item belongs to.

id property

id

int — The identifier of the menu item.

text property

text

str — The content of the menu item.

MessageBoxOption

Bases: IntFlag

Message box flags.

Attributes:

Name	Type	Description
ABORTRETRYIGNORE	int	0x00000002
CANCELTRYCONTINUE	int	0x00000006
HELP	int	0x00004000
OK	int	0x00000000
OKCANCEL	int	0x00000001
RETRYCANCEL	int	0x00000005
YESNO	int	0x00000004
YESNOCANCEL	int	0x00000003
ICONEXCLAMATION	int	0x00000030
ICONWARNING	int	0x00000030
ICONINFORMATION	int	0x00000040
ICONASTERISK	int	0x00000040
ICONQUESTION	int	0x00000020
ICONSTOP	int	0x00000010
ICONERROR	int	0x00000010
ICONHAND	int	0x00000010
DEFBUTTON1	int	0x00000000
DEFBUTTON2	int	0x00000100
DEFBUTTON3	int	0x00000200
DEFBUTTON4	int	0x00000300
APPLMODAL	int	0x00000000
SYSTEMMODAL	int	0x00001000
TASKMODAL	int	0x00002000
DEFAULT_DESKTOP_ONLY	int	0x00020000
RIGHT	int	0x00080000
RTLREADING	int	0x00100000
SETFOREGROUND	int	0x00010000
TOPMOST	int	0x00040000
SERVICE_NOTIFICATION	int	0x00200000

ShowWindow

Bases: IntEnum

Show window options.

Attributes:

Name	Type	Description
HIDE	int	0
SHOWNORMAL	int	1
NORMAL	int	1
SHOWMINIMIZED	int	2
SHOWMAXIMIZED	int	3
MAXIMIZE	int	3
SHOWNOACTIVATE	int	4
SHOW	int	5
MINIMIZE	int	6
SHOWMINNOACTIVE	int	7
SHOWNA	int	8
RESTORE	int	9
SHOWDEFAULT	int	10
FORCEMINIMIZE	int	11

WindowClassStyle

Bases: IntFlag

Window class style flags.

Attributes:

Name	Type	Description
NONE	int	0x0000
BYTEALIGNCLIENT	int	0x1000
BYTEALIGNWINDOW	int	0x2000
CLASSDC	int	0x0040
DBLCLKS	int	0x0008
DROPSHADOW	int	0x00020000
GLOBALCLASS	int	0x4000
HREDRAW	int	0x0002
NOCLOSE	int	0x0200
OWNDC	int	0x0020
PARENTDC	int	0x0080
SAVEBITS	int	0x0800
VREDRAW	int	0x0001

WindowPosition

Bases: IntFlag

Window position flags.

Attributes:

Name	Type	Description
NONE	int	0x0000
ASYNCWINDOWPOS	int	0x4000
DEFERERASE	int	0x2000
DRAWFRAME	int	0x0020
FRAMECHANGED	int	0x0020
HIDEWINDOW	int	0x0080
NOACTIVATE	int	0x0010
NOCOPYBITS	int	0x0100
NOMOVE	int	0x0002
NOOWNERZORDER	int	0x0200
NOREDRAW	int	0x0008
NOREPOSITION	int	0x0200
NOSENDCHANGING	int	0x0400
NOSIZE	int	0x0001
NOZORDER	int	0x0004
SHOWWINDOW	int	0x0040

WindowStyle

Bases: IntFlag

Window style flags.

Attributes:

Name	Type	Description
OVERLAPPED	int	0x00000000
POPUP	int	0x80000000
CHILD	int	0x40000000
MINIMIZE	int	0x20000000
VISIBLE	int	0x10000000
DISABLED	int	0x08000000
CLIPSIBLINGS	int	0x04000000
CLIPCHILDREN	int	0x02000000
MAXIMIZE	int	0x01000000
CAPTION	int	0x00C00000
BORDER	int	0x00800000
DLGFRAME	int	0x00400000
VSCROLL	int	0x00200000
HSCROLL	int	0x00100000
SYSMENU	int	0x00080000
THICKFRAME	int	0x00040000
GROUP	int	0x00020000
TABSTOP	int	0x00010000
MINIMIZEBOX	int	0x00020000
MAXIMIZEBOX	int	0x00010000
TILED	int	OVERLAPPED
ICONIC	int	MINIMIZE
SIZEBOX	int	THICKFRAME
OVERLAPPEDWINDOW	int	OVERLAPPED | CAPTION | SYSMENU | THICKFRAME | MINIMIZEBOX | MAXIMIZEBOX
POPUPWINDOW	int	POPUP | BORDER | SYSMENU
CHILDWINDOW	int	CHILD
TILEDWINDOW	int	OVERLAPPEDWINDOW