Skip to content

Commit

Permalink
Fixed documentation not displaying the actual HookEvent/ObjectId hex …
Browse files Browse the repository at this point in the history 
…values, or their documentation.
  • Loading branch information
@blep
blep committed Sep 6, 2023
1 parent 5145a04 commit 3ae7874
Show file tree
Hide file tree
Showing 2 changed files with 100 additions and 75 deletions.
8 changes: 8 additions & 0 deletions docs/conf.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -39,6 +39,14 @@
# ensure that __all__ is not ignored
autosummary_imported_members = True

autodoc_default_options = {
'exclude-members': 'FORCE_HEX_REPR', # Exclude NamedInt.FORCE_HEX_REPR
# TODO revist this, we want documented method to be in the doc
# 'special-members': '__init_subclass__, __eq__, __hash__',
}

autodoc_default_flags = ['members']

# -- Options for HTML output -------------------------------------------------
# https://www.sphinx-doc.org/en/master/usage/configuration.html#options-for-html-output

Expand Down
167 changes: 92 additions & 75 deletions win32_window_monitor/ids.py
View file
Original file line number Diff line number Diff line change
Expand Up @@ -13,13 +13,14 @@ class NamedInt(int):
See https://docs.python.org/3/reference/datamodel.html#customizing-class-creation for an
example of the logic used to convert integer constant to actual instance of the class.
"""
# Force str to output only the hex value. For documentation generation, so that enum are documented as:
# `SYSTEM_FOREGROUND = 0x0003` instead of `SYSTEM_FOREGROUND = HookEvent.SYSTEM_FOREGROUND`
FORCE_HEX_REPR = bool(os.environ.get('SPHINX_NAMED_INT_FORCE_HEX_REPR', False))
#: Force str to output only the hex value. For documentation generation, so that enum are documented as:
#: `SYSTEM_FOREGROUND = 0x0003` instead of `SYSTEM_FOREGROUND = HookEvent.SYSTEM_FOREGROUND`

_value2member_map_ = None

def __new__(cls, value):
"""Construct a enum value, setting its name if the int `value` is a known enum."""
if not isinstance(value, int):
raise ValueError(f'expected value to be a int, but was {value!r}')
named_int = cls._value2member_map_.get(value) if cls._value2member_map_ else None
Expand All @@ -30,15 +31,27 @@ def __new__(cls, value):

@property
def name(self):
"""Name of the enum value, or None for unknown int value.
For example `HookEvent.SYSTEM_FOREGROUND.name` returns 'SYSTEM_FOREGROUND'
"""
return self._name

@property
def value(self):
"""The integer value of the enum.
For example `HookEvent.SYSTEM_FOREGROUND.value` returns 0x0003
"""
return int(self)

@classmethod
def __init_subclass__(cls):
"""Maps the integer class field to actual instance of the class."""
"""Maps the subclass class attributes of type int to actual instance of the class.
This is the mechanism that transform the declaration `AIA_START = 0xA000` to `AIA_START = HookEvent(0xA000)`
and set the HookEvent instance name.
"""
cls._value2member_map_ = {}
for name, value in cls.__dict__.items():
if isinstance(value, int):
Expand All @@ -49,10 +62,12 @@ def __init_subclass__(cls):

@classmethod
def names(cls):
"""Returns an iterator over the list of the .name of each enum value."""
return (value.name for value in cls._value2member_map_.values())

@classmethod
def values(cls):
"""Returns an iterator over the list of all enums that have .name and .value property."""
return iter(cls._value2member_map_.values())

def __repr__(self):
Expand All @@ -71,9 +86,11 @@ def __str__(self):
return '0x%x' % int(self)

def __eq__(self, other):
"""Returns True if this enum int value == other."""
return int(self) == other

def __hash__(self):
"""Returns the hash of this enum int value."""
return super().__hash__()


Expand All @@ -88,217 +105,217 @@ class HookEvent(NamedInt):
Extends int to allow wrapping of any event id: HookEvent(0x1234), even if it is missing in the constant declared below.
"""

# Lowest possible event id.
#: Lowest possible event id.
MIN = 0x00000001
# highest possible event id.
#: highest possible event id.
MAX = 0x7FFFFFFF

# Start of the range for Accessibility Interoperability Alliance (AIA) WinEvent
#: Start of the range for Accessibility Interoperability Alliance (AIA) WinEvent
AIA_START = 0xA000
# End of the range for Accessibility Interoperability Alliance (AIA) WinEvent
#: End of the range for Accessibility Interoperability Alliance (AIA) WinEvent
AIA_END = 0xAFFF

