braille module
- braille.FALLBACK_TABLE
Table to use if the output table configuration is invalid.
- braille.CURSOR_SHAPES = ((192, 'Dots 7 and 8'), (128, 'Dot 8'), (255, 'All dots'))
Cursor shapes
- braille.SELECTION_SHAPE = 192
Dots 7 and 8
- braille.END_OF_BRAILLE_OUTPUT_SHAPE = 255
The braille shape shown on a braille display when the number of cells used by the braille handler is lower than the actual number of cells. The 0 based position of the shape is equal to the number of cells used by the braille handler.
- braille.INPUT_START_IND = '⣏'
Unicode braille indicator at the start of untranslated braille input.
- braille.INPUT_END_IND = ' ⣹'
Unicode braille indicator at the end of untranslated braille input.
- class braille.FormatTagDelimiter(value, names=None, *, module=None, qualname=None, type=None, start=1, boundary=None)
Bases:
StrEnum
Delimiters for the start and end of format tags.
As these are shapes, they should be provided in unicode braille.
- START = '⣋'
- END = '⣙'
- braille.CONTEXTPRES_CHANGEDCONTEXT = 'changedContext'
Identifier for a focus context presentation setting that only shows as much as possible focus context information when the context has changed.
- braille.CONTEXTPRES_FILL = 'fill'
Identifier for a focus context presentation setting that shows as much as possible focus context information if the focus object doesn’t fill up the whole display.
- braille.CONTEXTPRES_SCROLL = 'scroll'
Identifier for a focus context presentation setting that always shows the object with focus at the very left of the braille display.
- braille.focusContextPresentations = [('changedContext', 'Fill display for context changes'), ('fill', 'Always fill display'), ('scroll', 'Only when scrolling back')]
Focus context presentations associated with their user readable and translatable labels
- class braille.RegionWithPositions(region, start, end)
Bases:
tuple
Named tuple for a region with start and end positions in a buffer
- _asdict()
Return a new dict which maps field names to their values.
- _field_defaults = {}
- _fields = ('region', 'start', 'end')
- classmethod _make(iterable)
Make a new RegionWithPositions object from a sequence or iterable
- _replace(**kwds)
Return a new RegionWithPositions object replacing specified fields with new values
- end
Alias for field number 2
- region
Alias for field number 0
- start
Alias for field number 1
- braille.AUTO_DISPLAY_NAME = 'auto'
Used in place of a specific braille display driver name to indicate that braille displays should be automatically detected and used. @type: str
- braille.NO_BRAILLE_DISPLAY_NAME: str = 'noBraille'
The name of the noBraille display driver.
- class braille.FormattingMarker(start: str, end: str)
Bases:
NamedTuple
A pair of braille symbols that indicate the start and end of a particular type of font formatting.
As these are shapes, they should be provided in unicode braille.
Create new instance of FormattingMarker(start, end)
- start: str
Alias for field number 0
- end: str
Alias for field number 1
- _asdict()
Return a new dict which maps field names to their values.
- _field_defaults = {}
- _fields = ('start', 'end')
- classmethod _make(iterable)
Make a new FormattingMarker object from a sequence or iterable
- _replace(**kwds)
Return a new FormattingMarker object replacing specified fields with new values
- braille.NVDAObjectHasUsefulText(obj: NVDAObject) bool
Does obj contain useful text to display in braille
- Parameters:
obj – object to check
- Returns:
True if there is useful text, False if not
- braille._getDisplayDriver(moduleName: str, caseSensitive: bool = True) Type[BrailleDisplayDriver]
- braille.getDisplayList(excludeNegativeChecks=True) List[Tuple[str, str]]
Gets a list of available display driver names with their descriptions. @param excludeNegativeChecks: excludes all drivers for which the check method returns C{False}. @type excludeNegativeChecks: bool @return: list of tuples with driver names and descriptions.
- class braille.Region
Bases:
object
A region of braille to be displayed. Each portion of braille to be displayed is represented by a region. The region is responsible for retrieving its text and the cursor and selection positions, translating it into braille cells and handling cursor routing requests relative to its braille cells. The L{BrailleBuffer} containing this region will call L{update} and expect that L{brailleCells}, L{brailleCursorPos}, L{brailleSelectionStart} and L{brailleSelectionEnd} will be set appropriately. L{routeTo} will be called to handle a cursor routing request.
- rawText
The original, raw text of this region.
- cursorPos
The position of the cursor in L{rawText}, C{None} if the cursor is not in this region. @type: int
- selectionStart
The start of the selection in L{rawText} (inclusive), C{None} if there is no selection in this region. @type: int
- selectionEnd
The end of the selection in L{rawText} (exclusive), C{None} if there is no selection in this region. @type: int
- brailleCells
The translated braille representation of this region. @type: [int, …]
- rawTextTypeforms
liblouis typeform flags for each character in L{rawText}, C{None} if no typeform info. @type: [int, …]
- rawToBraillePos
A list mapping positions in L{rawText} to positions in L{brailleCells}. @type: [int, …]
- brailleToRawPos
A list mapping positions in L{brailleCells} to positions in L{rawText}. @type: [int, …]
- brailleCursorPos: int | None
The position of the cursor in L{brailleCells}, C{None} if the cursor is not in this region.
- brailleSelectionStart
The position of the selection start in L{brailleCells}, C{None} if there is no selection in this region. @type: int
- brailleSelectionEnd
The position of the selection end in L{brailleCells}, C{None} if there is no selection in this region. @type: int
- hidePreviousRegions
Whether to hide all previous regions. @type: bool
- focusToHardLeft
Whether this region should be positioned at the absolute left of the display when focused. @type: bool
- update()
Update this region. Subclasses should extend this to update L{rawText}, L{cursorPos}, L{selectionStart} and L{selectionEnd} if necessary. The base class method handles translation of L{rawText} into braille, placing the result in L{brailleCells}. Typeform information from L{rawTextTypeforms} is used, if any. L{rawToBraillePos} and L{brailleToRawPos} are updated according to the translation. L{brailleCursorPos}, L{brailleSelectionStart} and L{brailleSelectionEnd} are similarly updated based on L{cursorPos}, L{selectionStart} and L{selectionEnd}, respectively. @postcondition: L{brailleCells}, L{brailleCursorPos}, L{brailleSelectionStart} and L{brailleSelectionEnd} are updated and ready for rendering.
- routeTo(braillePos)
Handle a cursor routing request. For example, this might activate an object or move the cursor to the requested position. @param braillePos: The routing position in L{brailleCells}. @type braillePos: int @note: If routing the cursor, L{brailleToRawPos} can be used to translate L{braillePos} into a position in L{rawText}.
- nextLine()
Move to the next line if possible.
- previousLine(start=False)
Move to the previous line if possible. @param start: C{True} to move to the start of the line, C{False} to move to the end. @type start: bool
- braille._getAnnotationProperty(propertyValues: Dict[str, Any]) str
- braille.getPropertiesBraille(**propertyValues) str
- class braille.NVDAObjectRegion(obj: NVDAObject, appendText: str = '')
Bases:
Region
A region to provide a braille representation of an NVDAObject. This region will update based on the current state of the associated NVDAObject. A cursor routing request will activate the object’s default action.
Constructor. @param obj: The associated NVDAObject. @param appendText: Text which should always be appended to the NVDAObject text, useful if this region will always precede other regions.
- update()
Update this region. Subclasses should extend this to update L{rawText}, L{cursorPos}, L{selectionStart} and L{selectionEnd} if necessary. The base class method handles translation of L{rawText} into braille, placing the result in L{brailleCells}. Typeform information from L{rawTextTypeforms} is used, if any. L{rawToBraillePos} and L{brailleToRawPos} are updated according to the translation. L{brailleCursorPos}, L{brailleSelectionStart} and L{brailleSelectionEnd} are similarly updated based on L{cursorPos}, L{selectionStart} and L{selectionEnd}, respectively. @postcondition: L{brailleCells}, L{brailleCursorPos}, L{brailleSelectionStart} and L{brailleSelectionEnd} are updated and ready for rendering.
- routeTo(braillePos)
Handle a cursor routing request. For example, this might activate an object or move the cursor to the requested position. @param braillePos: The routing position in L{brailleCells}. @type braillePos: int @note: If routing the cursor, L{brailleToRawPos} can be used to translate L{braillePos} into a position in L{rawText}.
- class braille.ReviewNVDAObjectRegion(obj: NVDAObject, appendText: str = '')
Bases:
NVDAObjectRegion
A region to provide a braille representation of an NVDAObject when braille is tethered to review. This region behaves very similar to its base class. However, when the move system caret when routing review cursor braille setting is active, pressing a routing key will first focus the object before executing the default action.
Constructor. @param obj: The associated NVDAObject. @param appendText: Text which should always be appended to the NVDAObject text, useful if this region will always precede other regions.
- routeTo(braillePos: int)
Handle a cursor routing request. For example, this might activate an object or move the cursor to the requested position. @param braillePos: The routing position in L{brailleCells}. @type braillePos: int @note: If routing the cursor, L{brailleToRawPos} can be used to translate L{braillePos} into a position in L{rawText}.
- braille.getControlFieldBraille(info: TextInfo, field: Field, ancestors: List[Field], reportStart: bool, formatConfig: AggregatedSection) str | None
- braille._getControlFieldForLayoutPresentation(description: str | None, current: IsCurrent, hasDetails: bool, detailsRoles: Tuple[Role | None], role: Role, content: str | None) str | None
- braille._getControlFieldForTableCell(description: str | None, current: IsCurrent, hasDetails: bool, detailsRoles: Tuple[Role | None], field: Field, formatConfig: AggregatedSection, states: Set[State]) str
- braille._getControlFieldForReportStart(description: str | None, current: IsCurrent, hasDetails: bool, detailsRoles: Tuple[Role | None], field: Field, role: Role, states: Set[State], content: str | None, info: TextInfo, value: str | None, roleText: str, placeholder: str | None, errorMessage: str | None) str
- braille.getFormatFieldBraille(field, fieldCache, isAtStart, formatConfig)
Generates the braille text for the given format field. @param field: The format field to examine. @type field: {str : str, …} @param fieldCache: The format field of the previous run; i.e. the cached format field. @type fieldCache: {str : str, …} @param isAtStart: True if this format field precedes any text in the line/paragraph. This is useful to restrict display of information which should only appear at the start of the line/paragraph; e.g. the line number or line prefix (list bullet/number). @type isAtStart: bool @param formatConfig: The formatting config. @type formatConfig: {str : bool, …}
- braille.getParagraphStartMarker() str | None
- braille._getFormattingTags(field: dict[str, str], fieldCache: dict[str, str], formatConfig: dict[str, bool]) str | None
Get the formatting tags for the given field and cache.
Formatting tags are calculated according to the preferences passed in formatConfig.
- Parameters:
field – The format current field.
fieldCache – The previous format field.
formatConfig – The user’s formatting preferences.
- Returns:
The braille formatting tag as a string, or None if no pertinant formatting is applied.
- braille._appendFormattingMarker(attribute: str, marker: FormattingMarker, textList: list[str], field: dict[str, str], fieldCache: dict[str, str]) None
Append a formatting marker to the text list if the attribute has changed.
- Parameters:
attribute – The attribute to check.
marker – The formatting marker to use.
textList – The list of marker strings to append to.
field – The current format field.
fieldCache – The previous format field.
- class braille.TextInfoRegion(obj: NVDAObject)
Bases:
Region
- pendingCaretUpdate = False
True if the cursor should be updated for this region on the display
- allowPageTurns = True
True if a page turn should be tried when a TextInfo cannot move anymore and the object supports page turns.
- _isMultiline()
- _getSelection()
Retrieve the selection. If there is no selection, retrieve the collapsed cursor. @return: The selection. @rtype: L{textInfos.TextInfo}
- _setCursor(info: TextInfo)
Set the cursor. @param info: The range to which the cursor should be moved.
- _getTypeformFromFormatField(field, formatConfig)
- _addFieldText(text, contentPos, separate=True)
- _addTextWithFields(info, formatConfig, isSelection=False)
- _getReadingUnit()
- update()
Update this region. Subclasses should extend this to update L{rawText}, L{cursorPos}, L{selectionStart} and L{selectionEnd} if necessary. The base class method handles translation of L{rawText} into braille, placing the result in L{brailleCells}. Typeform information from L{rawTextTypeforms} is used, if any. L{rawToBraillePos} and L{brailleToRawPos} are updated according to the translation. L{brailleCursorPos}, L{brailleSelectionStart} and L{brailleSelectionEnd} are similarly updated based on L{cursorPos}, L{selectionStart} and L{selectionEnd}, respectively. @postcondition: L{brailleCells}, L{brailleCursorPos}, L{brailleSelectionStart} and L{brailleSelectionEnd} are updated and ready for rendering.
- getTextInfoForBraillePos(braillePos: int) TextInfo
Fetches a collapsed TextInfo at the specified braille position in the region. :param braillePos: The braille position.
If no textInfo could be found at braillePos, try to find one at braillePos - 1 until a position has been found.
- routeTo(braillePos: int)
Handle a cursor routing request. For example, this might activate an object or move the cursor to the requested position. @param braillePos: The routing position in L{brailleCells}. @type braillePos: int @note: If routing the cursor, L{brailleToRawPos} can be used to translate L{braillePos} into a position in L{rawText}.
- nextLine()
Move to the next line if possible.
- previousLine(start=False)
Move to the previous line if possible. @param start: C{True} to move to the start of the line, C{False} to move to the end. @type start: bool
- class braille.CursorManagerRegion(obj: NVDAObject)
Bases:
TextInfoRegion
- _isMultiline()
- _getSelection()
Retrieve the selection. If there is no selection, retrieve the collapsed cursor. @return: The selection. @rtype: L{textInfos.TextInfo}
- class braille.ReviewTextInfoRegion(obj: NVDAObject)
Bases:
TextInfoRegion
- allowPageTurns = False
True if a page turn should be tried when a TextInfo cannot move anymore and the object supports page turns.
- _getSelection()
Retrieve the selection. If there is no selection, retrieve the collapsed cursor. @return: The selection. @rtype: L{textInfos.TextInfo}
- class braille.ReviewCursorManagerRegion(obj: NVDAObject)
- braille._routingShouldMoveSystemCaret() bool
Returns whether pressing a braille routing key should move the system caret.
- braille.rindex(seq, item, start, end)
- class braille.BrailleBuffer(*args, **kwargs)
Bases:
AutoPropertyObject
- regions
The regions in this buffer. @type: [L{Region}, …]
- rawText
The raw text of the entire buffer.
- cursorPos
The position of the cursor in L{brailleCells}, C{None} if no region contains the cursor. @type: int
- brailleCells
The translated braille representation of the entire buffer. @type: [int, …]
- windowStartPos
The position in L{brailleCells} where the display window starts (inclusive). @type: int
- clear()
Clear the entire buffer. This removes all regions and resets the window position to 0.
- _get_visibleRegions()
- _get_regionsWithPositions()
- _get_rawToBraillePos()
@return: a list mapping positions in L{rawText} to positions in L{brailleCells} for the entire buffer. @rtype: [int, …]
- brailleToRawPos: List[int]
- _get_brailleToRawPos()
@return: a list mapping positions in L{brailleCells} to positions in L{rawText} for the entire buffer. @rtype: [int, …]
- bufferPosToRegionPos(bufferPos)
- regionPosToBufferPos(region, pos, allowNearest=False)
- bufferPositionsToRawText(startPos, endPos)
- bufferPosToWindowPos(bufferPos)
- _get_windowEndPos()
- _set_windowEndPos(endPos)
Sets the end position for the braille window and recalculates the window start position based on several variables. 1. Braille display size. 2. Whether one of the regions should be shown hard left on the braille display;
i.e. because of The configuration setting for focus context representation or whether the braille region that corresponds with the focus represents a multi line edit box.
Whether word wrap is enabled.
- _nextWindow()
- scrollForward()
- _previousWindow()
- scrollBack()
- scrollTo(region, pos)
- focus(region)
Bring the specified region into focus. The region is placed at the start of the display. However, if the region has not set L{Region.focusToHardLeft} and there is extra space at the end of the display, the display is scrolled left so that as much as possible is displayed. @param region: The region to focus. @type region: L{Region}
- update()
- updateDisplay()
- _get_cursorWindowPos()
- _get_windowRawText()
- _get_windowBrailleCells()
- routeTo(windowPos)
- getTextInfoForWindowPos(windowPos)
- saveWindow()
Save the current window so that it can be restored after the buffer is updated. The window start position is saved as a position relative to a region. This allows it to be restored even after other regions are added, removed or updated. It can be restored with L{restoreWindow}. @postcondition: The window is saved and can be restored with L{restoreWindow}.
- restoreWindow()
Restore the window saved by L{saveWindow}. @precondition: L{saveWindow} has been called. @postcondition: If the saved position is valid, the window is restored.
Otherwise, the nearest position is restored.
- _abc_impl = <_abc._abc_data object>
- cursorWindowPos
- rawToBraillePos
- regionsWithPositions
- visibleRegions
- windowBrailleCells
- property windowEndPos
- windowRawText
- braille.invalidateCachedFocusAncestors(index)
Invalidate cached focus ancestors from a given index. This will cause regions to be generated for the focus ancestors >= index next time L{getFocusContextRegions} is called, rather than using cached regions for those ancestors. @param index: The index from which cached focus ancestors should be invalidated. @type index: int
- braille.getFocusContextRegions(obj: NVDAObject, oldFocusRegions: List[Region] | None = None) Generator[Region, None, None]
- braille.getFocusRegions(obj: NVDAObject, review: bool = False) Generator[Region, None, None]
- braille.formatCellsForLog(cells: List[int]) str
Formats a sequence of braille cells so that it is suitable for logging. The output contains the dot numbers for each cell, with each cell separated by a space. A C{-} indicates an empty cell. @param cells: The cells to format. @return: The formatted cells.
- braille.pre_writeCells = <extensionPoints.Action object>
Notifies when cells are about to be written to a braille display. This allows components and add-ons to perform an action. For example, when a system is controlled by a braille enabled remote system, the remote system should know what cells to show on its display. @param cells: The list of braille cells. @type cells: List[int] @param rawText: The raw text that corresponds with the cells. @type rawText: str @param currentCellCount: The current number of cells @type currentCellCount: bool
- braille.filter_displaySize = <extensionPoints.Filter object>
Filter that allows components or add-ons to change the display size used for braille output. For example, when a system has an 80 cell display, but is being controlled by a remote system with a 40 cell display, the display size should be lowered to 40 . @param value: the number of cells of the current display. @type value: int
- braille.displaySizeChanged = <extensionPoints.Action object>
Action that allows components or add-ons to be notified of display size changes. For example, when a system is controlled by a remote system and the remote system swaps displays, The local system should be notified about display size changes at the remote system. @param displaySize: The current display size used by the braille handler. @type displaySize: int
- braille.displayChanged = <extensionPoints.Action object>
Action that allows components or add-ons to be notified of braille display changes. For example, when a system is controlled by a remote system and the remote system swaps displays, The local system should be notified about display parameters at the remote system, e.g. name and cellcount. @param display: The new braille display driver @type display: L{BrailleDisplayDriver} @param isFallback: Whether the display is set as fallback display due to another display’s failure @type isFallback: bool @param detected: If the display was set by auto detection, the device match that matched the driver @type detected: bdDetect.DeviceMatch or C{None}
- braille.decide_enabled = <extensionPoints.Decider object>
Allows components or add-ons to decide whether the braille handler should be forcefully disabled. For example, when a system is controlling a remote system with braille, the local braille handler should be disabled as long as the system is in control of the remote system. Handlers are called without arguments.
- class braille.BrailleHandler(*args, **kwargs)
Bases:
AutoPropertyObject
- TETHER_AUTO = 'auto'
- TETHER_FOCUS = 'focus'
- TETHER_REVIEW = 'review'
- tetherValues = [('auto', 'automatically'), ('focus', 'to focus'), ('review', 'to review')]
- queuedWrite: List[int] | None = None
- _displaySize: int
Internal cache for the displaySize property. This attribute is used to compare the displaySize output by l{filter_displaySize} with its previous output. If the value differs, L{displaySizeChanged} is notified.
- _enabled: bool
Internal cache for the enabled property. This attribute is used to compare the enabled output by l{decide_enabled} with its previous output. If L{decide_enabled} decides to disable the handler, pending output should be cleared.
- _regionsPendingUpdate: Set[NVDAObjectRegion | TextInfoRegion]
Regions pending an update. Regions are added by L{handleUpdate} and L{handleCaretMove} and cleared in L{_handlePendingUpdate}.
- queuedWriteLock: allocate_lock
- ackTimerHandle: int
- terminate()
- property table: BrailleTable
Type definition for auto prop ‘_get_table/_set_table’
- _get_table() BrailleTable
The translation table to use for braille output.
- _set_table(table: BrailleTable)
- _showSpeechInBrailleRegions: list[TextRegion] = []
- _showSpeechInBraille(speechSequence: SpeechSequence)
- _suppressClearBrailleRegions: bool = False
- suppressClearBrailleRegions(script: Callable[[InputGesture], None])
- clearBrailleRegions()
- getTether()
- setTether(tether, auto=False)
- _get_shouldAutoTether() bool
- property displaySize
Returns the display size to use for braille output. Handlers can register themselves to L{filter_displaySize} to change this value on the fly. Therefore, this is a read only property and can’t be set.
- _cache_displaySize = True
- _get_displaySize()
Returns the display size to use for braille output. Handlers can register themselves to L{filter_displaySize} to change this value on the fly. Therefore, this is a read only property and can’t be set.
- _set_displaySize(value)
While the display size can be changed while a display is connected (for instance see L{brailleDisplayDrivers.alva.BrailleDisplayDriver} split point feature), it is not possible to override the display size using this property. Consider registering a handler to L{filter_displaySize} instead.
- property enabled
Returns whether braille is enabled. Handlers can register themselves to L{decide_enabled} and return C{False} to forcefully disable the braille handler. If components need to change the state from disabled to enabled instead, they should register to L{filter_displaySize}. By default, the enabled/disabled state is based on the boolean value of L{displaySize}, and thus is C{True} when the display size is greater than 0. This is a read only property and can’t be set.
- _cache_enabled = True
- _get_enabled()
Returns whether braille is enabled. Handlers can register themselves to L{decide_enabled} and return C{False} to forcefully disable the braille handler. If components need to change the state from disabled to enabled instead, they should register to L{filter_displaySize}. By default, the enabled/disabled state is based on the boolean value of L{displaySize}, and thus is C{True} when the display size is greater than 0. This is a read only property and can’t be set.
- _set_enabled(value)
- _handleEnabledDecisionFalse()
When a decider handler decides to disable the braille handler, ensure braille doesn’t continue. This should be called from the main thread to avoid wx assertions.
- _lastRequestedDisplayName = None
The name of the last requested braille display driver with setDisplayByName, even if it failed and has fallen back to no braille.
- setDisplayByName(name: str, isFallback: bool = False, detected: DeviceMatch | None = None) bool
- _switchDisplay(oldDisplay: BrailleDisplayDriver | None, newDisplayClass: Type[BrailleDisplayDriver], **kwargs) BrailleDisplayDriver
- _setDisplay(newDisplayClass: Type[BrailleDisplayDriver], isFallback: bool = False, detected: DeviceMatch | None = None)
- _onBrailleViewerChangedState(created)
- _updateDisplay()
- _writeCells(cells: List[int])
- _writeCellsInBackground()
Writes cells to a braille display in the background by queuing a function to the i/o thread.
- _displayWithCursor()
- _blink()
- update()
- scrollForward()
- scrollBack()
- routeTo(windowPos)
- getTextInfoForWindowPos(windowPos)
- message(text)
Display a message to the user which times out after a configured interval. The timeout will be reset if the user scrolls the display. The message will be dismissed immediately if the user presses a cursor routing key. If a key is pressed the message will be dismissed by the next text being written to the display. @postcondition: The message is displayed.
- _resetMessageTimer()
Reset the message timeout. @precondition: A message is currently being displayed.
- _dismissMessage(shouldUpdate: bool = True)
Dismiss the current message. @param shouldUpdate: Whether to call update after dismissing. @precondition: A message is currently being displayed. @postcondition: The display returns to the main buffer.
- handleGainFocus(obj: NVDAObject, shouldAutoTether: bool = True) None
- _doNewObject(regions)
- handleCaretMove(obj: NVDAObject, shouldAutoTether: bool = True) None
- _handlePendingUpdate()
When any region is pending an update, updates the region and the braille display.
- scrollToCursorOrSelection(region)
- _handleProgressBarUpdate(obj: NVDAObject) None
- handleUpdate(obj: NVDAObject) None
- handleReviewMove(shouldAutoTether=True)
- initialDisplay()
- handlePostConfigProfileSwitch()
Called when the braille display becomes unavailable. This logs an error and disables the display. This is called when displaying cells raises an exception, but drivers can also call it themselves if appropriate.
- _enableDetection(usb: bool = True, bluetooth: bool = True, limitToDevices: List[str] | None = None)
Enables automatic detection of braille displays. When auto detection is already active, this will force a rescan for devices. This should also be executed when auto detection should be resumed due to loss of display connectivity. In that case, it is triggered by L{setDisplayByname}. @param usb: Whether to scan for USB devices @param bluetooth: Whether to scan for Bluetooth devices. @param limitToDevices: An optional list of driver names a scan should be limited to.
This is used when a Bluetooth device is detected, in order to switch to USB when an USB device for the same driver is found. C{None} if no driver filtering should occur.
- _disableDetection()
Disables automatic detection of braille displays.
- _bgThreadExecutor(param: int)
Executed as APC when cells have to be written to a display asynchronously.
- _ackTimeoutResetter(param: int)
- _abc_impl = <_abc._abc_data object>
- shouldAutoTether
- braille.initialize()
- braille.pumpAll()
Runs tasks at the end of each core cycle. For now just region updates, e.g. for caret movement.
- braille.terminate()
- class braille.BrailleDisplayDriver(*args, **kwargs)
Bases:
Driver
Abstract base braille display driver. Each braille display driver should be a separate Python module in the root brailleDisplayDrivers directory containing a BrailleDisplayDriver class which inherits from this base class.
At a minimum, drivers must set L{name} and L{description} and override the L{check} method. To display braille, L{numCells} and L{display} must be implemented.
- To support automatic detection of braille displays belonging to this driver:
The driver must be thread safe and L{isThreadSafe} should be set to C{True}
L{supportsAutomaticDetection} must be set to C{True}.
L{registerAutomaticDetection} must be implemented.
Drivers should dispatch input such as presses of buttons, wheels or other controls using the L{inputCore} framework. They should subclass L{BrailleDisplayGesture} and execute instances of those gestures using L{inputCore.manager.executeGesture}. These gestures can be mapped in L{gestureMap}. A driver can also inherit L{baseObject.ScriptableObject} to provide display specific scripts.
@see: L{hwIo} for raw serial and HID I/O.
There are factory functions to create L{autoSettingsUtils.driverSetting.DriverSetting} instances for common display specific settings; e.g. L{DotFirmnessSetting}.
Constructor @param port: Information on how to connect to the device.
Use L{_getTryPorts} to normalise to L{DeviceMatch} instances. - A string (from config “config.conf[“braille”][name][“port”]”). When manually configured.
This value is set via the settings dialog, the source of the options provided to the user is the BrailleDisplayDriver.getPossiblePorts method.
A L{DeviceMatch} instance. When automatically detected.
- _configSection = 'braille'
The configuration section where driver specific subsections should be saved. @type: str
- supportedSettings: SupportedSettingType = ()
Typing for auto property L{_get_supportedSettings}
- isThreadSafe: bool = False
Whether this driver is thread-safe. If it is, NVDA may initialize, terminate or call this driver on any thread. This allows NVDA to read from and write to the display in the background, which means the rest of NVDA is not blocked while this occurs, thus resulting in better performance. This is also required to use the L{hwIo} module.
- supportsAutomaticDetection: bool = False
Whether this driver is supported for automatic detection of braille displays.
- receivesAckPackets: bool = False
Whether displays for this driver return acknowledgements for sent packets. L{_handleAck} should be called when an ACK is received. Note that thread safety is required for the generic implementation to function properly. If a display is not thread safe, a driver should manually implement ACK processing.
- _awaitingAck: bool = False
Whether this driver is awaiting an Ack for a connected display. This is set to C{True} after displaying cells when L{receivesAckPackets} is True, and set to C{False} by L{_handleAck} or when C{timeout} has elapsed. This is for internal use by NVDA core code only and shouldn’t be touched by a driver itself.
- timeout: float = 0.2
Maximum timeout to use for communication with a device (in seconds). This can be used for serial connections. Furthermore, it is used to stop waiting for missed acknowledgement packets.
- classmethod check() bool
Determine whether this braille display is available. The display will be excluded from the list of available displays if this method returns C{False}. For example, if this display is not present, C{False} should be returned. @return: C{True} if this display is available, C{False} if not.
- classmethod registerAutomaticDetection(driverRegistrar: DriverRegistrar)
This method may register the braille display driver in the braille display automatic detection framework. The framework provides a L{bdDetect.DriverRegistrar} object as its only parameter. The methods on the driver registrar can be used to register devices or device scanners. This method should only register itself with the bdDetect framework, and should refrain from doing anything else. Drivers with L{supportsAutomaticDetection} set to C{True} must implement this method. @param driverRegistrar: An object containing several methods to register device identifiers for this driver.
- terminate()
Terminate this display driver. This will be called when NVDA is finished with this display driver. It should close any open connections, perform cleanup, etc. Subclasses should call the superclass method first. @postcondition: This instance can no longer be used unless it is constructed again.
- property numCells: int
typing information for autoproperty _get_numCells
- _get_numCells() int
Obtain the number of braille cells on this display. @note: 0 indicates that braille should be disabled. @note: For multi line displays, this is the total number of cells (e.g. numRows * numCols) @return: The number of cells.
- _set_numCells(numCells: int)
- numRows: int = 1
Number of rows of the braille display, this will be 1 for most displays Note: Setting this to 0 will cause numCells to be 0 and hence will disable braille.
- numCols: int = 0
Number of columns (cells per row) of the braille display 0 indicates that braille should be disabled.
- display(cells)
Display the given braille cells. @param cells: The braille cells to display. @type cells: [int, …]
- AUTOMATIC_PORT = ('auto', 'Automatic')
Automatic port constant to be used by braille displays that support the “automatic” port Kept for backwards compatibility
- classmethod getPossiblePorts() OrderedDict[str, str]
Returns possible hardware ports for this driver. Optionally and in addition to the values from L{getManualPorts}, three special values may be returned if the driver supports them, “auto”, “usb”, and “bluetooth”.
Generally, drivers shouldn’t implement this method directly. Instead, they should provide automatic detection data via L{bdDetect} and implement L{getPossibleManualPorts} if they support manual ports such as serial ports.
@return: Ordered dictionary for each port a (key : value) of name : translated description.
- classmethod _getAutoPorts(usb=True, bluetooth=True) Iterable[DeviceMatch]
Returns possible ports to connect to using L{bdDetect} automatic detection data. @param usb: Whether to search for USB devices. @type usb: bool @param bluetooth: Whether to search for bluetooth devices. @type bluetooth: bool @return: The device match for each port. @rtype: iterable of L{DeviceMatch}
- classmethod getManualPorts() Iterator[Tuple[str, str]]
Get possible manual hardware ports for this driver. This is for ports which cannot be detected automatically such as serial ports. @return: An iterator containing the name and description for each port.
- classmethod _getTryPorts(port: str | DeviceMatch) Iterator[DeviceMatch]
Returns the ports for this driver to which a connection attempt should be made. This generator function is usually used in L{__init__} to connect to the desired display. @param port: the port to connect to. @return: The name and description for each port
- gestureMap: GlobalGestureMap | None = None
Global input gesture map for this display driver.
- classmethod _getModifierGestures(model=None)
Retrieves modifier gestures from this display driver’s L{gestureMap} that are bound to modifier only keyboard emulate scripts. @param model: the optional braille display model for which modifier gestures should also be included. @type model: str; C{None} if model specific gestures should not be included @return: the ids of the display keys and the associated generalised modifier names @rtype: generator of (set, set)
- _handleAck()
Base implementation to handle acknowledgement packets.
- classmethod DotFirmnessSetting(defaultVal, minVal, maxVal, useConfig=False)
Factory function for creating dot firmness setting.
- classmethod BrailleInputSetting(useConfig=True)
Factory function for creating braille input setting.
- classmethod HIDInputSetting(useConfig)
Factory function for creating HID input setting.
- _abc_impl = <_abc._abc_data object>
- class braille.BrailleDisplayGesture(*args, **kwargs)
Bases:
InputGesture
A button, wheel or other control pressed on a braille display. Subclasses must provide L{source} and L{id}. Optionally, L{model} can be provided to facilitate model specific gestures. L{routingIndex} should be provided for routing buttons. Subclasses can also inherit from L{brailleInput.BrailleInputGesture} if the display has a braille keyboard. If the braille display driver is a L{baseObject.ScriptableObject}, it can provide scripts specific to input gestures from this display.
- _abc_impl = <_abc._abc_data object>
- displayName: str
- id
- identifiers: List[str] | Tuple[str, ...]
- keyNames
- model
- script
- scriptableObject: ScriptableObject | None
typing information for autoproperty _get_scriptableObject
- source
- speechEffectWhenExecuted
The effect on speech when this gesture is executed; one of the SPEECHEFFECT_* constants or C{None}.
- shouldPreventSystemIdle: bool = True
Indicates whether executing this gesture should explicitly prevent the system from being idle. For example, the system is unaware of C{BrailleDisplayGesture} execution, and might even get into sleep mode when reading a long portion of text in braille. In contrast, the system is aware of C{KeyboardInputGesture} execution itself.
- _get_source()
The string used to identify all gestures from this display. This should generally be the driver name. This string will be included in the source portion of gesture identifiers. For example, if this was C{alvaBC6}, a display specific gesture identifier might be C{br(alvaBC6):etouch1}. @rtype: str
- _get_model()
The string used to identify all gestures from a specific braille display model. This should be an alphanumeric short version of the model name, without spaces. This string will be included in the source portion of gesture identifiers. For example, if this was C{alvaBC6}, the model string could look like C{680}, and a corresponding display specific gesture identifier might be C{br(alvaBC6.680):etouch1}. @rtype: str; C{None} if model specific gestures are not supported
- _get_id()
The unique, display specific id for this gesture. @rtype: str
- routingIndex = None
The index of the routing key or C{None} if this is not a routing key. @type: int
- _get_identifiers()
The identifier(s) which will be used in input gesture maps to represent this gesture. These identifiers will be normalized and looked up in order until a match is found. A single identifier should take the form: C{source:id} where C{source} is a few characters representing the source of this gesture and C{id} is the specific gesture. An example identifier is: C{kb(desktop):NVDA+1}
This property should not perform normalization itself. However, please note the following regarding normalization. If C{id} contains multiple chunks separated by a + sign, they are considered to be ordered arbitrarily and may be reordered when normalized. Normalization also ensures that the entire identifier is lower case. For example, NVDA+control+f1 and control+nvda+f1 will match when normalized. See L{normalizeGestureIdentifier} for more details.
Subclasses must implement this method. @return: One or more identifiers which uniquely identify this gesture. @rtype: list or tuple of str
- _get_displayName()
The name of this gesture as presented to the user. The base implementation calls L{getDisplayTextForIdentifier} for the first identifier. Subclasses need not override this unless they wish to provide a more optimal implementation. @return: The display name. @rtype: str
- _get_scriptableObject()
An object which contains scripts specific to this gesture or type of gesture. This object will be searched for scripts before any other object when handling this gesture. @return: The gesture specific scriptable object or C{None} if there is none.
- _get_script()
The script bound to this input gesture. @return: The script to be executed. @rtype: script function
- _get_keyNames()
The names of the keys that are part of this gesture. @rtype: list
- _get_speechEffectWhenExecuted() str | None
- ID_PARTS_REGEX = re.compile('br\\((\\w+)(?:\\.(\\w+))?\\):([\\w+]+)')
Compiled regular expression to match an identifier including an optional model name The model name should be an alphanumeric string without spaces. @type: RegexObject
- classmethod getDisplayTextForIdentifier(identifier)
Get the text to be presented to the user describing a given gesture identifier. This should only be called with normalized gesture identifiers returned by the L{normalizedIdentifiers} property in the same subclass. For example, C{KeyboardInputGesture.getDisplayTextForIdentifier} should only be called for “kb:*” identifiers returned by C{KeyboardInputGesture.normalizedIdentifiers}. Most callers will want L{inputCore.getDisplayTextForIdentifier} instead. The display text consists of two strings: the gesture’s source (e.g. “laptop keyboard”) and the specific gesture (e.g. “alt+tab”). @param identifier: The normalized gesture identifier in question. @type identifier: str @return: A tuple of (source, specificGesture). @rtype: tuple of (str, str) @raise Exception: If no display text can be determined.
- braille.getSerialPorts(filterFunc=None) Iterator[Tuple[str, str]]
Get available serial ports in a format suitable for L{BrailleDisplayDriver.getManualPorts}. @param filterFunc: a function executed on every dictionary retrieved using L{hwPortUtils.listComPorts}.
For example, this can be used to filter by USB or Bluetooth com ports.
@type filterFunc: callable
- braille.getDisplayDrivers(filterFunc: Callable[[Type[BrailleDisplayDriver]], bool] | None = None) Generator[Type[BrailleDisplayDriver], Any, Any]
Gets an iterator of braille display drivers meeting the given filter callable. @param filterFunc: an optional callable that receives a driver as its only argument and returns
either True or False.
@return: Iterator of braille display drivers.