Trees       Indices       Help   
Module Tier :: Class Tier
[hide private]
[frames] | no frames]

Class Tier

source code

object --+
         |
        Tier

Manages the Perks for a single instance of a running program (a process). Supports the addition and removal of Perks from its stack. Executes Tasks registered in each Perk in response to AEEvents. Provides methods to assist Perks and Tasks in finding registered Tasks throughout the Tier.

Instance Methods [hide private]
 
__init__(self, tier_manager, name, aid, por)
Stores a reference to the TierManager that created this Tier.		 source code
 
close(self)
Clears all Perks and closes them.		 source code
 
setShow(self, show)
Sets whether show methods should be called on the TierManager when handling events or not based on the presence of AEMonitors in the manager.		 source code
POR
getPointer(self)
Gets the user POR for this Tier.		 source code
 
setPointer(self, por)
Sets the user POR for this Tier.		 source code
POR
getFocus(self)
Gets the application focus POR for this Tier.		 source code
list of 2-tuple of string
getHistory(self)
Gets the entire linear history of Tasks that have executed and the Perks they are in.		 source code
2-tuple of string
getAnchor(self)
Gets the identity of the Task to which the current Task is chained and its corresponding Perk.		 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
 
clearState(self)
Clears all stored temp_data, the chain_stack, task_history, and the show flag.		 source code
 
addChainRef(self, target, perk)
Adds a weak reference to a Perk as one to check for Tasks which are part of a the chain for the target.		 source code
 
removeChainRef(self, target, perk)
Removes a weak reference to a Perk as one to no longer check for Tasks which are part of the chain for the target.		 source code
 
addTaskRef(self, key, perk)
Adds a key that can be used later to quickly look up a reference to a Perk in this Tier.		 source code
 
