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 ascontrolTypes.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 ofRole
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. Usingenum.auto
may backfill role values and should be avoided. Refer totest_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
- LINK = 19
- 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 ascontrolTypes.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 ofState
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.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 ascontrolTypes.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 ofRole
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. Usingenum.auto
may backfill role values and should be avoided. Refer totest_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
- LINK = 19
- 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 ascontrolTypes.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 ofState
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