Skip to content

activex¤

Load ActiveX controls in an application window.

The following classes are available to interact with ActiveX controls

and the following enumerations

Application ¤

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

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
style WindowStyle

The window style(s). Can be any combination (bitwise OR) of WindowStyle values.

OVERLAPPEDWINDOW
title str

The text to display in the titlebar (if one is visible).

'ActiveX'
Source code in src/msl/loadlib/activex.py
924
925
926
927
928
929
930
931
932
933
934
935
936
937
938
939
940
941
942
943
944
945
946
947
948
949
950
951
952
953
954
955
956
957
958
959
960
961
962
963
964
965
966
967
968
969
970
971
972
973
974
975
976
977
978
979
980
981
982
983
984
985
986
987
988
def __init__(
    self,
    *,
    background: Colour = Colour.WHITE,
    class_style: WindowClassStyle = WindowClassStyle.NONE,
    icon: Icon | None = None,
    style: WindowStyle = WindowStyle.OVERLAPPEDWINDOW,
    title: str = "ActiveX",
) -> 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.
        style: The window style(s). Can be any combination (bitwise OR)
            of [WindowStyle][msl.loadlib.activex.WindowStyle] values.
        title: The text to display in the titlebar (if one is visible).
    """
    super().__init__()
    self._atom: wt.ATOM | None = None
    self._icon: Icon | None = icon  # prevent an icon from being garbage collected
    self._event_connections: 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=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
1017
1018
1019
1020
1021
1022
1023
1024
1025
1026
1027
1028
1029
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
1031
1032
1033
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 events from an ActiveX object (see GetEvents).

Parameters:

Name Type Description Default
source Any

An ActiveX object that emits events.

required
sink Callable[..., Any] | None

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
1035
1036
1037
1038
1039
1040
1041
1042
1043
1044
1045
1046
1047
1048
1049
1050
1051
1052
def handle_events(self, source: Any, sink: Callable[..., Any] | None = None, *, interface: Any = None) -> Any:
    """Handle events from an ActiveX object (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._event_connections.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
1059
1060
1061
1062
1063
1064
1065
1066
1067
1068
1069
1070
1071
1072
1073
1074
1075
1076
1077
1078
1079
1080
1081
1082
1083
1084
1085
1086
1087
1088
1089
1090
1091
1092
1093
1094
1095
1096
1097
1098
1099
1100
1101
1102
1103
1104
1105
1106
1107
1108
1109
1110
1111
1112
1113
1114
1115
1116
1117
1118
1119
1120
1121
1122
1123
1124
1125
1126
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,reportUnknownVariableType,reportUnknownArgumentType]
    ret = atl.AtlAxGetControl(hwnd, ctypes.byref(unknown))  # pyright: ignore[reportUnknownArgumentType]
    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
1133
1134
1135
1136
1137
1138
1139
1140
1141
1142
1143
1144
1145
1146
1147
1148
1149
1150
1151
1152
1153
1154
1155
1156
1157
1158
@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
1160
1161
1162
1163
1164
1165
1166
1167
1168
1169
1170
1171
1172
1173
@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
1175
1176
1177
1178
1179
1180
1181
1182
1183
1184
1185
1186
1187
1188
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
1190
1191
1192
1193
1194
1195
1196
1197
1198
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
1200
1201
1202
1203
1204
1205
1206
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
1208
1209
1210
1211
1212
1213
1214
1215
1216
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)

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
610
611
612
613
614
615
616
617
618
619
620
621
622
623
624
625
626
627
628
629
630
631
632
633
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
648
649
650
651
652
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
832
833
834
835
836
837
838
839
840
841
842
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._id: int = 0
    self._items: dict[int, MenuItem] = {}
    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
848
849
850
851
852
853
854
855
856
857
858
859
860
861
862
863
864
865
866
867
868
869
870
871
872
873
874
875
876
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.
    """
    self._id += 1
    user32.AppendMenuW(hmenu, flags, self._id, text)
    item = MenuItem(hmenu=hmenu, text=text, callback=callback, id=self._id, flags=flags, data=data)
    self._items[self._id] = item
    return item

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
878
879
880
881
882
883
884
885
886
887
888
889
890
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.
    """
    for item in menu_group:
        self._id += 1
        item._hmenu = hmenu  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
        item._id = self._id  # noqa: SLF001  # pyright: ignore[reportPrivateUsage]
        user32.AppendMenuW(hmenu, item.flags, self._id, item.text)
        self._items[self._id] = 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
892
893
894
895
896
897
898
899
def append_separator(self, hmenu: int) -> None:
    """Append a horizontal dividing line to a popup menu.

    Args:
        hmenu: The handle to a popup menu.
    """
    self._id += 1
    user32.AppendMenuW(hmenu, MenuFlag.SEPARATOR, self._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
901
902
903
904
905
906
907
908
909
910
911
912
913
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
756
757
758
759
760
761
762
763
764
765
766
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] = []

checked property writable ¤

checked

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

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
776
777
778
779
780
781
782
783
784
785
786
787
788
789
790
791
792
793
794
795
796
797
798
799
800
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=-1, text=text, callback=callback, id=-1, 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
802
803
804
def append_separator(self) -> None:
    """Append a horizontal dividing line to the group."""
    self._items.append(MenuItem(hmenu=-1, text=None, callback=None, id=-1, 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
658
659
660
661
662
663
664
665
666
667
668
669
670
671
672
673
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._hmenu: int = kwargs["hmenu"]
    self._id: int = kwargs["id"]
    self._text: str = kwargs["text"]
    self._callback: Callable[[MenuItem], None] | None = kwargs["callback"]
    self._flags: int = kwargs["flags"]
    self._checked: bool = False
    self._data: Any = kwargs["data"]

callback property ¤

callback

Callable | 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 property writable ¤

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