Trees       Indices       Help   
SUE - Revision 232
Package AccessEngine :: Module AETier :: Class AETier
[hide private]
[frames] | no frames]

Class AETier

source code

object --+
         |
        AETier
Manages the AEScripts for a single instance of a running program (a process). Supports the addition and removal of AEScripts from its stack. Executes script tasks registered in each AEScript in response to AEEvents. Provides methods to assist AEScripts in finding registered tasks throughout the AETier.

Instance Methods [hide private]
 
__init__(self, name, aid, por)
Stores a reference to the AETierManager that created this AETier.		 source code
 
close(self)
Clears all AEScripts and closes them.		 source code
 
clearState(self)
Clears all stored temp_data, the chain_stack, task_history, and the show flag.		 source code
string
getName(self)
Returns: Name of this AETier (i.e.		 source code
opaque
getIdentity(self)
Returns: Unique identifier for this AETier		 source code
AEPor
getPointer(self)
Gets the user AEPor for this AETier.		 source code
 
setPointer(self, por)
Sets the user AEPor for this AETier.		 source code
AEPor
getFocus(self)
Gets the application focus AEPor for this AETier.		 source code
3-tuple of integer, string, integer
getLastKey(self)
Gets the last key code, key sym, and key modifiers.		 source code
object
getTempVal(self, name)
Gets data from temp_data.		 source code
 
setTempVal(self, name, value)
Stores data for the duration of the execution of an AEEvent.		 source code
 
setShow(self, show)
Sets whether show methods should be called on the AETierManager when handling events or not based on the presence of AEMonitors in the manager.		 source code
 
getEventLayer(self) source code
 
pushScript(self, *scripts)
Adds one or more AEScripts to the top of the stack.		 source code
 
insertScript(self, index, *scripts)
Adds one AEScript to the stack at the insertion index.		 source code
 
popScript(self, *indices)
Removes one or more AEScripts from the stack given their indices.		 source code
 
clearScripts(self)
Removes all AEScripts from the stack.		 source code
list of AEScript
getScripts(self)
Gets all AEScripts pushed onto this AETier in execution order.		 source code
 
setEventInterest(self, kind, wants)
Updates the wanted_events dictionary to indicate that a task in a AEScript in this AETier has been registered for a particular kind of AEEvent.		 source code
 
addTaskRef(self, key, script)
Adds a key that can be used later to quickly look up a reference to a AEScript in this AETier.		 source code
 
removeTaskRef(self, task_key)
Removes a key used to quickly look up a reference to a AEScript in this AETier.		 source code
list of tuple ('task name', 'script name')
getRegisteredTasks(self)
Gets the keys of all script tasks currently registered in this AETier.		 source code
list of tuples ('Task Identitiy', script.getClassName())
findRegisteredTasks(self, task_name)
Finds all tasks with the given name over all scripts in this tier.		 source code
list of functions [exec_function, update_function]
getRegisteredTaskFunctions(self, task_key)
Gets a task with the given key.		 source code
boolean
isTaskRegistered(self, task_key)
Looks whether a task is already registered.		 source code
2-tuple of string
getAnchor(self)
Gets the identity of the task to which the current task is chained and its corresponding AEScript.		 source code
 
addChainRef(self, target, script)
Adds a weak reference to a AEScript as one to check for tasks which are part of a the chain for the target.		 source code
 
removeChainRef(self, target, script)
Removes a weak reference to a AEScript as one to no longer check for tasks which are part of the chain for the target.		 source code
boolean
wantsEvent(self, event)
Gets if this AETier wants a particular kind of AEEvent given that one of its AEScripts has a task that wants to handle it.		 source code
function
getChooserTask(self, task_key)
Gets a task registered under a particular key set to execute in response to events.		 source code
tuple of ('task name', 'script name')
getCommandTask(self, gesture_list)
Gets a script task registered to execute in response to the AEInput.Gesture.		 source code
list of tuple ('task name', 'script name')
getEventTasks(self, event_type, task_layer)
Gets all tasks registered to handle the given type of event on the given layer by iterating through the registered {Script}s.		 source code
3-tuple of list, task key, list
getChainedTasks(self, target_key)
Gets all tasks linked to the target by iterating through AEScript references established by addChainRef.		 source code
list of 2-tuple of string
getHistory(self)
Gets the entire linear history of tasks that have executed and the AEScripts they are in.		 source code
list of string
getTaskHistory(self)
Gets the identities of all tasks that have executed in response to the event currently being processed.		 source code
list of string
getScriptHistory(self)
Gets the class names of all AEScripts that have executed in response to the event currently being processed.		 source code
boolean
_executeTask(self, por, layer, task_key, task_params, propagate, script=None)
Executes the given task in response to the given AEEvent.		 source code
 
manageChain(self, por, layer, task_key, task_params, propagate, chain)
Executes all script tasks chained to the given task, recursively if chain=True.		 source code
 
manageEvent(self, event)
Manages an event by iterating through the AEScript stack (top to bottom) and checking for registered tasks of the given type.		 source code
 
manageGesture(self, event, count)
Manages an event by getting the AEInput.Gesture that triggered it and locating a task registered to execute in response to it.		 source code
 
manageTimerTask(self, event)
Manages a TimerAlert event by locating a task registered to execute in response to it.		 source code
 
manageChooserTask(self, event)
Manages an event by locating a task under a particular key (not keyboard key, but some immutable identifier) registered to execute in response to it.		 source code
 
managePrivate(self, event)
Pulls private data from an event and stores it in appropriate instance variables.		 source code

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

Instance Variables [hide private]
opaque aid
ID uniquely identifying this AETier from all other AETiers
dictionary chain_refs
References to AEScripts keyed by task names.
list of tuple chain_stack
Stack of task names currently executing in one or more chains before, after, or around one or more anchors :
integer event_layer
AEPor focus_por
Point of regard for the application focus
3-tuple of integer, string, integer last_key
Stores the key code, key sym, and modifiers for the last key pressed
string name
Name of this AETier
AEPor pointer_por
Pointer of regard for the user focus
weakref.WeakValueDictionary script_refs
References to AEScripts keyed by task names, commands, identifiers, etc.
list [AEScript] scripts
List of AEScripts treated as a stack (last in, first executed)
boolean show
Call show* methods on AETierManager to log events? Set by the AETierManager based on whether monitors are loaded or not.
list of tuple task_history
Stack of task and AEScript names having already executed in response to an AEEvent, including all chained tasks and all tasks executed from within other tasks :
dictionary temp_data
Arbitrary name/value pairs stored by tasks executing in this AETier in response to a single event.
AEPor virtual_por
review pointer
dictionary wanted_events
Lookup table for what AEEvents are desired by any task in any AEScript in this AETier.
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self, name, aid, por)
(Constructor)