removeTaskRef(self, key)
Removes a key used to quickly look up a reference to a Perk in this Tier.		 source code
string
getName(self)
Returns: Name of this Tier (i.e.		 source code
opaque
getIdentity(self)
Returns: Unique identifier for this Tier		 source code
 
pushPerk(self, ae, *perks)
Adds one or more Perks to the top of the stack.		 source code
 
insertPerk(self, ae, index, *perks)
Adds one Perk to the stack at the insertion index.		 source code
 
popPerk(self, *indices)
Removes one or more Perks from the stack given their indices.		 source code
 
clearPerks(self)
Removes all Perks from the stack.		 source code
list of Perk
getPerks(self)
Gets all Perks pushed onto this Tier in execution order.		 source code
 
setEventInterest(self, kind, wants)
Updates the wanted_events dictionary to indicate that a Task in a Perk in this Tier has been registered for a particular kind of AEEvent.		 source code
 
wantsEvent(self, event)
Gets if this Tier wants a particular kind of AEEvent given that one of its Perks has a Task that wants to handle it.		 source code
Task
getKeyedTask(self, key)
Gets a Task registered under a particular key set to execute in response to events.		 source code
string
getCommandTask(self, gesture_list)
Gets a Task registered to execute in response to the AEInput.Gesture.		 source code
Task.Base.Task
getNamedTask(self, name)
Gets a Task with the given name by iterating through the registered Perks until one is found containing a Task registered under the given name.		 source code
list of Task.Base.Task
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 {Perk}s.		 source code
3-tuple of list, string, list
getChainedTasks(self, target)
Gets all Tasks linked to the target by iterating through Perk references established by addChainRef.		 source code
boolean
_executeTask(self, task, perk, por, layer, params, propagate)
Executes the given Task in response to the given AEEvent.		 source code
 
manageChain(self, por, name, task, perk, layer, task_params, propagate, chain)
Executes all Tasks chained the the given Task, recursively if chain=True.		 source code
 
manageEvent(self, event)
Manages an event by iterating through the Perk 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
 
manageKeyedTask(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 Tier from all other Tiers
dictionary chain_refs
References to Perks keyed by task names.
list chain_stack
Stack of Task and Perk names currently executing in one or more chains before, after, or around one or more anchors
POR 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 Tier
weakref.WeakValueDictionary perk_refs
References to Perks keyed by task names, commands, identifiers, etc.
list perks
List of Perks treated as a stack (last in, first executed)
POR pointer_por
Pointer of regard for the user focus
boolean show
Call show* methods on TierManager to log events? Set by the TierManager based on whether monitors are loaded or not.
list task_history
Stack of Task and Perk 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 Tier in response to a single event.
TierManager tier_manager
TierManager that created this Tier
dictionary wanted_events
Lookup table for what AEEvents are desired by any Task in any Perk in this Tier.
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

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

source code 

Stores a reference to the TierManager that created this Tier. Creates an empty list of Perks. Initializes the stored focus POR to None and the pointer POR to the application. Creates the weak dictionary for Perk Tasks and stores other information about the Tier.

Parameters:
  • tier_manager (TierManager) - Manager that created this Tier
  • name (string) - Name of this Tier
  • aid (opaque) - ID uniquely identifying this Tier from all other Tiers
  • por (POR) - First point of regard to the application represented by this Tier. Typically, the top most accessible.
Overrides: object.__init__

setShow(self, show)

source code 

Sets whether show methods should be called on the TierManager when handling events or not based on the presence of AEMonitors in the manager.

Parameters:
  • show (boolean) - Call show methods to notify monitors?

getPointer(self)

source code 

Gets the user POR for this Tier.

Returns: POR
Point of regard of user attention

setPointer(self, por)

source code 

Sets the user POR for this Tier.

Parameters:
  • por (POR) - Point of regard of user attention

getFocus(self)

source code 

Gets the application focus POR for this Tier.

Returns: POR
Point of regard of application focus

getHistory(self)

source code 

Gets the entire linear history of Tasks that have executed and the Perks they are in.

Returns: list of 2-tuple of string
List of Task identities and Perk class names

getAnchor(self)

source code 

Gets the identity of the Task to which the current Task is chained and its corresponding Perk. If there is no anchor for the executing Task, this method returns None.

Returns: 2-tuple of string
Task identity and Perk class name or None

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

addChainRef(self, target, perk)

source code 

Adds a weak reference to a Perk as one to check for Tasks which are part of a the chain for the target. Optimization for the manageChain method.

Parameters:
  • target (string) - Name of the Task to link to
  • perk (Perk) - Perk have at least one link in the chain for the target

removeChainRef(self, target, perk)

source code 

Removes a weak reference to a Perk 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) - Name of the Task to unlink from
  • perk (Perk) - Perk have at least one link in the chain for the target

addTaskRef(self, key, perk)

source code 

Adds a key that can be used later to quickly look up a reference to a Perk in this Tier. Optimization for the getKeyedTask, getCommandTask, and getNamedTask methods.

Parameters:
  • key (immutable) - Key under which to hash the Perk
  • perk (Perk) - Perk to store in the hash

removeTaskRef(self, key)

source code 

Removes a key used to quickly look up a reference to a Perk in this Tier. Keys are cleaned up automatically when Perks are destroyed. However, this method may be used to manually remove Perks at any time.

Parameters:
  • key (immutable) - Key under which to hash the Perk

getName(self)

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

getIdentity(self)

source code 
Returns: opaque
Unique identifier for this Tier

pushPerk(self, ae, *perks)

source code 

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

Parameters:
  • ae (AccessEngine) - The AccessEngine context to use for initializing the Perk
  • perks (list of Perk) - Perks to add

insertPerk(self, ae, index, *perks)

source code 

Adds one Perk to the stack at the insertion index. Negative indices are valid per Python list convention.

Parameters:
  • ae (AccessEngine) - The AccessEngine context to use for initializing the Perk
  • index (integer) - Index at which the Perk should be inserted in the stack
  • perks (list of Perk) - Perks to add

popPerk(self, *indices)

source code 

Removes one or more Perks from the stack given their indices. Negative indices are valid per Python list convention. Calls Perk.Perk.close on each to ensure they have a chance to persist state.

Parameters:
  • indices (list of integer) - Indices of Perks to remove
Raises:
  • IndexError - When the stack is empty
  • ValueError - When a specific index is out of the bounds of the stack

clearPerks(self)

source code 

Removes all Perks from the stack. Calls Perk.Perk.close on each to ensure they have a chance to persist state.

getPerks(self)

source code 

Gets all Perks pushed onto this Tier in execution order.

Returns: list of Perk
All Perks pushed onto this Tier

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

setEventInterest(self, kind, wants)

source code 

Updates the wanted_events dictionary to indicate that a Task in a Perk in this Tier 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 Perk 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)?

