controlTypes package

class controlTypes.IsCurrent(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringStrEnum

Values to use within NVDA to denote ‘current’ values. These describe if an item is the current item within a particular kind of selection. EG aria-current

NO = 'false'
YES = 'true'
PAGE = 'page'
STEP = 'step'
LOCATION = 'location'
DATE = 'date'
TIME = 'time'
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

property displayString

@return: The translated UI display string that should be used for this value of the enum.

class controlTypes.OutputReason(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Specify the reason that a given piece of output was generated.

FOCUS = 1

An object to be reported due to a focus change or similar.

FOCUSENTERED = 2

An ancestor of the focus object to be reported due to a focus change or similar.

MOUSE = 3

An item under the mouse.

QUERY = 4

A response to a user query.

CHANGE = 5

Reporting a change to an object.

MESSAGE = 6

A generic, screen reader specific message.

SAYALL = 7

Text reported as part of a say all.

CARET = 8

Content reported due to caret movement or similar.

ONLYCACHE = 9

No output, but any state should be cached as if output had occurred.

QUICKNAV = 10
controlTypes.processAndLabelStates(role: Role, states: Set[State], reason: OutputReason, positiveStates: Set[State] | None = None, negativeStates: Set[State] | None = None, positiveStateLabelDict: Dict[State, str] = {}, negativeStateLabelDict: Dict[State, str] = {}) List[str]

Processes the states for an object and returns the appropriate state labels for both positive and negative states. @param role: The role of the object to process states for (e.g. C{Role.CHECKBOX}). @param states: The raw states for an object to process. @param reason: The reason to process the states (e.g. C{OutputReason.FOCUS}). @param positiveStates: Used for C{OutputReason.CHANGE}, specifies states changed from negative to positive. @param negativeStates: Used for C{OutputReason.CHANGE}, specifies states changed from positive to negative. @param positiveStateLabelDict: Dictionary containing state identifiers as keys and associated positive labels as their values. @param negativeStateLabelDict: Dictionary containing state identifiers as keys and associated negative labels as their values. @return: The labels of the relevant positive and negative states.

class controlTypes.Role(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringIntEnum

Add-on authors are recommended not to depend on values and use a Role directly. From a string, this can be done as controlTypes.Role[nameOfRole] e.g. Role["CHECKBOX"]. Although unlikely to change, if names/values changing represents a significant risk for your add-on, then consider decoupling, and maintain an internal mapping of Role to add-on internal roles.

As add-on authors may still rely on the values, new members of Role should continue the previous pattern of incrementing. Using enum.auto may backfill role values and should be avoided. Refer to test_controlTypes.TestBackCompat.test_rolesValues for compatibility requirements.

Some behaviour of treating roles as their integer values is already unsupported. ``` # Former constants ROLE_GRAPHIC: int = controlTypes.Role.GRAPHIC.value ROLE_GRAPHIC is 16 True

# New aliases ROLE_GRAPHIC: controlTypes.Role = controlTypes.Role.GRAPHIC ROLE_GRAPHIC is 16 False ```

property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

UNKNOWN = 0
WINDOW = 1
TITLEBAR = 2
PANE = 3
DIALOG = 4
CHECKBOX = 5
RADIOBUTTON = 6
STATICTEXT = 7
EDITABLETEXT = 8
BUTTON = 9
MENUBAR = 10
MENUITEM = 11
POPUPMENU = 12
COMBOBOX = 13
LIST = 14
LISTITEM = 15
GRAPHIC = 16
HELPBALLOON = 17
TOOLTIP = 18
TREEVIEW = 20
TREEVIEWITEM = 21
TAB = 22
TABCONTROL = 23
SLIDER = 24
PROGRESSBAR = 25
SCROLLBAR = 26
STATUSBAR = 27
TABLE = 28
TABLECELL = 29
TABLECOLUMN = 30
TABLEROW = 31
TABLECOLUMNHEADER = 32
TABLEROWHEADER = 33
FRAME = 34
TOOLBAR = 35
DROPDOWNBUTTON = 36
CLOCK = 37
SEPARATOR = 38
FORM = 39
HEADING = 40
HEADING1 = 41
HEADING2 = 42
HEADING3 = 43
HEADING4 = 44
HEADING5 = 45
HEADING6 = 46
PARAGRAPH = 47
BLOCKQUOTE = 48
TABLEHEADER = 49
TABLEBODY = 50
TABLEFOOTER = 51
DOCUMENT = 52
ANIMATION = 53
APPLICATION = 54
BOX = 55
GROUPING = 56
PROPERTYPAGE = 57
CANVAS = 58
CAPTION = 59
CHECKMENUITEM = 60
DATEEDITOR = 61
ICON = 62
DIRECTORYPANE = 63
EMBEDDEDOBJECT = 64
ENDNOTE = 65
FOOTER = 66
FOOTNOTE = 67
GLASSPANE = 69
HEADER = 70
IMAGEMAP = 71
INPUTWINDOW = 72
LABEL = 73
NOTE = 74
PAGE = 75
RADIOMENUITEM = 76
LAYEREDPANE = 77
REDUNDANTOBJECT = 78
ROOTPANE = 79
EDITBAR = 80
TERMINAL = 82
RICHEDIT = 83
RULER = 84
SCROLLPANE = 85
SECTION = 86
SHAPE = 87
SPLITPANE = 88
VIEWPORT = 89
TEAROFFMENU = 90
TEXTFRAME = 91
TOGGLEBUTTON = 92
BORDER = 93
CARET = 94
CHARACTER = 95
CHART = 96
CURSOR = 97
DIAGRAM = 98
DIAL = 99
DROPLIST = 100
SPLITBUTTON = 101
MENUBUTTON = 102
DROPDOWNBUTTONGRID = 103
MATH = 104
GRIP = 105
HOTKEYFIELD = 106
INDICATOR = 107
SPINBUTTON = 108
SOUND = 109
WHITESPACE = 110
TREEVIEWBUTTON = 111
IPADDRESS = 112
DESKTOPICON = 113
INTERNALFRAME = 115
DESKTOPPANE = 116
OPTIONPANE = 117
COLORCHOOSER = 118
FILECHOOSER = 119
FILLER = 120
MENU = 121
PANEL = 122
PASSWORDEDIT = 123
FONTCHOOSER = 124
LINE = 125
FONTNAME = 126
FONTSIZE = 127
BOLD = 128
ITALIC = 129
UNDERLINE = 130
FGCOLOR = 131
BGCOLOR = 132
SUPERSCRIPT = 133
SUBSCRIPT = 134
STYLE = 135
INDENT = 136
ALIGNMENT = 137
ALERT = 138
DATAGRID = 139
DATAITEM = 140
HEADERITEM = 141
THUMB = 142
CALENDAR = 143
VIDEO = 144
AUDIO = 145
CHARTELEMENT = 146
DELETED_CONTENT = 147
INSERTED_CONTENT = 148
LANDMARK = 149
ARTICLE = 150
REGION = 151
FIGURE = 152
MARKED_CONTENT = 153
BUSY_INDICATOR = 154
COMMENT = 155
SUGGESTION = 156
DEFINITION = 157
SWITCH = 158
class controlTypes.State(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringIntEnum

Add-on authors are recommended not to depend on values and use a State directly. From a string, this can be done as controlTypes.State[nameOfState] e.g. State["CHECKED"]. Although unlikely to change, if names/values changing represents a significant risk for your add-on, then consider decoupling, and maintain an internal mapping of State to add-on internal states.

As add-on authors may still rely on the values, new members of State should continue the pattern of incrementing.

property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

property negativeDisplayString: str

@return: The translated UI display string, used when referring to this value of the enum in the negative.

UNAVAILABLE = 1
FOCUSED = 2
SELECTED = 4
BUSY = 8
PRESSED = 16
CHECKED = 32
HALFCHECKED = 64
READONLY = 128
EXPANDED = 256
COLLAPSED = 512
INVISIBLE = 1024
VISITED = 2048
LINKED = 4096
HASPOPUP = 8192
PROTECTED = 16384
REQUIRED = 32768
DEFUNCT = 65536
INVALID_ENTRY = 131072
MODAL = 262144
AUTOCOMPLETE = 524288
MULTILINE = 1048576
ICONIFIED = 2097152
OFFSCREEN = 4194304
SELECTABLE = 8388608
FOCUSABLE = 16777216
CLICKABLE = 33554432
EDITABLE = 67108864
CHECKABLE = 134217728
DRAGGABLE = 268435456
DRAGGING = 536870912
DROPTARGET = 1073741824
SORTED = 2147483648
SORTED_ASCENDING = 4294967296
SORTED_DESCENDING = 8589934592
HASLONGDESC = 17179869184
PINNED = 34359738368
HASFORMULA = 68719476736
HASCOMMENT = 137438953472
OBSCURED = 274877906944
CROPPED = 549755813888
OVERFLOWING = 1099511627776
UNLOCKED = 2199023255552
HAS_ARIA_DETAILS = 4398046511104
HASNOTE = 8796093022208
INDETERMINATE = 17592186044416
HALF_PRESSED = 35184372088832
ON = 70368744177664
HASPOPUP_DIALOG = 140737488355328
HASPOPUP_GRID = 281474976710656
HASPOPUP_LIST = 562949953421312
HASPOPUP_TREE = 1125899906842624
class controlTypes.DescriptionFrom(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Values to use within NVDA to denote possible values for DescriptionFrom. These are used to determine how the source of the ‘description’ property if an NVDAObject.

UNKNOWN = 1
ARIA_DESCRIPTION = 'aria-description'
ARIA_DESCRIBED_BY = 'aria-describedby'
RUBY_ANNOTATION = 'ruby-annotation'
SUMMARY = 'summary'
TABLE_CAPTION = 'table-caption'
TOOLTIP = 'tooltip'
BUTTON_LABEL = 'button-label'
class controlTypes.TextAlign(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringStrEnum

Values to use for ‘text-align’ NVDA format field. These describe the horizontal paragraph position.

UNDEFINED = 'undefined'
LEFT = 'left'
CENTER = 'center'
RIGHT = 'right'
JUSTIFY = 'justify'
DISTRIBUTE = 'distribute'
CENTER_ACROSS_SELECTION = 'center-across-selection'
GENERAL = 'general'
FILL = 'fill'
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

class controlTypes.TextPosition(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringStrEnum

Values to use for ‘text-position’ NVDA format field. These describe the vertical position of the text with respect to the base line.

UNDEFINED = 'undefined'
BASELINE = 'baseline'
SUBSCRIPT = 'sub'
SUPERSCRIPT = 'super'
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

controlTypes.transformRoleStates(role: Role, states: Set[State]) Tuple[Role, Set[State]]

Map NVDA Role-State combinations to adjusted NVDA Role-State combinations. Some combinations of roles and states may be better represented with some alternative combination. As an example: Role.PROGRESSBAR with State.INDETERMINATE should be represented by only the Role.BUSY_INDICATOR, with no State.INDETERMINATE, or State.HALFCHECKED. @param role: NVDA Role to consider @param states: NVDA States to consider @return: A tuple with the new Role and modified States set.

class controlTypes.VerticalTextAlign(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringStrEnum

Values to use for ‘vertical-align’ NVDA format field. These describe the vertical text position, e.g. in a table cell.

UNDEFINED = 'undefined'
TOP = 'top'
CENTER = 'center'
BOTTOM = 'bottom'
JUSTIFY = 'justify'
DISTRIBUTE = 'distributed'
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

controlTypes.processNegativeStates(role: Role, states: Set[State], reason: OutputReason, negativeStates: Set[State] | None = None) Set[State]

Processes the states for an object and returns the negative states to output for a specified reason. For example, if C{State.CHECKED} is in the returned states, it means that the processed object is not checked. @param role: The role of the object to process states for (e.g. C{Role.CHECKBOX}). @param states: The raw states for an object to process. @param reason: The reason to process the states (e.g. C{OutputReason.FOCUS)}. @param negativeStates: Used for C{OutputReason.CHANGE}, specifies states changed from positive to negative. @return: The processed negative states.

controlTypes.processPositiveStates(role: Role, states: Set[State], reason: OutputReason, positiveStates: Set[State] | None = None) Set[State]

Processes the states for an object and returns the positive states to output for a specified reason. For example, if C{State.CHECKED} is in the returned states, it means that the processed object is checked. @param role: The role of the object to process states for (e.g. C{Role.CHECKBOX}). @param states: The raw states for an object to process. @param reason: The reason to process the states (e.g. C{OutputReason.FOCUS}). @param positiveStates: Used for C{OutputReason.CHANGE}, specifies states changed from negative to positive. @return: The processed positive states.

Submodules

controlTypes.deprecatedAliases module

This module contains aliases for symbols used before controlTypes was refactored. These values should not be extended, they are for backwards compatibility with add-ons only. It is recommended that add-ons convert to use the Role, and State symbols directly rather than continuing to rely on the aliases (I.E. ‘ROLE_*’ and ‘STATE_*’ symbols) this module provides. Using controlTypes.Role and controlTypes.State will make your add-on code consistent with NVDA core.

controlTypes.deprecatedAliases.roleLabels = {Role.UNKNOWN: 'unknown', Role.WINDOW: 'window', Role.TITLEBAR: 'title bar', Role.PANE: 'pane', Role.DIALOG: 'dialog', Role.CHECKBOX: 'check box', Role.RADIOBUTTON: 'radio button', Role.STATICTEXT: 'text', Role.EDITABLETEXT: 'edit', Role.BUTTON: 'button', Role.MENUBAR: 'menu bar', Role.MENUITEM: 'menu item', Role.POPUPMENU: 'menu', Role.COMBOBOX: 'combo box', Role.LIST: 'list', Role.LISTITEM: 'list item', Role.GRAPHIC: 'graphic', Role.HELPBALLOON: 'help balloon', Role.TOOLTIP: 'tool tip', Role.LINK: 'link', Role.TREEVIEW: 'tree view', Role.TREEVIEWITEM: 'tree view item', Role.TAB: 'tab', Role.TABCONTROL: 'tab control', Role.SLIDER: 'slider', Role.PROGRESSBAR: 'progress bar', Role.SCROLLBAR: 'scroll bar', Role.STATUSBAR: 'status bar', Role.TABLE: 'table', Role.TABLECELL: 'cell', Role.TABLECOLUMN: 'column', Role.TABLEROW: 'row', Role.TABLECOLUMNHEADER: 'column header', Role.TABLEROWHEADER: 'row header', Role.FRAME: 'frame', Role.TOOLBAR: 'tool bar', Role.DROPDOWNBUTTON: 'drop down button', Role.CLOCK: 'clock', Role.SEPARATOR: 'separator', Role.FORM: 'form', Role.HEADING: 'heading', Role.HEADING1: 'heading 1', Role.HEADING2: 'heading 2', Role.HEADING3: 'heading 3', Role.HEADING4: 'heading 4', Role.HEADING5: 'heading 5', Role.HEADING6: 'heading 6', Role.PARAGRAPH: 'paragraph', Role.BLOCKQUOTE: 'block quote', Role.TABLEHEADER: 'table header', Role.TABLEBODY: 'table body', Role.TABLEFOOTER: 'table footer', Role.DOCUMENT: 'document', Role.ANIMATION: 'animation', Role.APPLICATION: 'application', Role.BOX: 'box', Role.GROUPING: 'grouping', Role.PROPERTYPAGE: 'property page', Role.CANVAS: 'canvas', Role.CAPTION: 'caption', Role.CHECKMENUITEM: 'check menu item', Role.DATEEDITOR: 'date edit', Role.ICON: 'icon', Role.DIRECTORYPANE: 'directory pane', Role.EMBEDDEDOBJECT: 'embedded object', Role.ENDNOTE: 'end note', Role.FOOTER: 'footer', Role.FOOTNOTE: 'foot note', Role.GLASSPANE: 'glass pane', Role.HEADER: 'header', Role.IMAGEMAP: 'image map', Role.INPUTWINDOW: 'input window', Role.LABEL: 'label', Role.NOTE: 'note', Role.PAGE: 'page', Role.RADIOMENUITEM: 'radio menu item', Role.LAYEREDPANE: 'layered pane', Role.REDUNDANTOBJECT: 'redundant object', Role.ROOTPANE: 'root pane', Role.EDITBAR: 'edit bar', Role.TERMINAL: 'terminal', Role.RICHEDIT: 'rich edit', Role.RULER: 'ruler', Role.SCROLLPANE: 'scroll pane', Role.SECTION: 'section', Role.SHAPE: 'shape', Role.SPLITPANE: 'split pane', Role.VIEWPORT: 'view port', Role.TEAROFFMENU: 'tear off menu', Role.TEXTFRAME: 'text frame', Role.TOGGLEBUTTON: 'toggle button', Role.BORDER: 'border', Role.CARET: 'caret', Role.CHARACTER: 'character', Role.CHART: 'chart', Role.CURSOR: 'cursor', Role.DIAGRAM: 'diagram', Role.DIAL: 'dial', Role.DROPLIST: 'drop list', Role.SPLITBUTTON: 'split button', Role.MENUBUTTON: 'menu button', Role.DROPDOWNBUTTONGRID: 'drop down button grid', Role.MATH: 'math', Role.GRIP: 'grip', Role.HOTKEYFIELD: 'hot key field', Role.INDICATOR: 'indicator', Role.SPINBUTTON: 'spin button', Role.SOUND: 'sound', Role.WHITESPACE: 'white space', Role.TREEVIEWBUTTON: 'tree view button', Role.IPADDRESS: 'IP address', Role.DESKTOPICON: 'desktop icon', Role.INTERNALFRAME: 'frame', Role.DESKTOPPANE: 'desktop pane', Role.OPTIONPANE: 'option pane', Role.COLORCHOOSER: 'color chooser', Role.FILECHOOSER: 'file chooser', Role.FILLER: 'filler', Role.MENU: 'menu', Role.PANEL: 'panel', Role.PASSWORDEDIT: 'password edit', Role.FONTCHOOSER: 'font chooser', Role.LINE: 'line', Role.FONTNAME: 'font name', Role.FONTSIZE: 'font size', Role.BOLD: 'bold', Role.ITALIC: 'italic', Role.UNDERLINE: 'underline', Role.FGCOLOR: 'foreground color', Role.BGCOLOR: 'background color', Role.SUPERSCRIPT: 'superscript', Role.SUBSCRIPT: 'subscript', Role.STYLE: 'style', Role.INDENT: 'indent', Role.ALIGNMENT: 'alignment', Role.ALERT: 'alert', Role.DATAGRID: 'data grid', Role.DATAITEM: 'data item', Role.HEADERITEM: 'header item', Role.THUMB: 'thumb control', Role.CALENDAR: 'calendar', Role.VIDEO: 'video', Role.AUDIO: 'audio', Role.CHARTELEMENT: 'chart element', Role.DELETED_CONTENT: 'deleted', Role.INSERTED_CONTENT: 'inserted', Role.LANDMARK: 'landmark', Role.ARTICLE: 'article', Role.REGION: 'region', Role.FIGURE: 'figure', Role.MARKED_CONTENT: 'highlighted', Role.BUSY_INDICATOR: 'busy indicator', Role.COMMENT: 'comment', Role.SUGGESTION: 'suggestion', Role.DEFINITION: 'definition', Role.SWITCH: 'switch'}

Deprecated. Recommendation: prefer to use controlTypes.Role.displayString instead

controlTypes.deprecatedAliases.stateLabels = {State.UNAVAILABLE: 'unavailable', State.FOCUSED: 'focused', State.SELECTED: 'selected', State.BUSY: 'busy', State.PRESSED: 'pressed', State.CHECKED: 'checked', State.HALFCHECKED: 'half checked', State.READONLY: 'read only', State.EXPANDED: 'expanded', State.COLLAPSED: 'collapsed', State.INVISIBLE: 'invisible', State.VISITED: 'visited', State.LINKED: 'linked', State.HASPOPUP: 'subMenu', State.PROTECTED: 'protected', State.REQUIRED: 'required', State.DEFUNCT: 'defunct', State.INVALID_ENTRY: 'invalid entry', State.MODAL: 'modal', State.AUTOCOMPLETE: 'has auto complete', State.MULTILINE: 'multi line', State.ICONIFIED: 'iconified', State.OFFSCREEN: 'off screen', State.SELECTABLE: 'selectable', State.FOCUSABLE: 'focusable', State.CLICKABLE: 'clickable', State.EDITABLE: 'editable', State.CHECKABLE: 'checkable', State.DRAGGABLE: 'draggable', State.DRAGGING: 'dragging', State.DROPTARGET: 'drop target', State.SORTED: 'sorted', State.SORTED_ASCENDING: 'sorted ascending', State.SORTED_DESCENDING: 'sorted descending', State.HASLONGDESC: 'has long description', State.PINNED: 'pinned', State.HASFORMULA: 'has formula', State.HASCOMMENT: 'has comment', State.OBSCURED: 'obscured', State.CROPPED: 'cropped', State.OVERFLOWING: 'overflowing', State.UNLOCKED: 'unlocked', State.HASNOTE: 'has note', State.HALF_PRESSED: 'half pressed', State.ON: 'on', State.HASPOPUP_DIALOG: 'opens dialog', State.HASPOPUP_GRID: 'opens grid', State.HASPOPUP_LIST: 'opens list', State.HASPOPUP_TREE: 'opens tree'}

Deprecated. Recommendation: prefer to use controlTypes.State.displayString instead

controlTypes.deprecatedAliases.negativeStateLabels = {State.SELECTED: 'not selected', State.PRESSED: 'not pressed', State.CHECKED: 'not checked', State.DROPTARGET: 'done dragging', State.ON: 'off'}

Deprecated. Recommendation: prefer to use controlTypes.State.negativeDisplayString instead

controlTypes.deprecatedAliases.processNegativeStates(role: Role, states: Set[State], reason: OutputReason, negativeStates: Set[State] | None = None) Set[State]

Deprecated. Recommendation: prefer to use controlTypes.processAndLabelStates instead

controlTypes.deprecatedAliases.processPositiveStates(role: Role, states: Set[State], reason: OutputReason, positiveStates: Set[State] | None = None) Set[State]

Deprecated. Recommendation: prefer to use controlTypes.processAndLabelStates instead

controlTypes.descriptionFrom module

class controlTypes.descriptionFrom.DescriptionFrom(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Values to use within NVDA to denote possible values for DescriptionFrom. These are used to determine how the source of the ‘description’ property if an NVDAObject.

UNKNOWN = 1
ARIA_DESCRIPTION = 'aria-description'
ARIA_DESCRIBED_BY = 'aria-describedby'
RUBY_ANNOTATION = 'ruby-annotation'
SUMMARY = 'summary'
TABLE_CAPTION = 'table-caption'
TOOLTIP = 'tooltip'
BUTTON_LABEL = 'button-label'

controlTypes.formatFields module

class controlTypes.formatFields.TextPosition(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringStrEnum

Values to use for ‘text-position’ NVDA format field. These describe the vertical position of the text with respect to the base line.

UNDEFINED = 'undefined'
BASELINE = 'baseline'
SUBSCRIPT = 'sub'
SUPERSCRIPT = 'super'
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

controlTypes.formatFields._textPositionLabels: Dict[TextPosition, str] = {TextPosition.BASELINE: 'baseline', TextPosition.SUBSCRIPT: 'subscript', TextPosition.SUPERSCRIPT: 'superscript', TextPosition.UNDEFINED: ''}

Text to use for ‘text-position’ format field values. These describe the vertical position of the formatted text with respect to the base line.

class controlTypes.formatFields.FontSize

Bases: object

_unitToTranslatableString: Dict[str, str] = {'%': '%s%%', 'em': '%s em', 'ex': '%s ex', 'pt': '%s pt', 'px': '%s px', 'rem': '%s rem'}
_keywordToTranslatableString: Dict[str, str] = {'large': 'large', 'larger': 'larger', 'medium': 'medium', 'small': 'small', 'smaller': 'smaller', 'x-large': 'x-large', 'x-small': 'x-small', 'xx-large': 'xx-large', 'xx-small': 'xx-small', 'xxx-large': 'xxx-large'}
_measurementRe = re.compile('([0-9\\.]+)(px|em|ex|rem|pt|%)')
static translateFromAttribute(fontSize: str) str

@param fontSize: Browsers provide the value of the font-size attribute directly, either as a measurement or as keywords. These aren’t translated. https://developer.mozilla.org/en-US/docs/Web/CSS/font-size#values

@return: a translated font size string.

class controlTypes.formatFields.TextAlign(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringStrEnum

Values to use for ‘text-align’ NVDA format field. These describe the horizontal paragraph position.

UNDEFINED = 'undefined'
LEFT = 'left'
CENTER = 'center'
RIGHT = 'right'
JUSTIFY = 'justify'
DISTRIBUTE = 'distribute'
CENTER_ACROSS_SELECTION = 'center-across-selection'
GENERAL = 'general'
FILL = 'fill'
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

controlTypes.formatFields._textAlignLabels: Dict[TextAlign, str] = {TextAlign.CENTER: 'align center', TextAlign.CENTER_ACROSS_SELECTION: 'align centered across selection', TextAlign.DISTRIBUTE: 'align distributed', TextAlign.FILL: 'align fill', TextAlign.GENERAL: 'align general', TextAlign.JUSTIFY: 'align justify', TextAlign.LEFT: 'align left', TextAlign.RIGHT: 'align right', TextAlign.UNDEFINED: ''}

Text to use for ‘text-align format field values. These describe the horizontal position of a paragraph or a cell’s content.

class controlTypes.formatFields.VerticalTextAlign(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringStrEnum

Values to use for ‘vertical-align’ NVDA format field. These describe the vertical text position, e.g. in a table cell.

UNDEFINED = 'undefined'
TOP = 'top'
CENTER = 'center'
BOTTOM = 'bottom'
JUSTIFY = 'justify'
DISTRIBUTE = 'distributed'
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

controlTypes.formatFields._verticalTextAlignLabels: Dict[VerticalTextAlign, str] = {VerticalTextAlign.BOTTOM: 'vertical align bottom', VerticalTextAlign.CENTER: 'vertical align middle', VerticalTextAlign.DISTRIBUTE: 'vertical align distributed', VerticalTextAlign.JUSTIFY: 'vertical align justified', VerticalTextAlign.TOP: 'vertical align top', VerticalTextAlign.UNDEFINED: ''}

Text to use for ‘vertical-align’ format field values. These describe the vertical position of a cell’s content.

controlTypes.isCurrent module

class controlTypes.isCurrent.IsCurrent(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringStrEnum

Values to use within NVDA to denote ‘current’ values. These describe if an item is the current item within a particular kind of selection. EG aria-current

NO = 'false'
YES = 'true'
PAGE = 'page'
STEP = 'step'
LOCATION = 'location'
DATE = 'date'
TIME = 'time'
property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

property displayString

@return: The translated UI display string that should be used for this value of the enum.

controlTypes.isCurrent._isCurrentLabels: Dict[IsCurrent, str] = {IsCurrent.DATE: 'current date', IsCurrent.NO: '', IsCurrent.LOCATION: 'current location', IsCurrent.PAGE: 'current page', IsCurrent.STEP: 'current step', IsCurrent.TIME: 'current time', IsCurrent.YES: 'current'}

Text to use for ‘current’ values. These describe if an item is the current item within a particular kind of selection. EG aria-current

controlTypes.outputReason module

class controlTypes.outputReason.OutputReason(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: Enum

Specify the reason that a given piece of output was generated.

FOCUS = 1

An object to be reported due to a focus change or similar.

FOCUSENTERED = 2

An ancestor of the focus object to be reported due to a focus change or similar.

MOUSE = 3

An item under the mouse.

QUERY = 4

A response to a user query.

CHANGE = 5

Reporting a change to an object.

MESSAGE = 6

A generic, screen reader specific message.

SAYALL = 7

Text reported as part of a say all.

CARET = 8

Content reported due to caret movement or similar.

ONLYCACHE = 9

No output, but any state should be cached as if output had occurred.

QUICKNAV = 10

controlTypes.processAndLabelStates module

controlTypes.processAndLabelStates._processPositiveStates(role: Role, states: Set[State], reason: OutputReason, positiveStates: Set[State] | None = None) Set[State]

Processes the states for an object and returns the positive states to output for a specified reason. For example, if C{State.CHECKED} is in the returned states, it means that the processed object is checked. @param role: The role of the object to process states for (e.g. C{Role.CHECKBOX}). @param states: The raw states for an object to process. @param reason: The reason to process the states (e.g. C{OutputReason.FOCUS}). @param positiveStates: Used for C{OutputReason.CHANGE}, specifies states changed from negative to positive. @return: The processed positive states.

controlTypes.processAndLabelStates._processNegativeStates(role: Role, states: Set[State], reason: OutputReason, negativeStates: Set[State] | None = None) Set[State]

Processes the states for an object and returns the negative states to output for a specified reason. For example, if C{State.CHECKED} is in the returned states, it means that the processed object is not checked. @param role: The role of the object to process states for (e.g. C{Role.CHECKBOX}). @param states: The raw states for an object to process. @param reason: The reason to process the states (e.g. C{OutputReason.FOCUS)}. @param negativeStates: Used for C{OutputReason.CHANGE}, specifies states changed from positive to negative. @return: The processed negative states.

controlTypes.processAndLabelStates.processAndLabelStates(role: Role, states: Set[State], reason: OutputReason, positiveStates: Set[State] | None = None, negativeStates: Set[State] | None = None, positiveStateLabelDict: Dict[State, str] = {}, negativeStateLabelDict: Dict[State, str] = {}) List[str]

Processes the states for an object and returns the appropriate state labels for both positive and negative states. @param role: The role of the object to process states for (e.g. C{Role.CHECKBOX}). @param states: The raw states for an object to process. @param reason: The reason to process the states (e.g. C{OutputReason.FOCUS}). @param positiveStates: Used for C{OutputReason.CHANGE}, specifies states changed from negative to positive. @param negativeStates: Used for C{OutputReason.CHANGE}, specifies states changed from positive to negative. @param positiveStateLabelDict: Dictionary containing state identifiers as keys and associated positive labels as their values. @param negativeStateLabelDict: Dictionary containing state identifiers as keys and associated negative labels as their values. @return: The labels of the relevant positive and negative states.

controlTypes.role module

class controlTypes.role.Role(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringIntEnum

Add-on authors are recommended not to depend on values and use a Role directly. From a string, this can be done as controlTypes.Role[nameOfRole] e.g. Role["CHECKBOX"]. Although unlikely to change, if names/values changing represents a significant risk for your add-on, then consider decoupling, and maintain an internal mapping of Role to add-on internal roles.

As add-on authors may still rely on the values, new members of Role should continue the previous pattern of incrementing. Using enum.auto may backfill role values and should be avoided. Refer to test_controlTypes.TestBackCompat.test_rolesValues for compatibility requirements.

Some behaviour of treating roles as their integer values is already unsupported. ``` # Former constants ROLE_GRAPHIC: int = controlTypes.Role.GRAPHIC.value ROLE_GRAPHIC is 16 True

# New aliases ROLE_GRAPHIC: controlTypes.Role = controlTypes.Role.GRAPHIC ROLE_GRAPHIC is 16 False ```

property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

UNKNOWN = 0
WINDOW = 1
TITLEBAR = 2
PANE = 3
DIALOG = 4
CHECKBOX = 5
RADIOBUTTON = 6
STATICTEXT = 7
EDITABLETEXT = 8
BUTTON = 9
MENUBAR = 10
MENUITEM = 11
POPUPMENU = 12
COMBOBOX = 13
LIST = 14
LISTITEM = 15
GRAPHIC = 16
HELPBALLOON = 17
TOOLTIP = 18
TREEVIEW = 20
TREEVIEWITEM = 21
TAB = 22
TABCONTROL = 23
SLIDER = 24
PROGRESSBAR = 25
SCROLLBAR = 26
STATUSBAR = 27
TABLE = 28
TABLECELL = 29
TABLECOLUMN = 30
TABLEROW = 31
TABLECOLUMNHEADER = 32
TABLEROWHEADER = 33
FRAME = 34
TOOLBAR = 35
DROPDOWNBUTTON = 36
CLOCK = 37
SEPARATOR = 38
FORM = 39
HEADING = 40
HEADING1 = 41
HEADING2 = 42
HEADING3 = 43
HEADING4 = 44
HEADING5 = 45
HEADING6 = 46
PARAGRAPH = 47
BLOCKQUOTE = 48
TABLEHEADER = 49
TABLEBODY = 50
TABLEFOOTER = 51
DOCUMENT = 52
ANIMATION = 53
APPLICATION = 54
BOX = 55
GROUPING = 56
PROPERTYPAGE = 57
CANVAS = 58
CAPTION = 59
CHECKMENUITEM = 60
DATEEDITOR = 61
ICON = 62
DIRECTORYPANE = 63
EMBEDDEDOBJECT = 64
ENDNOTE = 65
FOOTER = 66
FOOTNOTE = 67
GLASSPANE = 69
HEADER = 70
IMAGEMAP = 71
INPUTWINDOW = 72
LABEL = 73
NOTE = 74
PAGE = 75
RADIOMENUITEM = 76
LAYEREDPANE = 77
REDUNDANTOBJECT = 78
ROOTPANE = 79
EDITBAR = 80
TERMINAL = 82
RICHEDIT = 83
RULER = 84
SCROLLPANE = 85
SECTION = 86
SHAPE = 87
SPLITPANE = 88
VIEWPORT = 89
TEAROFFMENU = 90
TEXTFRAME = 91
TOGGLEBUTTON = 92
BORDER = 93
CARET = 94
CHARACTER = 95
CHART = 96
CURSOR = 97
DIAGRAM = 98
DIAL = 99
DROPLIST = 100
SPLITBUTTON = 101
MENUBUTTON = 102
DROPDOWNBUTTONGRID = 103
MATH = 104
GRIP = 105
HOTKEYFIELD = 106
INDICATOR = 107
SPINBUTTON = 108
SOUND = 109
WHITESPACE = 110
TREEVIEWBUTTON = 111
IPADDRESS = 112
DESKTOPICON = 113
INTERNALFRAME = 115
DESKTOPPANE = 116
OPTIONPANE = 117
COLORCHOOSER = 118
FILECHOOSER = 119
FILLER = 120
MENU = 121
PANEL = 122
PASSWORDEDIT = 123
FONTCHOOSER = 124
LINE = 125
FONTNAME = 126
FONTSIZE = 127
BOLD = 128
ITALIC = 129
UNDERLINE = 130
FGCOLOR = 131
BGCOLOR = 132
SUPERSCRIPT = 133
SUBSCRIPT = 134
STYLE = 135
INDENT = 136
ALIGNMENT = 137
ALERT = 138
DATAGRID = 139
DATAITEM = 140
HEADERITEM = 141
THUMB = 142
CALENDAR = 143
VIDEO = 144
AUDIO = 145
CHARTELEMENT = 146
DELETED_CONTENT = 147
INSERTED_CONTENT = 148
LANDMARK = 149
ARTICLE = 150
REGION = 151
FIGURE = 152
MARKED_CONTENT = 153
BUSY_INDICATOR = 154
COMMENT = 155
SUGGESTION = 156
DEFINITION = 157
SWITCH = 158

controlTypes.roleAndStateSpecialCases module

controlTypes.roleAndStateSpecialCases.transformRoleStates(role: Role, states: Set[State]) Tuple[Role, Set[State]]

Map NVDA Role-State combinations to adjusted NVDA Role-State combinations. Some combinations of roles and states may be better represented with some alternative combination. As an example: Role.PROGRESSBAR with State.INDETERMINATE should be represented by only the Role.BUSY_INDICATOR, with no State.INDETERMINATE, or State.HALFCHECKED. @param role: NVDA Role to consider @param states: NVDA States to consider @return: A tuple with the new Role and modified States set.

controlTypes.state module

controlTypes.state.setBit(bitPos: int) int
class controlTypes.state.State(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)

Bases: DisplayStringIntEnum

Add-on authors are recommended not to depend on values and use a State directly. From a string, this can be done as controlTypes.State[nameOfState] e.g. State["CHECKED"]. Although unlikely to change, if names/values changing represents a significant risk for your add-on, then consider decoupling, and maintain an internal mapping of State to add-on internal states.

As add-on authors may still rely on the values, new members of State should continue the pattern of incrementing.

property _displayStringLabels

Specify a dictionary which takes members of the Enum and returns the translated display string.

property negativeDisplayString: str

@return: The translated UI display string, used when referring to this value of the enum in the negative.

UNAVAILABLE = 1
FOCUSED = 2
SELECTED = 4
BUSY = 8
PRESSED = 16
CHECKED = 32
HALFCHECKED = 64
READONLY = 128
EXPANDED = 256
COLLAPSED = 512
INVISIBLE = 1024
VISITED = 2048
LINKED = 4096
HASPOPUP = 8192
PROTECTED = 16384
REQUIRED = 32768
DEFUNCT = 65536
INVALID_ENTRY = 131072
MODAL = 262144
AUTOCOMPLETE = 524288
MULTILINE = 1048576
ICONIFIED = 2097152
OFFSCREEN = 4194304
SELECTABLE = 8388608
FOCUSABLE = 16777216
CLICKABLE = 33554432
EDITABLE = 67108864
CHECKABLE = 134217728
DRAGGABLE = 268435456
DRAGGING = 536870912
DROPTARGET = 1073741824
SORTED = 2147483648
SORTED_ASCENDING = 4294967296
SORTED_DESCENDING = 8589934592
HASLONGDESC = 17179869184
PINNED = 34359738368
HASFORMULA = 68719476736
HASCOMMENT = 137438953472
OBSCURED = 274877906944
CROPPED = 549755813888
OVERFLOWING = 1099511627776
UNLOCKED = 2199023255552
HAS_ARIA_DETAILS = 4398046511104
HASNOTE = 8796093022208
INDETERMINATE = 17592186044416
HALF_PRESSED = 35184372088832
ON = 70368744177664
HASPOPUP_DIALOG = 140737488355328
HASPOPUP_GRID = 281474976710656
HASPOPUP_LIST = 562949953421312
HASPOPUP_TREE = 1125899906842624