Trees       Indices       Help   
Package NVDAObjects :: Class NVDAObject
[hide private]
[frames] | no frames]

Class NVDAObject

source code

                   object --+        
                            |        
baseObject.AutoPropertyObject --+    
                                |    
      baseObject.ScriptableObject --+
                                    |
                                   NVDAObject

NVDA's representation of a single control/widget.
Every widget, regardless of how it is exposed by an application or the operating system, is represented by a single NVDAObject instance.
This allows NVDA to work with all widgets in a uniform way.
An NVDAObject provides information about the widget (e.g. its name, role and value),
as well as functionality to manipulate it (e.g. perform an action or set focus).
Events for the widget are handled by special event methods on the object.
Commands triggered by input from the user can also be handled by special methods called scripts.
See L{ScriptableObject} for more details.

The only attribute that absolutely must be provided is L{processID}.
However, subclasses should provide at least the L{name} and L{role} attributes in order for the object to be meaningful to the user.
Attributes such as L{parent}, L{firstChild}, L{next} and L{previous} link an instance to other NVDAObjects in the hierarchy.
In order to facilitate access to text exposed by a widget which supports text content (e.g. an editable text control),
a L{textInfos.TextInfo} should be implemented and the L{TextInfo} attribute should specify this class.

There are two main types of NVDAObject classes:
        * API classes, which provide the core functionality to work with objects exposed using a particular API (e.g. MSAA/IAccessible).
        * Overlay classes, which supplement the core functionality provided by an API class to handle a specific widget or type of widget.
Most developers need only be concerned with overlay classes.
The overlay classes to be used for an instance are determined using the L{findOverlayClasses} method on the API class.
An L{AppModule} can also choose overlay classes for an instance using the L{AppModule.chooseNVDAObjectOverlayClasses} method.
Nested Classes [hide private]
  __metaclass__
  TextInfo
A default TextInfo which is used to enable text review of information about widgets that don't support text content.
Instance Methods [hide private]
 
findOverlayClasses(self, clsList)
Chooses overlay classes which should be added to this object's class structure after the object has been initially instantiated.		 source code
 
__init__(self)
x.__init__(...) initializes x; see help(type(x)) for signature		 source code
boolean
_isEqual(self, other)
Calculates if this object is equal to another object.		 source code
 
__eq__(self, other)
Compaires the objects' memory addresses, their type, and uses NVDAObject._isEqual to see if they are equal.		 source code
 
__ne__(self, other)
The opposite to NVDAObject.__eq__		 source code
 
_get_treeInterceptorClass(self)
If this NVDAObject should use a treeInterceptor, then this property provides the treeInterceptorHandler.TreeInterceptor class it should use.		 source code
treeInterceptorHandler.TreeInterceptor
_get_treeInterceptor(self)
Retreaves the treeInterceptor associated with this object.		 source code
 
_set_treeInterceptor(self, obj)
Specifically sets a treeInterceptor to be associated with this object.		 source code
appModuleHandler.AppModule
_get_appModule(self)
Retreaves the appModule representing the application this object is a part of by asking appModuleHandler.		 source code
basestring
_get_name(self)
The name or label of this object (example: the text of a button).		 source code
int
_get_role(self)
The role or type of control this object represents (example: button, list, dialog).		 source code
basestring
_get_value(self)
The value of this object (example: the current percentage of a scrollbar, the selected option in a combo box).		 source code
basestring
_get_description(self)
The description or help text of this object.		 source code
 
_get_actionCount(self)
Retreaves the number of actions supported by this object.		 source code
basestring
getActionName(self, index=None)
Retreaves the name of an action supported by this object.		 source code
 
doAction(self, index=None)
Performs an action supported by this object.		 source code
 
_get_defaultActionIndex(self)
Retreaves the index of the action that is the default.		 source code
basestring
_get_keyboardShortcut(self)
The shortcut key that activates this object(example: alt+t).		 source code
 
_get_isInForeground(self)
Finds out if this object is currently within the foreground.		 source code
set of int
_get_states(self)
Retreaves the current states of this object (example: selected, focused).		 source code
tuple of int
_get_location(self)
The location of this object on the screen.		 source code
NVDAObject or None
_get_parent(self)
Retreaves this object's parent (the object that contains this object).		 source code
 