source code 
Stores a reference to the AETierManager that created this AETier. Creates an empty list of AEScripts. Initializes the stored focus AEPor to None and the pointer AEPor to the application. Creates the weak dictionary for AEScript tasks and stores other information about the AETier.
Parameters:
  • name (string) - Name of this AETier
  • aid (opaque) - ID uniquely identifying this AETier from all other AETiers
  • por (AEPor) - First point of regard to the application represented by this AETier. Typically, the top most accessible.
Overrides: object.__init__

getName(self)

source code 
Returns: string
Name of this AETier (i.e. name of the app with which it is associated)

getIdentity(self)

source code 
Returns: opaque
Unique identifier for this AETier

getPointer(self)

source code 
Gets the user AEPor for this AETier.
Returns: AEPor
Point of regard of user attention

setPointer(self, por)

source code 
Sets the user AEPor for this AETier.
Parameters:
  • por (AEPor) - Point of regard of user attention

getFocus(self)

source code 
Gets the application focus AEPor for this AETier.
Returns: AEPor
Point of regard of application focus

getLastKey(self)

source code 
Gets the last key code, key sym, and key modifiers. Useful for dealing with applications that do a poor job of synthesizing caret and text events.
Returns: 3-tuple of integer, string, integer
The key code, key sym, and modifiers for the last key pressed

getTempVal(self, name)

source code 
Gets data from temp_data.
Parameters:
  • name (immutable) - Name of the stored data
Returns: object
Value stored under the given name
Raises:
  • KeyError - When no data is stored under the given name