# An object's KeyboardShortcut property changed.
#: An object's KeyboardShortcut property changed.
OBJECT_ACCELERATORCHANGE = 0x8012

# Sent when a window is cloaked. A cloaked window still exists but is invisible to the user.
#: Sent when a window is cloaked. A cloaked window still exists but is invisible to the user.
OBJECT_CLOAKED = 0x8017

# A window object's scrolling has ended.
#: A window object's scrolling has ended.
OBJECT_CONTENTSCROLLED = 0x8015

# An object has been created.
#: An object has been created.
OBJECT_CREATE = 0x8000

# An object's DefaultAction property has changed.
#: An object's DefaultAction property has changed.
OBJECT_DEFACTIONCHANGE = 0x8011

# An object's Description property has changed.
#: An object's Description property has changed.
OBJECT_DESCRIPTIONCHANGE = 0x800D

# An object has been destroyed.
#: An object has been destroyed.
OBJECT_DESTROY = 0x8001

# The user started to drag an element.
#: The user started to drag an element.
OBJECT_DRAGSTART = 0x8021

# The user has ended a drag operation before dropping the dragged element on a drop target.
#: The user has ended a drag operation before dropping the dragged element on a drop target.
OBJECT_DRAGCANCEL = 0x8022

# The user dropped an element on a drop target.
#: The user dropped an element on a drop target.
OBJECT_DRAGCOMPLETE = 0x8023

# The user dragged an element into a drop target's boundary.
#: The user dragged an element into a drop target's boundary.
OBJECT_DRAGENTER = 0x8024

# The user dragged an element out of a drop target's boundary.
#: The user dragged an element out of a drop target's boundary.
OBJECT_DRAGLEAVE = 0x8025

# The user dropped an element on a drop target.
#: The user dropped an element on a drop target.
OBJECT_DRAGDROPPED = 0x8026

# The highest object event value.
#: The highest object event value.
OBJECT_END = 0x80FF

# An object has received the keyboard focus.
#: An object has received the keyboard focus.
OBJECT_FOCUS = 0x8005

# An object's Help property has changed.
#: An object's Help property has changed.
OBJECT_HELPCHANGE = 0x8010

# An object is hidden.
#: An object is hidden.
OBJECT_HIDE = 0x8003

# A window that hosts other accessible objects has changed the hosted objects.
#: A window that hosts other accessible objects has changed the hosted objects.
OBJECT_HOSTEDOBJECTSINVALIDATED = 0x8020

# An IME window has become hidden.
#: An IME window has become hidden.
OBJECT_IME_HIDE = 0x8028

# An IME window has become visible.
#: An IME window has become visible.
OBJECT_IME_SHOW = 0x8027

# The size or position of an IME window has changed.
#: The size or position of an IME window has changed.
OBJECT_IME_CHANGE = 0x8029

# An object has been invoked; for example, the user has clicked a button.
#: An object has been invoked; for example, the user has clicked a button.
OBJECT_INVOKED = 0x8013

# An object that is part of a live region has changed.
#: An object that is part of a live region has changed.
OBJECT_LIVEREGIONCHANGED = 0x8019

# An object has changed location, shape, or size.
#: An object has changed location, shape, or size.
OBJECT_LOCATIONCHANGE = 0x800B

# An object's Name property has changed.
#: An object's Name property has changed.
OBJECT_NAMECHANGE = 0x800C

# An object has a new parent object.
#: An object has a new parent object.
OBJECT_PARENTCHANGE = 0x800F

# A container object has added, removed, or reordered its children.
#: A container object has added, removed, or reordered its children.
OBJECT_REORDER = 0x8004

# The selection within a container object has changed.
#: The selection within a container object has changed.
OBJECT_SELECTION = 0x8006

# A child within a container object has been added to an existing selection.
#: A child within a container object has been added to an existing selection.
OBJECT_SELECTIONADD = 0x8007

# An item within a container object has been removed from the selection.
#: An item within a container object has been removed from the selection.
OBJECT_SELECTIONREMOVE = 0x8008

# Numerous selection changes have occurred within a container object.
#: Numerous selection changes have occurred within a container object.
OBJECT_SELECTIONWITHIN = 0x8009

# A hidden object is shown.
#: A hidden object is shown.
OBJECT_SHOW = 0x8002

# An object's state has changed.
#: An object's state has changed.
OBJECT_STATECHANGE = 0x800A

# The conversion target within an IME composition has changed.
#: The conversion target within an IME composition has changed.
OBJECT_TEXTEDIT_CONVERSIONTARGETCHANGED = 0x8030

# An object's text selection has changed.
#: An object's text selection has changed.
OBJECT_TEXTSELECTIONCHANGED = 0x8014

