X-Git-Url: http://review.tizen.org/git/?a=blobdiff_plain;f=pyatspi%2Futils.py;h=fb7cfba591113c76368c8e8f0957eb73662e281a;hb=77e0f05b669f34a8ff16311269e356018f8ee216;hp=8d3b7cc36d7979b15bed14f8dc4e877e40835194;hpb=059285c4a35a5dd7dd2aa9e2fa5458e28a8a66f8;p=platform%2Fcore%2Fuifw%2Fat-spi2-atk.git diff --git a/pyatspi/utils.py b/pyatspi/utils.py index 8d3b7cc..fb7cfba 100644 --- a/pyatspi/utils.py +++ b/pyatspi/utils.py @@ -24,308 +24,308 @@ import state import registry __all__ = [ - "setCacheLevel", - "getCacheLevel", - "clearCache", - "printCache", - "getInterfaceIID", - "getInterfaceName", - "listInterfaces", - "stringToConst", - "stateToString", - "stateToString", - "allModifiers", - "findDescendant", - "findAllDescendants", - "findAncestor", - "getPath", - ] + "setCacheLevel", + "getCacheLevel", + "clearCache", + "printCache", + "getInterfaceIID", + "getInterfaceName", + "listInterfaces", + "stringToConst", + "stateToString", + "stateToString", + "allModifiers", + "findDescendant", + "findAllDescendants", + "findAncestor", + "getPath", + ] def setCacheLevel(level): - pass + pass def getCacheLevel(): - return None + return None def clearCache(): - pass + pass def printCache(): - print "Print cache function is deprecated"; + print "Print cache function is deprecated"; def getInterfaceIID(obj): - """ - Gets the ID of an interface class or object in string format for use in - queryInterface. - - @param obj: Class representing an AT-SPI interface or instance - @type obj: object - @return: IID for the interface - @rtype: string - @raise AttributeError: When the parameter does not provide typecode info - - WARNING!! DEPRECATED!! - - In current D-Bus version of pyatspi this simply returns a null string. - """ - return "" + """ + Gets the ID of an interface class or object in string format for use in + queryInterface. + + @param obj: Class representing an AT-SPI interface or instance + @type obj: object + @return: IID for the interface + @rtype: string + @raise AttributeError: When the parameter does not provide typecode info + + WARNING!! DEPRECATED!! + + In current D-Bus version of pyatspi this simply returns a null string. + """ + return "" def getInterfaceName(obj): - """ - Gets the human readable name of an interface class or object in string - format. - - @param obj: Class representing an AT-SPI interface or instance - @type obj: class - @return: Name of the interface - @rtype: string - @raise AttributeError: When the parameter does not provide typecode info - """ - return obj._dbus_interface.lstrip("org.freedesktop.atspi.") + """ + Gets the human readable name of an interface class or object in string + format. + + @param obj: Class representing an AT-SPI interface or instance + @type obj: class + @return: Name of the interface + @rtype: string + @raise AttributeError: When the parameter does not provide typecode info + """ + return obj._dbus_interface.lstrip("org.freedesktop.atspi.") def listInterfaces(obj): - """ - Gets a list of the names of all interfaces supported by this object. The - names are the short-hand interface names like "Accessible" and "Component", - not the full interface identifiers. - - @param obj: Arbitrary object to query for all accessibility related - interfaces. Must provide a queryInterface method. - @type obj: object - @return: Set of supported interface names - @rtype: set - @raise AttributeError: If the object provide does not implement - queryInterface - """ - return [itf.lstrip("org.freedesktop.atspi.") for itf in obj.interfaces] + """ + Gets a list of the names of all interfaces supported by this object. The + names are the short-hand interface names like "Accessible" and "Component", + not the full interface identifiers. + + @param obj: Arbitrary object to query for all accessibility related + interfaces. Must provide a queryInterface method. + @type obj: object + @return: Set of supported interface names + @rtype: set + @raise AttributeError: If the object provide does not implement + queryInterface + """ + return [itf.lstrip("org.freedesktop.atspi.") for itf in obj.interfaces] def stringToConst(prefix, suffix): - """ - Maps a string name to an AT-SPI constant. The rules for the mapping are as - follows: - - The prefix is captalized and has an _ appended to it. - - All spaces in the suffix are mapped to the _ character. - - All alpha characters in the suffix are mapped to their uppercase. - - The resulting name is used with getattr to look up a constant with that name - in the L{constants} module. If such a constant does not exist, the string - suffix is returned instead. - - This method allows strings to be used to refer to roles, relations, etc. - without direct access to the constants. It also supports the future expansion - of roles, relations, etc. by allowing arbitrary strings which may or may not - map to the current standard set of roles, relations, etc., but may still - match some non-standard role, relation, etc. being reported by an - application. - - @param prefix: Prefix of the constant name such as role, relation, state, - text, modifier, key - @type prefix: string - @param suffix: Name of the role, relation, etc. to use to lookup the constant - @type suffix: string - @return: The matching constant value - @rtype: object - """ - name = prefix.upper()+'_'+suffix.upper().replace(' ', '_') - return getattr(constants, name, suffix) + """ + Maps a string name to an AT-SPI constant. The rules for the mapping are as + follows: + - The prefix is captalized and has an _ appended to it. + - All spaces in the suffix are mapped to the _ character. + - All alpha characters in the suffix are mapped to their uppercase. + + The resulting name is used with getattr to look up a constant with that name + in the L{constants} module. If such a constant does not exist, the string + suffix is returned instead. + + This method allows strings to be used to refer to roles, relations, etc. + without direct access to the constants. It also supports the future expansion + of roles, relations, etc. by allowing arbitrary strings which may or may not + map to the current standard set of roles, relations, etc., but may still + match some non-standard role, relation, etc. being reported by an + application. + + @param prefix: Prefix of the constant name such as role, relation, state, + text, modifier, key + @type prefix: string + @param suffix: Name of the role, relation, etc. to use to lookup the constant + @type suffix: string + @return: The matching constant value + @rtype: object + """ + name = prefix.upper()+'_'+suffix.upper().replace(' ', '_') + return getattr(constants, name, suffix) def stateToString(value): - """ - Converts a state value to a string based on the name of the state constant in - the L{constants} module that has the given value. - - @param value: An AT-SPI state - @type value: Accessibility.StateType - @return: Human readable, untranslated name of the state - @rtype: string - """ - return state.STATE_VALUE_TO_NAME.get(value) + """ + Converts a state value to a string based on the name of the state constant in + the L{constants} module that has the given value. + + @param value: An AT-SPI state + @type value: Accessibility.StateType + @return: Human readable, untranslated name of the state + @rtype: string + """ + return state.STATE_VALUE_TO_NAME.get(value) def relationToString(value): - """ - Converts a relation value to a string based on the name of the state constant - in the L{constants} module that has the given value. - - @param value: An AT-SPI relation - @type value: Accessibility.RelationType - @return: Human readable, untranslated name of the relation - @rtype: string - """ - return relation.RELATION_VALUE_TO_NAME.get(value) + """ + Converts a relation value to a string based on the name of the state constant + in the L{constants} module that has the given value. + + @param value: An AT-SPI relation + @type value: Accessibility.RelationType + @return: Human readable, untranslated name of the relation + @rtype: string + """ + return relation.RELATION_VALUE_TO_NAME.get(value) def allModifiers(): - """ - Generates all possible keyboard modifiers for use with - L{registry.Registry.registerKeystrokeListener}. - """ - mask = 0 - while mask <= (1 << registry.MODIFIER_NUMLOCK): - yield mask - mask += 1 + """ + Generates all possible keyboard modifiers for use with + L{registry.Registry.registerKeystrokeListener}. + """ + mask = 0 + while mask <= (1 << registry.MODIFIER_NUMLOCK): + yield mask + mask += 1 def findDescendant(acc, pred, breadth_first=False): - """ - Searches for a descendant node satisfying the given predicate starting at - this node. The search is performed in depth-first order by default or - in breadth first order if breadth_first is True. For example, - - my_win = findDescendant(lambda x: x.name == 'My Window') - - will search all descendants of x until one is located with the name 'My - Window' or all nodes are exausted. Calls L{_findDescendantDepth} or - L{_findDescendantBreadth} to start the recursive search. - - @param acc: Root accessible of the search - @type acc: Accessibility.Accessible - @param pred: Search predicate returning True if accessible matches the - search criteria or False otherwise - @type pred: callable - @param breadth_first: Search breadth first (True) or depth first (False)? - @type breadth_first: boolean - @return: Accessible matching the criteria or None if not found - @rtype: Accessibility.Accessible or None - """ - if breadth_first: - return _findDescendantBreadth(acc, pred) - - for child in acc: - try: - ret = _findDescendantDepth(acc, pred) - except Exception: - ret = None - if ret is not None: return ret + """ + Searches for a descendant node satisfying the given predicate starting at + this node. The search is performed in depth-first order by default or + in breadth first order if breadth_first is True. For example, + + my_win = findDescendant(lambda x: x.name == 'My Window') + + will search all descendants of x until one is located with the name 'My + Window' or all nodes are exausted. Calls L{_findDescendantDepth} or + L{_findDescendantBreadth} to start the recursive search. + + @param acc: Root accessible of the search + @type acc: Accessibility.Accessible + @param pred: Search predicate returning True if accessible matches the + search criteria or False otherwise + @type pred: callable + @param breadth_first: Search breadth first (True) or depth first (False)? + @type breadth_first: boolean + @return: Accessible matching the criteria or None if not found + @rtype: Accessibility.Accessible or None + """ + if breadth_first: + return _findDescendantBreadth(acc, pred) + + for child in acc: + try: + ret = _findDescendantDepth(acc, pred) + except Exception: + ret = None + if ret is not None: return ret def _findDescendantBreadth(acc, pred): - """ - Internal function for locating one descendant. Called by L{findDescendant} to - start the search. - - @param acc: Root accessible of the search - @type acc: Accessibility.Accessible - @param pred: Search predicate returning True if accessible matches the - search criteria or False otherwise - @type pred: callable - @return: Matching node or None to keep searching - @rtype: Accessibility.Accessible or None - """ - for child in acc: - try: - if pred(child): return child - except Exception: - pass - for child in acc: - try: - ret = _findDescendantBreadth(child, pred) - except Exception: - ret = None - if ret is not None: return ret + """ + Internal function for locating one descendant. Called by L{findDescendant} to + start the search. + + @param acc: Root accessible of the search + @type acc: Accessibility.Accessible + @param pred: Search predicate returning True if accessible matches the + search criteria or False otherwise + @type pred: callable + @return: Matching node or None to keep searching + @rtype: Accessibility.Accessible or None + """ + for child in acc: + try: + if pred(child): return child + except Exception: + pass + for child in acc: + try: + ret = _findDescendantBreadth(child, pred) + except Exception: + ret = None + if ret is not None: return ret def _findDescendantDepth(acc, pred): - """ - Internal function for locating one descendant. Called by L{findDescendant} to - start the search. - - @param acc: Root accessible of the search - @type acc: Accessibility.Accessible - @param pred: Search predicate returning True if accessible matches the - search criteria or False otherwise - @type pred: callable - @return: Matching node or None to keep searching - @rtype: Accessibility.Accessible or None - """ - try: - if pred(acc): return acc - except Exception: - pass - for child in acc: - try: - ret = _findDescendantDepth(child, pred) - except Exception: - ret = None - if ret is not None: return ret - + """ + Internal function for locating one descendant. Called by L{findDescendant} to + start the search. + + @param acc: Root accessible of the search + @type acc: Accessibility.Accessible + @param pred: Search predicate returning True if accessible matches the + search criteria or False otherwise + @type pred: callable + @return: Matching node or None to keep searching + @rtype: Accessibility.Accessible or None + """ + try: + if pred(acc): return acc + except Exception: + pass + for child in acc: + try: + ret = _findDescendantDepth(child, pred) + except Exception: + ret = None + if ret is not None: return ret + def findAllDescendants(acc, pred): - """ - Searches for all descendant nodes satisfying the given predicate starting at - this node. Does an in-order traversal. For example, - - pred = lambda x: x.getRole() == pyatspi.ROLE_PUSH_BUTTON - buttons = pyatspi.findAllDescendants(node, pred) - - will locate all push button descendants of node. - - @param acc: Root accessible of the search - @type acc: Accessibility.Accessible - @param pred: Search predicate returning True if accessible matches the - search criteria or False otherwise - @type pred: callable - @return: All nodes matching the search criteria - @rtype: list - """ - matches = [] - _findAllDescendants(acc, pred, matches) - return matches + """ + Searches for all descendant nodes satisfying the given predicate starting at + this node. Does an in-order traversal. For example, + + pred = lambda x: x.getRole() == pyatspi.ROLE_PUSH_BUTTON + buttons = pyatspi.findAllDescendants(node, pred) + + will locate all push button descendants of node. + + @param acc: Root accessible of the search + @type acc: Accessibility.Accessible + @param pred: Search predicate returning True if accessible matches the + search criteria or False otherwise + @type pred: callable + @return: All nodes matching the search criteria + @rtype: list + """ + matches = [] + _findAllDescendants(acc, pred, matches) + return matches def _findAllDescendants(acc, pred, matches): - """ - Internal method for collecting all descendants. Reuses the same matches - list so a new one does not need to be built on each recursive step. - """ - for child in acc: - try: - if pred(child): matches.append(child) - except Exception: - pass - _findAllDescendants(child, pred, matches) - + """ + Internal method for collecting all descendants. Reuses the same matches + list so a new one does not need to be built on each recursive step. + """ + for child in acc: + try: + if pred(child): matches.append(child) + except Exception: + pass + _findAllDescendants(child, pred, matches) + def findAncestor(acc, pred): - """ - Searches for an ancestor satisfying the given predicate. Note that the - AT-SPI hierarchy is not always doubly linked. Node A may consider node B its - child, but B is not guaranteed to have node A as its parent (i.e. its parent - may be set to None). This means some searches may never make it all the way - up the hierarchy to the desktop level. - - @param acc: Starting accessible object - @type acc: Accessibility.Accessible - @param pred: Search predicate returning True if accessible matches the - search criteria or False otherwise - @type pred: callable - @return: Node matching the criteria or None if not found - @rtype: Accessibility.Accessible - """ - if acc is None: - # guard against bad start condition - return None - while 1: - if acc.parent is None: - # stop if there is no parent and we haven't returned yet - return None - try: - if pred(acc.parent): return acc.parent - except Exception: - pass - # move to the parent - acc = acc.parent + """ + Searches for an ancestor satisfying the given predicate. Note that the + AT-SPI hierarchy is not always doubly linked. Node A may consider node B its + child, but B is not guaranteed to have node A as its parent (i.e. its parent + may be set to None). This means some searches may never make it all the way + up the hierarchy to the desktop level. + + @param acc: Starting accessible object + @type acc: Accessibility.Accessible + @param pred: Search predicate returning True if accessible matches the + search criteria or False otherwise + @type pred: callable + @return: Node matching the criteria or None if not found + @rtype: Accessibility.Accessible + """ + if acc is None: + # guard against bad start condition + return None + while 1: + if acc.parent is None: + # stop if there is no parent and we haven't returned yet + return None + try: + if pred(acc.parent): return acc.parent + except Exception: + pass + # move to the parent + acc = acc.parent def getPath(acc): - """ - Gets the path from the application ancestor to the given accessible in - terms of its child index at each level. - - @param acc: Target accessible - @type acc: Accessibility.Accessible - @return: Path to the target - @rtype: list of integer - @raise LookupError: When the application accessible cannot be reached - """ - path = [] - while 1: - if acc.parent is None: - path.reverse() - return path - try: - path.append(acc.getIndexInParent()) - except Exception: - raise LookupError - acc = acc.parent + """ + Gets the path from the application ancestor to the given accessible in + terms of its child index at each level. + + @param acc: Target accessible + @type acc: Accessibility.Accessible + @return: Path to the target + @rtype: list of integer + @raise LookupError: When the application accessible cannot be reached + """ + path = [] + while 1: + if acc.parent is None: + path.reverse() + return path + try: + path.append(acc.getIndexInParent()) + except Exception: + raise LookupError + acc = acc.parent