setTempVal(self, name, value)

source code 
Stores data for the duration of the execution of an AEEvent.
Parameters:
  • name (immutable) - Name to associate with the value
  • value (object) - Any value to store

setShow(self, show)

source code 
Sets whether show methods should be called on the AETierManager when handling events or not based on the presence of AEMonitors in the manager.
Parameters:
  • show (boolean) - Call show methods to notify monitors?

pushScript(self, *scripts)

source code 
Adds one or more AEScripts to the top of the stack. If more than one AEScript is specified, the last specified AEScript will be at the top of the stack when this method completes. That is, the behavior of pushing more than one AEScript at a time is the same as if each AEScript were pushed individually.
Parameters:

insertScript(self, index, *scripts)

source code 
Adds one AEScript to the stack at the insertion index. Negative indices are valid per Python list convention.
Parameters:
  • index (integer) - Index at which the AEScript should be inserted in the stack
  • scripts (list of AEScript) - AEScripts to add

popScript(self, *indices)

source code 
Removes one or more AEScripts from the stack given their indices. Negative indices are valid per Python list convention. Calls AEScript.AEScript.close on each to ensure they have a chance to persist state.
Parameters:
  • indices (list of integer) - Indices of AEScripts to remove
Raises:
  • IndexError - When the stack is empty
  • ValueError - When a specific index is out of the bounds of the stack

clearScripts(self)

source code 
Removes all AEScripts from the stack. Calls AEScript.AEScript.close on each to ensure they have a chance to persist state.

getScripts(self)

source code 
Gets all AEScripts pushed onto this AETier in execution order.
Returns: list of AEScript
All AEScripts pushed onto this AETier

Note: This method does not return a copy of the stack. Modifications will affect this AETier!

setEventInterest(self, kind, wants)