# Sent when a window is uncloaked.
#: Sent when a window is uncloaked.
OBJECT_UNCLOAKED = 0x8018

# An object's Value property has changed.
#: An object's Value property has changed.
OBJECT_VALUECHANGE = 0x800E

# Range of event constant values reserved for OEMs.
#: Range of event constant values reserved for OEMs.
OEM_DEFINED_START = 0x0101
OEM_DEFINED_END = 0x01FF

# An alert has been generated.
#: An alert has been generated.
SYSTEM_ALERT = 0x0002

# A preview rectangle is being displayed.
#: A preview rectangle is being displayed.
SYSTEM_ARRANGMENTPREVIEW = 0x8016

# A window has lost mouse capture.
#: A window has lost mouse capture.
SYSTEM_CAPTUREEND = 0x0009

# A window has received mouse capture.
#: A window has received mouse capture.
SYSTEM_CAPTURESTART = 0x0008

# A window has exited context-sensitive Help mode.
#: A window has exited context-sensitive Help mode.
SYSTEM_CONTEXTHELPEND = 0x000D

# A window has entered context-sensitive Help mode.
#: A window has entered context-sensitive Help mode.
SYSTEM_CONTEXTHELPSTART = 0x000C

# The active desktop has been switched.
#: The active desktop has been switched.
SYSTEM_DESKTOPSWITCH = 0x0020

# A dialog box has been closed.
#: A dialog box has been closed.
SYSTEM_DIALOGEND = 0x0011

# A dialog box has been displayed.
#: A dialog box has been displayed.
SYSTEM_DIALOGSTART = 0x0010

# An application is about to exit drag-and-drop mode.
#: An application is about to exit drag-and-drop mode.
SYSTEM_DRAGDROPEND = 0x000F

# An application is about to enter drag-and-drop mode.
#: An application is about to enter drag-and-drop mode.
SYSTEM_DRAGDROPSTART = 0x000E

# The highest system event value.
#: The highest system event value.
SYSTEM_END = 0x00FF

# The foreground window has changed.
#: The foreground window has changed.
SYSTEM_FOREGROUND = 0x0003

# A pop-up menu has been closed.
#: A pop-up menu has been closed.
SYSTEM_MENUPOPUPEND = 0x0007

# A pop-up menu has been displayed.
#: A pop-up menu has been displayed.
SYSTEM_MENUPOPUPSTART = 0x0006

# A menu from the menu bar has been closed.
#: A menu from the menu bar has been closed.
SYSTEM_MENUEND = 0x0005

# A menu item on the menu bar has been selected.
#: A menu item on the menu bar has been selected.
SYSTEM_MENUSTART = 0x0004

# A window object is about to be restored.
#: A window object is about to be restored.
SYSTEM_MINIMIZEEND = 0x0017

# A window object is about to be minimized.
#: A window object is about to be minimized.
SYSTEM_MINIMIZESTART = 0x0016

# The movement or resizing of a window has finished.
#: The movement or resizing of a window has finished.
SYSTEM_MOVESIZEEND = 0x000B

# A window is being moved or resized.
#: A window is being moved or resized.
SYSTEM_MOVESIZESTART = 0x000A

# Scrolling has ended on a scroll bar.
#: Scrolling has ended on a scroll bar.
SYSTEM_SCROLLINGEND = 0x0013

# Scrolling has started on a scroll bar.
#: Scrolling has started on a scroll bar.
SYSTEM_SCROLLINGSTART = 0x0012

# A sound has been played.
#: A sound has been played.
SYSTEM_SOUND = 0x0001

# The user has released ALT+TAB.
#: The user has released ALT+TAB.
SYSTEM_SWITCHEND = 0x0015

# The user has pressed ALT+TAB, which activates the switch window.
#: The user has pressed ALT+TAB, which activates the switch window.
SYSTEM_SWITCHSTART = 0x0014

# Start of range reserved for UI Automation event identifiers.
#: Start of range reserved for UI Automation event identifiers.
UIA_EVENTID_START = 0x4E00
# End of range reserved for UI Automation event identifiers.
#: End of range reserved for UI Automation event identifiers.
UIA_EVENTID_END = 0x4EFF

# Start of range reserved for UI Automation property-changed event identifiers.
#: Start of range reserved for UI Automation property-changed event identifiers.
UIA_PROPID_START = 0x7500
# End of range reserved for UI Automation property-changed event identifiers.
#: End of range reserved for UI Automation property-changed event identifiers.
UIA_PROPID_END = 0x75FF


Expand Down

0 comments on commit 3ae7874

Please sign in to comment.