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

Class AEOutput

source code

                     object --+    
                              |    
AEUserInterface.AEUserInterface --+
                                  |
                                 AEOutput
Defines the base class for all output devices. All output devices used by SUE should derive from this class and should implement the methods defined here. All methods defined here raise NotImplementedError to ensure that derived classes create appropriate implementions.

Nested Classes [hide private]
AEOutput.Style class STYLE
Style class to use when constructing style objects for this device.
Instance Methods [hide private]
 
__init__(self)
Initializes the styles dictionary and default style object.		 source code
list of string
getCapabilities(self)
Gets a list of strings representing the capabilities of this device.		 source code
 
loadStyles(self)
Called after the init method by the AEDeviceManager to ensure that the device is functioning before time is spent unserializing its style data.		 source code
 
saveStyles(self)
Persists styles to disk.		 source code
 
setStyle(self, key, style)
Stores the style object under the given key.		 source code
AEState
getStyle(self, key)
Gets the style object stored under the given key.		 source code
AEOutput.Style
getDefaultStyle(self)
Gets the default style of the device.		 source code
list of AEOutput.Style
createDistinctStyles(self, num_groups, num_layers)
Creates a default set of distinct styles for this device.		 source code
 
init(self)
Called after the instance is created to initialize the device.		 source code
 
postInit(self)
Called after the init method and after either loadStyles or createDistinctStyles.		 source code
 