source code 
Updates the wanted_events dictionary to indicate that a task in a AEScript in this AETier has been registered for a particular kind of AEEvent. This information is used for optimization purposes such that no processing will occur on the event unless at least one task is registered that will use it.
Parameters:
  • kind (AEEvent class) - Kind of AEEvent of interest to a task
  • wants (boolean) - Does a AEScript want an event (i.e. a task is registering for it or no longer want an event (i.e. a task is unregistering for it)?

addTaskRef(self, key, script)

source code 
Adds a key that can be used later to quickly look up a reference to a AEScript in this AETier. Optimization for the getChooserTask, getCommandTask, and getRegisteredTasks methods.
Parameters:
  • key (immutable) - Key under which to hash the AEScript
  • script (AEScript) - Script to store in the hash

removeTaskRef(self, task_key)

source code 
Removes a key used to quickly look up a reference to a AEScript in this AETier. Keys are cleaned up automatically when AEScripts are destroyed. However, this method may be used to manually remove AEScripts at any time.
Parameters:
  • task_key (immutable) - Key under which to hash the AEScript

getRegisteredTasks(self)

source code 
Gets the keys of all script tasks currently registered in this AETier.
Returns: list of tuple ('task name', 'script name')
List of all registered script task keys

findRegisteredTasks(self, task_name)

source code 
Finds all tasks with the given name over all scripts in this tier. None is returned if not found.
Parameters:
  • task_name (string) - the name of the wanted tasks.
Returns: list of tuples ('Task Identitiy', script.getClassName())
list of the found keys or None.

getRegisteredTaskFunctions(self, task_key)

source code 
Gets a task with the given key. None is returned if not found.
Parameters:
  • task_key (tuple of ('task name', 'script name')) - Key to the task to find
Returns: list of functions [exec_function, update_function]
the execute and update functions to the task

isTaskRegistered(self, task_key)

source code 
Looks whether a task is already registered.
Parameters:
  • task_key (tuple of ('task name', 'script name')) - Key to the task to find
Returns: boolean
True when the task is already registered, otherwise False

getAnchor(self)

source code 
Gets the identity of the task to which the current task is chained and its corresponding AEScript. If there is no anchor for the executing task, this method returns None.
Returns: 2-tuple of string
task identity and AEScript class name or None

addChainRef(self, target, script)

source code 
Adds a weak reference to a AEScript as one to check for tasks which are part of a the chain for the target. Optimization for the manageChain method.
Parameters:
  • target (string or tuple of ('task name', 'script name')) - Name of the task to link to
  • script (AEScript) - Script have at least one link in the chain for the target

removeChainRef(self, target, script)

source code 
Removes a weak reference to a AEScript as one to no longer check for tasks which are part of the chain for the target. Optimization for the manageChain method.
Parameters:
  • target (string or tuple of ('task name', 'script name')) - Name of the task to unlink from
  • script (AEScript) - Script have at least one link in the chain for the target

wantsEvent(self, event)

source code 
Gets if this AETier wants a particular kind of AEEvent given that one of its AEScripts has a task that wants to handle it.
Parameters:
  • event (AEEvent) - Event to be tested
Returns: boolean

getChooserTask(self, task_key)

source code 
Gets a task registered under a particular key set to execute in response to events. None is returned if not found.
Parameters:
  • task_key (integer) - Unique ID for locating a registered task
Returns: function
task functions to execute in response to the event or None

getCommandTask(self, gesture_list)

source code 
Gets a script task registered to execute in response to the AEInput.Gesture. None is returned if not found.
Parameters:
  • gesture_list (AEInput.Gesture) - Gestures and device expressed as a list of virtual key codes
Returns: tuple of ('task name', 'script name')
Name of the task to execute in response to the input gesture or None if no task registered to execute

getEventTasks(self, event_type, task_layer)

source code 
Gets all tasks registered to handle the given type of event on the given layer by iterating through the registered {Script}s. The tasks are returned in the order they will be executed both within and across AEScripts in this AETier.
Parameters:
  • event_type (AEEvent class) - Desired type of AEEvent
  • task_layer (integer) - Layer on which the desired tasks are registered
Returns: list of tuple ('task name', 'script name')
List of all tasks registered to handle the given type of event on the given layer

getChainedTasks(self, target_key)

source code 
Gets all tasks linked to the target by iterating through AEScript references established by addChainRef. The tasks are returned in the order in which they were registered within a AEScript. Ordering is undefined across AEScripts within a chain segment.
Parameters:
  • target_key (tuple of string ('task name', 'script name')) - Name and script of the task to link to
Returns: 3-tuple of list, task key, list
task keys for before, around, and after segments
Raises:
  • KeyError - When the target has no chained tasks

getHistory(self)

source code 
Gets the entire linear history of tasks that have executed and the AEScripts they are in.
Returns: list of 2-tuple of string
List of task identities and AEScript class names

getTaskHistory(self)

source code 

Gets the identities of all tasks that have executed in response to the event currently being processed. This includes all chained tasks and all tasks executed using AEScript.doTask flattened into a linear history.

If any task that executed did not have an identity, None is substituted in its place.

The history is ordered from the first task to respond to an event to the most recent task to respond, including the current task.
Returns: list of string
Identities of the tasks

getScriptHistory(self)

source code 

Gets the class names of all AEScripts that have executed in response to the event currently being processed. The contents of the list returned by this method have a one-to-one pairing with the list contents from getTaskHistory.

The history is ordered from the first AEScript to respond to an event to the most recent AEScript to respond, including the current AEScript.
Returns: list of string
Class names of the AEScripts

_executeTask(self, por, layer, task_key, task_params, propagate, script=None)

source code 
Executes the given task in response to the given AEEvent.
Parameters:
  • por (AEPor) - Point of regard where the event occurred
  • layer (integer) - Layer on which the AEEvent occurred, one of AEConstants.Event.LAYER_FOCUS, AEConstants.Event.LAYER_TIER, AEConstants.Event.LAYER_BACKGROUND
  • task_key (tuple of string ('task name', 'script name')) - A task registered to handle the given event
  • task_params (dictionary) - Keyword arguments to be provided to the task function as parameters
  • propagate (boolean) - Should this event be propagated to the tasks execute function or should we call the tasks update function instead for housekeeping?
  • script (AEScript) - The AEScript containing the task
Returns: boolean
Should the next registered task be executed or only updated?

manageChain(self, por, layer, task_key, task_params, propagate, chain)

source code 
Executes all script tasks chained to the given task, recursively if chain=True.
Parameters:
  • por (AEPor) -
  • layer (integer) - Layer in which to execute the task, one of AEConstants.Event.LAYER_FOCUS, AEConstants.Event.LAYER_TIER, AEConstants.Event.LAYER_BACKGROUND
  • task_key (tuple of string ('task name', 'script name')) - Key of the task to execute
  • task_params (dictionary) - Keyword data to pass to the task function as parameters on execution or update
  • propagate (boolean) - Should chained tasks be executed or updated?
  • chain (boolean) - Execute all tasks chained to the one named or not?

Note: This method is purposely long because much code that could be refactored into other methods is inlined for performance reasons.

manageEvent(self, event)

source code 
Manages an event by iterating through the AEScript stack (top to bottom) and checking for registered tasks of the given type. Executes the registered tasks (last registered, first executed) in each AEScript until one of the following conditions is met:
  • All tasks have executed
  • A task returns False
  • A task raises an exception

In the latter two cases, no additional tasks in the current AEScript or additional AEScripts in this AETier are executed. Instead the update methods are called to allow housekeeping operations (e.g updating state) to be performed.

If a task returns neither True or False (e.g. it returns None) a warning is logged and the return value is treated as if it were True. This likely means the task forgot to specify a return value.
Parameters:

manageGesture(self, event, count)

source code 
Manages an event by getting the AEInput.Gesture that triggered it and locating a task registered to execute in response to it. If a task could not be found for the given event, the task registered for invalid gestures is executed instead.
Parameters:
  • event (AEEvent.InputGesture) - Event to process
  • count (integer) - Number of times this gesture has been issued without interruption

manageTimerTask(self, event)

source code 
Manages a TimerAlert event by locating a task registered to execute in response to it.
Parameters:
  • event (AEEvent) - Event to process

manageChooserTask(self, event)

source code 
Manages an event by locating a task under a particular key (not keyboard key, but some immutable identifier) registered to execute in response to it.
Parameters:
  • event (AEEvent) - Event to process

managePrivate(self, event)

source code 
Pulls private data from an event and stores it in appropriate instance variables. Does not forward the event to AEScripts and tasks. Rather, the stored information is made public through AccessEngineAPI methods.
Parameters:
  • event (AEEvent) - Event to process

Instance Variable Details [hide private]

chain_refs

References to AEScripts keyed by task names. Many to many mapping. See addChainRef and removeChainRef. : 
Dictionary {
  key: ('Task Identity', script.getClassName()), 
  value: { key: Script, value: None}
}
Type:
dictionary

chain_stack

Stack of task names currently executing in one or more chains before, after, or around one or more anchors : 
 Tuple ('Task Identity', script.getClassName())
Type:
list of tuple

script_refs

References to AEScripts keyed by task names, commands, identifiers, etc. Many to one mapping. See addTaskRef and removeTaskRef.: 
 WeakValueDictionary {
   key: ('Task Identity', script.getClassName()), value: Script;
   key: id(Chooser), value: Script;
   key: L{AEInput.GestureList}, value: Script
 }
Type:
weakref.WeakValueDictionary

show

Call show* methods on AETierManager to log events? Set by the AETierManager based on whether monitors are loaded or not. Optimization.
Type:
boolean

task_history

Stack of task and AEScript names having already executed in response to an AEEvent, including all chained tasks and all tasks executed from within other tasks : 
 Tuple ('Task Identity', script.getClassName())
Type:
list of tuple

temp_data

Arbitrary name/value pairs stored by tasks executing in this AETier in response to a single event. The data is persistent until the event has been handled by all tasks at which time it is cleared. : 
 Dictionary {
   key: keyName immutable, 
   value: object
 }
Type:
dictionary

wanted_events

Lookup table for what AEEvents are desired by any task in any AEScript in this AETier. Used to optimize event dispatch and processing. Unwanted events are ignored. : 
 Dictionary {
   key: <class 'AEEvent-Class-Type'>,
   value: integer
 }
Type:
dictionary

   Trees       Indices       Help   
SUE - Revision 232
Generated by Epydoc 3.0beta1 on Mon Jun 30 13:05:58 2008 http://epydoc.sourceforge.net