_get_container(self)
Exactly like parent, however another object at this same sibling level may be retreaved first (e.g.		 source code
NVDAObject or None
_get_next(self)
Retreaves the object directly after this object with the same parent.		 source code
NVDAObject or None
_get_previous(self)
Retreaves the object directly before this object with the same parent.		 source code
NVDAObject or None
_get_firstChild(self)
Retreaves the first object that this object contains.		 source code
NVDAObject or None
_get_lastChild(self)
Retreaves the last object that this object contains.		 source code
list of NVDAObject
_get_children(self)
Retreaves a list of all the objects directly contained by this object (who's parent is this object).		 source code
int
_get_rowNumber(self)
Retreaves the row number of this object if it is in a table.		 source code
int
_get_columnNumber(self)
Retreaves the column number of this object if it is in a table.		 source code
int
_get_rowCount(self)
Retreaves the number of rows this object contains if its a table.		 source code
int
_get_columnCount(self)
Retreaves the number of columns this object contains if its a table.		 source code
NVDAObject
_get_table(self)
Retreaves the object that represents the table that this object is contained in, if this object is a table cell.		 source code
generator of NVDAObject
_get_recursiveDescendants(self)
Recursively traverse and return the descendants of this object.		 source code
 
_get_presentationType(self) source code
 
_get_simpleParent(self) source code
 
_findSimpleNext(self, useChild=False, useParent=True, goPrevious=False) source code
 
_get_simpleNext(self) source code
 
_get_simplePrevious(self) source code
 
_get_simpleFirstChild(self) source code
 
_get_simpleLastChild(self) source code
int
_get_childCount(self)
Retreaves the number of children this object contains.		 source code
NVDAObject or None
_get_activeChild(self)
Retreaves the child of this object that currently has, or contains, the focus.		 source code
 
setFocus(self)
Tries to force this object to take the focus.		 source code
 
scrollIntoView(self)
Scroll this object into view on the screen if possible.		 source code
NVDAObject or None
_get_labeledBy(self)
Retreaves the object that this object is labeled by (example: the static text label beside an edit field).		 source code
dict
_get_positionInfo(self)
Retreaves position information for this object such as its level, its index with in a group, and the number of items in that group.		 source code
int
_get_processID(self)
Retreaves an identifyer of the process this object is a part of.		 source code
boolean
_get_isProtected(self)
Returns: True if this object is protected (hides its input for passwords), or false otherwise		 source code
int
_get_indexInParent(self)
The index of this object in its parent object.		 source code
NVDAObject
_get_flowsTo(self)
The object to which content flows from this object.		 source code
NVDAObject
_get_flowsFrom(self)
The object from which content flows to this object.		 source code
textInfos.TextInfo
_get_embeddingTextInfo(self)
Retrieve the parent text range which embeds this object.		 source code
bool
_get_isPresentableFocusAncestor(self)
Determine if this object should be presented to the user in the focus ancestry.		 source code
NVDAObject or None
_get_statusBar(self)
Finds the closest status bar in relation to this object.		 source code
 
reportFocus(self)
Announces this object in a way suitable such that it gained focus.		 source code
 
event_typedCharacter(self, ch) source code
 
event_mouseMove(self, x, y) source code
 
event_stateChange(self) source code
 
event_focusEntered(self) source code
 
event_gainFocus(self)
This code is executed if a gain focus event is received by this object.		 source code
 
event_foreground(self)
Called when the foreground window changes.		 source code
 
event_becomeNavigatorObject(self)
Called when this object becomes the navigator object.		 source code
 
event_valueChange(self) source code
 
event_nameChange(self) source code
 
event_descriptionChange(self) source code
 
event_caret(self) source code
 
_get_flatReviewPosition(self)
Locates a TextInfo positioned at this object, in the closest flat review.		 source code
 
_get_basicText(self) source code
 
makeTextInfo(self, position) source code
list of str
_get_devInfo(self)
Information about this object useful to developers.		 source code

Inherited from baseObject.ScriptableObject: bindGesture, bindGestures, clearGestureBindings, getScript

Inherited from baseObject.AutoPropertyObject: invalidateCache

Inherited from baseObject.AutoPropertyObject (private): _getPropertyViaCache

Inherited from object: __delattr__, __format__, __getattribute__, __hash__, __new__, __reduce__, __reduce_ex__, __repr__, __setattr__, __sizeof__, __str__, __subclasshook__

Class Methods [hide private]
DynamicNVDAObjectType
findBestAPIClass(cls, kwargs, relation=None)
Finds out the highest-level APIClass this object can get to given these kwargs, and updates the kwargs and returns the APIClass.		 source code
generator
getPossibleAPIClasses(cls, kwargs, relation=None)
Provides a generator which can generate all the possible API classes (in priority order) that inherit directly from the class it was called on.		 source code
boolean
kwargsFromSuper(cls, kwargs, relation=None)
Finds out if this class can be instanciated from the given super kwargs.		 source code

Inherited from baseObject.AutoPropertyObject: invalidateCaches

Static Methods [hide private]
NVDAObject
objectFromPoint(x, y)
Retreaves an NVDAObject instance representing a control in the Operating System at the given x and y coordinates.		 source code
NVDAObject
objectWithFocus()
Retreaves the object representing the control currently with focus in the Operating System.		 source code
NVDAObject
objectInForeground()
Retreaves the object representing the current foreground control according to the Operating System.		 source code
Class Variables [hide private]
  cachePropertiesByDefault = True
  beTransparentToMouse = False
If true then NVDA will never consider the mouse to be on this object, rather it will be on an ancestor.
  tableCellCoordsInName = False
True if the object's name contains the cell coordinates, such as 'A1'.
  presType_unavailable = "unavailable"
  presType_layout = "layout"
  presType_content = "content"
Instance Variables [hide private]
  _mouseEntered
True if the mouse has entered this object (for use in event_mouseMoved)
  textRepresentationLineLength
If an integer greater than 0 then lines of text in this object are always this long.
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

findBestAPIClass(cls, kwargs, relation=None)
Class Method

source code 

Finds out the highest-level APIClass this object can get to given these kwargs, and updates the kwargs and returns the APIClass.

Parameters:
  • relation - the relationship of a possible new object of this type to another object creating it (e.g. parent).
  • type - string
  • kwargs (dictionary) - the arguments necessary to construct an object of the class this method was called on.
Returns: DynamicNVDAObjectType
the new APIClass

getPossibleAPIClasses(cls, kwargs, relation=None)
Class Method

source code 

Provides a generator which can generate all the possible API classes (in priority order) that inherit directly from the class it was called on.

Parameters:
  • relation - the relationship of a possible new object of this type to another object creating it (e.g. parent).
  • type - string
  • kwargs (dictionary) - the arguments necessary to construct an object of the class this method was called on.
Returns: generator
a generator

kwargsFromSuper(cls, kwargs, relation=None)
Class Method

source code 

Finds out if this class can be instanciated from the given super kwargs. If so it updates the kwargs to contain everything it will need to instanciate this class, and returns True. If this class can not be instanciated, it returns False and kwargs is not touched.

Parameters:
  • relation (string) - why is this class being instanciated? parent, focus, foreground etc...
  • kwargs (dict) - the kwargs for constructing this class's super class.
Returns: boolean

findOverlayClasses(self, clsList)

source code 

Chooses overlay classes which should be added to this object's class structure after the object has been initially instantiated. After an NVDAObject class (normally an API-level class) is instantiated, this method is called on the instance to choose appropriate overlay classes. This method may use properties, etc. on the instance to make this choice. The object's class structure is then mutated to contain these classes. initOverlayClass is then called for each class which was not part of the initially instantiated object. This process allows an NVDAObject to be dynamically created using the most appropriate NVDAObject subclass at each API level. Classes should be listed with subclasses first. That is, subclasses should generally call super and then append their own classes to the list. For example: Called on an IAccessible NVDAObjectThe list might contain DialogIaccessible (a subclass of IAccessible), Edit (a subclass of Window).

Parameters:
  • clsList (list of NVDAObject) - The list of classes, which will be modified by this method if appropriate.

objectFromPoint(x, y)
Static Method

source code 

Retreaves an NVDAObject instance representing a control in the Operating System at the given x and y coordinates.

Parameters:
  • x (int) - the x coordinate.
  • y - the y coordinate.
  • y - int
Returns: NVDAObject
The object at the given x and y coordinates.

objectWithFocus()
Static Method

source code 

Retreaves the object representing the control currently with focus in the Operating System. This differens from NVDA's focus object as this focus object is the real focus object according to the Operating System, not according to NVDA.

Returns: NVDAObject
the object with focus.

objectInForeground()
Static Method

source code 

Retreaves the object representing the current foreground control according to the Operating System. This differes from NVDA's foreground object as this object is the real foreground object according to the Operating System, not according to NVDA.

Returns: NVDAObject
the foreground object

__init__(self)
(Constructor)

source code 

x.__init__(...) initializes x; see help(type(x)) for signature

Overrides: object.__init__
(inherited documentation)

_isEqual(self, other)

source code 

Calculates if this object is equal to another object. Used by NVDAObject.__eq__.

Parameters:
  • other (NVDAObject) - the other object to compare with.
Returns: boolean
True if equal, false otherwise.

_get_treeInterceptorClass(self)

source code 

If this NVDAObject should use a treeInterceptor, then this property provides the treeInterceptorHandler.TreeInterceptor class it should use. If not then it should be not implemented.

_get_treeInterceptor(self)

source code 

Retreaves the treeInterceptor associated with this object. If a treeInterceptor has not been specifically set, the treeInterceptorHandler is asked if it can find a treeInterceptor containing this object.

Returns: treeInterceptorHandler.TreeInterceptor
the treeInterceptor

_get_appModule(self)

source code 

Retreaves the appModule representing the application this object is a part of by asking appModuleHandler.

Returns: appModuleHandler.AppModule
the appModule

_get_role(self)

source code 

The role or type of control this object represents (example: button, list, dialog).

Returns: int
a ROLE_* constant from controlTypes

getActionName(self, index=None)

source code 

Retreaves the name of an action supported by this object. If index is not given then the default action will be used if it exists.

Parameters:
  • index (int) - the optional 0-based index of the wanted action.
Returns: basestring
the action's name

doAction(self, index=None)

source code 

Performs an action supported by this object. If index is not given then the default action will be used if it exists.

_get_states(self)

source code 

Retreaves the current states of this object (example: selected, focused).

Returns: set of int
a set of STATE_* constants from controlTypes.

_get_location(self)

source code 

The location of this object on the screen.

Returns: tuple of int
left, top, width and height of the object.

_get_parent(self)

source code 

Retreaves this object's parent (the object that contains this object).

Returns: NVDAObject or None
the parent object if it exists else None.

_get_container(self)

source code 

Exactly like parent, however another object at this same sibling level may be retreaved first (e.g. a groupbox). Mostly used when presenting context such as focus ancestry.

_get_next(self)

source code 

Retreaves the object directly after this object with the same parent.

Returns: NVDAObject or None
the next object if it exists else None.

_get_previous(self)

source code 

Retreaves the object directly before this object with the same parent.

Returns: NVDAObject or None
the previous object if it exists else None.

_get_firstChild(self)

source code 

Retreaves the first object that this object contains.

Returns: NVDAObject or None
the first child object if it exists else None.

_get_lastChild(self)

source code 

Retreaves the last object that this object contains.

Returns: NVDAObject or None
the last child object if it exists else None.

_get_recursiveDescendants(self)

source code 

Recursively traverse and return the descendants of this object. This is a depth-first forward traversal.

Returns: generator of NVDAObject
The recursive descendants of this object.

_get_activeChild(self)

source code 

Retreaves the child of this object that currently has, or contains, the focus.

Returns: NVDAObject or None
the active child if it has one else None

_get_labeledBy(self)

source code 

Retreaves the object that this object is labeled by (example: the static text label beside an edit field).

Returns: NVDAObject or None
the label object if it has one else None.

_get_positionInfo(self)

source code 

Retreaves position information for this object such as its level, its index with in a group, and the number of items in that group.

Returns: dict
a dictionary containing any of level, groupIndex and similarItemsInGroup.

_get_isProtected(self)

source code 
Returns: boolean
True if this object is protected (hides its input for passwords), or false otherwise

_get_indexInParent(self)

source code 

The index of this object in its parent object.

Returns: int
The 0 based index, None if there is no parent.
Raises:
  • NotImplementedError - If not supported by the underlying object.

_get_flowsTo(self)

source code 

The object to which content flows from this object.

Returns: NVDAObject
The object to which this object flows, None if none.
Raises:
  • NotImplementedError - If not supported by the underlying object.

_get_flowsFrom(self)

source code 

The object from which content flows to this object.

Returns: NVDAObject
The object from which this object flows, None if none.
Raises:
  • NotImplementedError - If not supported by the underlying object.

_get_embeddingTextInfo(self)

source code 

Retrieve the parent text range which embeds this object. The returned text range will have its start positioned on the embedded object character associated with this object. That is, calling textInfos.TextInfo.getEmbeddedObject() on the returned text range will return this object.

Returns: textInfos.TextInfo
The text range for the embedded object character associated with this object or None if this is not an embedded object.
Raises:
  • NotImplementedError - If not supported.

_get_isPresentableFocusAncestor(self)

source code 

Determine if this object should be presented to the user in the focus ancestry.

Returns: bool
True if it should be presented in the focus ancestry, False if not.

_get_statusBar(self)

source code 

Finds the closest status bar in relation to this object.

Returns: NVDAObject or None
the found status bar else None

event_foreground(self)

source code 

Called when the foreground window changes. This method should only perform tasks specific to the foreground window changing. event_focusEntered or event_gainFocus will be called for this object, so this method should not speak/braille the object, etc.

_get_devInfo(self)

source code 

Information about this object useful to developers. Subclasses may extend this, calling the superclass property first.

Returns: list of str
A list of text strings providing information about this object useful to developers.

Class Variable Details [hide private]

tableCellCoordsInName

True if the object's name contains the cell coordinates, such as 'A1'. Speech and Braille can choose to in this case not present the actual row and column information as the name is already enough.

Value:
False

   Trees       Indices       Help   
Generated by Epydoc 3.0.1 on Fri Nov 18 17:45:54 2011 http://epydoc.sourceforge.net