close(self)
Closes an initialized output device.		 source code
AEOutput
getProxy(self)
Gets the object that the AEDeviceManager will use to communicate with this device.		 source code
object
send(self, name, value, style=None)
Sends arbitrary data to a device.		 source code
boolean
isActive(self)
Indicates whether the device is active (e.g.		 source code
string
getRole(self)
Gets the role of this device		 source code

Inherited from AEUserInterface.AEUserInterface: getClassName, getDescription, getName, getPath

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

Class Variables [hide private]
boolean USE_THREAD = None
Should this device use a separate thread to queue output? Devices that block while doing output (e.g.
string COMMAND_CHARS = ''
String of characters that are treated as commands on the device implementing this interface.
  ROLE = 'output'
Instance Variables [hide private]
dictionary styles
Mapping from arbitrary, immutable keys to style objects
Properties [hide private]

Inherited from object: __class__

Method Details [hide private]

__init__(self)
(Constructor)

source code 
Initializes the styles dictionary and default style object.
Overrides: object.__init__

getCapabilities(self)

source code 

Gets a list of strings representing the capabilities of this device. Typical output capabilities include "audio" and "braille" though others are certainly possible.

The AEDeviceManager will only load a device if another device doesn't already provide all of its capabilities.
Returns: list of string
Lowercase names of output capabilities

loadStyles(self)

source code 

Called after the init method by the AEDeviceManager to ensure that the device is functioning before time is spent unserializing its style data.

Calls the init method on the default style object and provides it with a reference to this initialized device. Then tries to load the persisted setting values from disk. If that fails, the AEDeviceManager will try to call createDistinctStyles instead.
Raises:
  • KeyError - When styles have not previously been persisted for this device
  • OSError - When the profile file cannot be opened or read

Note: This method should not be overriden by a subclass. See postInit if you need to run code after the styles are created or restored from disk.

saveStyles(self)

source code 
Persists styles to disk. Called after the close method by the AEDeviceManager to ensure the device is properly shutdown before serializing its data.
Raises:
  • KeyError - When styles have not previously been persisted for this device
  • OSError - When the profile file cannot be opened or read

Note: This method should not be overriden by a subclass.

setStyle(self, key, style)

source code 
Stores the style object under the given key. The style object should be one previously generated by this device (e.g. using createDistinctStyles) but it is not an enforced requirement. Always makes the style clean before storing it.
Parameters:
  • key (immutable) - Any immutable object
  • style (AEState) - AEOutput subclass of AEState

getStyle(self, key)

source code 
Gets the style object stored under the given key. If the key is unknown, returns an empty flyweight backed by the default style and stores the new style in styles.
Parameters:
  • key (immutable) - Any immutable object
Returns: AEState
AEOutput subclass of AEState

getDefaultStyle(self)

source code 
Gets the default style of the device.
Returns: AEOutput.Style
Default style of the device

createDistinctStyles(self, num_groups, num_layers)

source code 

Creates a default set of distinct styles for this device. The device should instantiate AEOutput.Style objects having properties that reflect the capabilities of this device, leaving any unsupported fields set to the value of None. A total number of num_groups + num_layers style objects should be returned.

The properties of the style object should be set so as to distinguish content presented using the style. For instance, audio devices may distinguish styles in the following recommended manner:
  • Create a total of num_groups styles with different voices and pitches.
  • If the device supports multiple channels,
    • Duplicate the styles num_layers times assigning each set of duplicates to the same channel.
  • If the device does not support multiple channels,
    • Duplicate the styles num_layers times.

For Braille and magnification devices, don't implement this method unless you have some creative way of making the device respond differently to the semantic tags defined in AEConstants.

The total number of requested styles (num_groups * num_layers) must be returned. If the device cannot honor the request for the number of distinct styles it is asked to generate, it may duplicate styles it has already created using AEState.Base.AEState.copy to fulfill the quota.

The device is not expected to create distinct styles across invocations of this method. This method should only be called once by AEDeviceManager to create a default set of styles for the device if the manager cannot load previously persisted settings from disk. If this method is not implemented, calls to getStyle during normal operation of the AEDeviceManager will end up making copies based on the default style.
Parameters:
  • num_groups (integer) - Number of sematic groups the requestor would like to represent using distinct styles
  • num_layers (integer) - Number of content origins (e.g. output originating from a background task versus the focus) the requestor would like to represent using distinct styles
Returns: list of AEOutput.Style
New styles
Raises:
  • NotImplementedError - When not overridden in a subclass

init(self)

source code 
Called after the instance is created to initialize the device. May be called to re-initialize the device after a call to close.
Raises:
  • NotImplementedError - When not overridden in a subclass
  • Error.InitError - When a communication or state problem exists for the specific device

postInit(self)

source code 
Called after the init method and after either loadStyles or createDistinctStyles. Override this method to perform additional initilization after the setting values are available.
Raises:
  • Error.InitError - When a communication or state problem exists for the specific device

close(self)

source code 
Closes an initialized output device.
Raises:
  • NotImplementedError - When not overridden in a subclass

getProxy(self)

source code 
Gets the object that the AEDeviceManager will use to communicate with this device. The returned object may either be a proxy (e.g. a thread) or this device itself.
Returns: AEOutput
An output object that implements this class
Raises:
  • NotImplementedError - When not overridden in a subclass

send(self, name, value, style=None)

source code 

Sends arbitrary data to a device. The device must recognize the name in order to decide what to do with the value data. If given, the style object is used to decide how the data should be presented if it is content to be rendered.

This is a generic method which receives all content and commands to be rendered and executed on a device. Standard name identifiers should be used whenever possible. For instance, AEConstants.Output.CMD_STOP and AEConstants.Output.CMD_TALK. However, device specific names and values are certainly possible.
Parameters:
  • name (object) - Descriptor of the data value sent
  • value (object) - Content value
  • style (AEOutput.Style) - Style with which this value should be output
Returns: object
Return value specific to the given command
Raises:
  • NotImplementedError - When not overridden in a subclass

isActive(self)

source code 
Indicates whether the device is active (e.g. giving output, has buffered content to output, is otherwise busy) or not.
Returns: boolean
True when active, False when not
Raises:
  • NotImplementedError - When not overriden in a subclass

Class Variable Details [hide private]

USE_THREAD

Should this device use a separate thread to queue output? Devices that block while doing output (e.g. serial Braille device) should use a thread to keep the main thread unlocked and responsive. Defaults to None so a subclass must override it with an explicit boolean value.
Type:
boolean
Value:
None

COMMAND_CHARS

String of characters that are treated as commands on the device implementing this interface. These characters are replaced with blanks in any string sent to the device.
Type:
string
Value:
''

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