wantsEvent(self, event)

source code 

Gets if this Tier wants a particular kind of AEEvent given that one of its Perks has a Task that wants to handle it.

Parameters:
  • event (AEEvent) - Event to be tested

getKeyedTask(self, 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:
  • key (integer) - Unique ID for locating a registered Task
Returns: Task
Task set to execute in response to the event or None

getCommandTask(self, gesture_list)

source code 

Gets a 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: string
Name of the Task to execute in response to the input gesture or None if no Task registered to execute

getNamedTask(self, name)

source code 

Gets a Task with the given name by iterating through the registered Perks until one is found containing a Task registered under the given name. None is returned if not found.

Parameters:
  • name (string) - Name of the Task to find
Returns: Task.Base.Task
Task with the given name or None

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 {Perk}s. The Tasks are returned in the order they will be executed both within and across Perks in this Tier.

Parameters:
  • event_type (AEEvent class) - Desired type of AEEvent
  • task_layer (integer) - Layer on which the desired Tasks are registered
Returns: list of Task.Base.Task
List of all Tasks registered to handle the given type of event on the given layer

getChainedTasks(self, target)

source code 

Gets all Tasks linked to the target by iterating through Perk references established by addChainRef. The Tasks are returned in the order in which they were registered within a Perk. Ordering is undefined across Perks within a chain segment.

Parameters:
  • target (string) - Name of the Task to link to
Returns: 3-tuple of list, string, list
Task names for before, around, and after segments
Raises:
  • KeyError - When the target has no chained Tasks

_executeTask(self, task, perk, por, layer, params, propagate)

source code 

Executes the given Task in response to the given AEEvent.

Parameters:
Returns: boolean
Should the next registered Task be executed or only updated?
Raises:
  • AssertionError - When the Perk or Task does not preExecute successfully

manageChain(self, por, name, task, perk, layer, task_params, propagate, chain)

source code 

Executes all Tasks chained the the given Task, recursively if chain=True.

Parameters:

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 Perk stack (top to bottom) and checking for registered Tasks of the given type. Executes the registered Tasks (last registered, first executed) in each Perk 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 Perk or additional Perks in this Tier are executed. Instead the Task.Base.Task.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

manageKeyedTask(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 Perks and Tasks. Rather, the stored information is made public through Task.Tools methods.

Parameters:
  • event (AEEvent) - Event to process

Instance Variable Details [hide private]

chain_refs

References to Perks keyed by task names. Many to many mapping. See addChainRef and removeChainRef.
Type:
dictionary

perk_refs

References to Perks keyed by task names, commands, identifiers, etc. Many to one mapping. See addTaskRef and removeTaskRef.
Type:
weakref.WeakValueDictionary

show

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

temp_data

Arbitrary name/value pairs stored by Tasks executing in this Tier 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.
Type:
dictionary

wanted_events

Lookup table for what AEEvents are desired by any Task in any Perk in this Tier. Used to optimize event dispatch and processing. Unwanted events are ignored.
Type:
dictionary

   Trees       Indices       Help   
Generated by Epydoc 3.0beta1 on Mon Jun 4 15:33:25 2007 http://epydoc.sourceforge.net