api module
General functions for NVDA Functions should mostly refer to getting an object (NVDAObject) or a position (TextInfo).
- api.getFocusObject() NVDAObject
Gets the current object with focus. @returns: the object with focus
- api.getForegroundObject() NVDAObject
Gets the current foreground object. This (cached) object is the (effective) top-level “window” (hwnd). EG a Dialog rather than the focused control within the dialog. The cache is updated as queued events are processed, as such there will be a delay between the winEvent and this function matching. However, within NVDA this should be used in order to be in sync with other functions such as “getFocusAncestors”. @returns: the current foreground object
- api.setForegroundObject(obj: NVDAObject) bool
Stores the given object as the current foreground object. Note: does not cause the operating system to change the foreground window,
but simply allows NVDA to keep track of what the foreground window is. Alternative names for this function may have been: - setLastForegroundWindow - setLastForegroundEventObject
@param obj: the object that will be stored as the current foreground object
- api.setFocusObject(obj: NVDAObject) bool
Stores an object as the current focus object. Note: this does not physically change the window with focus in the operating system, but allows NVDA to keep track of the correct object. Before overriding the last object, this function calls event_loseFocus on the object to notify it that it is losing focus. @param obj: the object that will be stored as the focus object
- api.getFocusDifferenceLevel()
- api.getFocusAncestors()
An array of NVDAObjects that are all parents of the object which currently has focus
- api.getMouseObject()
Returns the object that is directly under the mouse
- api.setMouseObject(obj: NVDAObject) bool
Tells NVDA to remember the given object as the object that is directly under the mouse
- api.getDesktopObject() NVDAObject
Get the desktop object
- api.setDesktopObject(obj: NVDAObject) None
Tells NVDA to remember the given object as the desktop object. We cannot prevent setting this when objectBelowLockScreenAndWindowsIsLocked is True, as NVDA needs to set the desktopObject on start, and NVDA may start from the lockscreen.
- api.getReviewPosition() TextInfo
Retrieves the current TextInfo instance representing the user’s review position. If it is not set, it uses navigator object to create a TextInfo.
- api.setReviewPosition(reviewPosition: TextInfo, clearNavigatorObject: bool = True, isCaret: bool = False, isMouse: bool = False) bool
Sets a TextInfo instance as the review position. @param clearNavigatorObject: if True, It sets the current navigator object to C{None}.
In that case, the next time the navigator object is asked for it fetches it from the review position.
@param isCaret: Whether the review position is changed due to caret following. @param isMouse: Whether the review position is changed due to mouse following.
Gets the current navigator object. Navigator objects can be used to navigate around the operating system (with the numpad), without moving the focus. If the navigator object is not set, it fetches and sets it from the review position. @returns: the current navigator object
Sets an object to be the current navigator object. Navigator objects can be used to navigate around the operating system (with the numpad), without moving the focus. It also sets the current review position to None so that next time the review position is asked for, it is created from the navigator object. @param obj: the object that will be set as the current navigator object @param isFocus: true if the navigator object was set due to a focus change.
- api.isTypingProtected()
Checks to see if key echo should be suppressed because the focus is currently on an object that has its protected state set. @returns: True if it should be suppressed, False otherwise. @rtype: boolean
- api.createStateList(states)
Breaks down the given integer in to a list of numbers that are 2 to the power of their position.
- api.moveMouseToNVDAObject(obj)
Moves the mouse to the given NVDA object’s position
- api.processPendingEvents(processEventQueue=True)
- api.copyToClip(text: str, notify: bool | None = False) bool
Copies the given text to the windows clipboard. @returns: True if it succeeds, False otherwise. @param text: the text which will be copied to the clipboard @param notify: whether to emit a confirmation message
- api.getClipData()
Receives text from the windows clipboard. @returns: Clipboard text @rtype: string
- api.getStatusBar() NVDAObject | None
Obtain the status bar for the current foreground object. @return: The status bar object or C{None} if no status bar was found.
- api.getStatusBarText(obj)
Get the text from a status bar. This includes the name of the status bar and the names and values of all of its children. @param obj: The status bar. @type obj: L{NVDAObjects.NVDAObject} @return: The status bar text. @rtype: str
- api.filterFileName(name)
Replaces invalid characters in a given string to make a windows compatible file name. @param name: The file name to filter. @type name: str @returns: The filtered file name. @rtype: str
- api.isNVDAObject(obj: Any) bool
Returns whether the supplied object is a L{NVDAObjects.NVDAObject}
- api.isCursorManager(obj: Any) bool
Returns whether the supplied object is a L{cursorManager.CursorManager}
- api.isTreeInterceptor(obj: Any) bool
Returns whether the supplied object is a L{treeInterceptorHandler.TreeInterceptor}
- api.isObjectInActiveTreeInterceptor(obj: NVDAObject) bool
Returns whether the supplied L{NVDAObjects.NVDAObject} is in an active L{treeInterceptorHandler.TreeInterceptor}, i.e. a tree interceptor that is not in pass through mode.
- api.getCaretObject() documentBase.TextContainerObject
Gets the object which contains the caret. This is normally the NVDAObject with focus, unless it has a browse mode tree interceptor to return instead. @return: The object containing the caret. @note: Note: this may not be the NVDA Object closest to the caret, EG an edit text box may have focus, and contain multiple NVDAObjects closer to the caret position, consider instead:
ti = getCaretPosition() ti.expand(textInfos.UNIT_CHARACTER) closestObj = ti.NVDAObjectAtStart