Type Diagram

 object --+            
          |            
INotifyable --+        
              |        
     BaseObject --+    
                  |    
     object --+   |    
              |   |    
         Sprite --+    
                  |    
         BaseWidget --+
                      |
                     Diagram

Known Subclasses:

Graph2D

Diagram () -> Diagram

An abstract widget class for diagram and graph implementations.

The Diagram class contains the minimum set of attributes and methods
needed to visualize diagrams or graphs from arbitrary data.

Diagrams can have different resolutions, dependant on the value
range, that should be displayed. Inheritors thus have to implement
the 'units' attribute and its related methods get_units() and
set_units(), which define, how many pixels between each full unit
have to be left. Greater values usually result in a higher
resolution, resp. pixel amount between the values.

To allow the user to know about the kind of data, that is evaluated
and displayed, the 'scale_units' attribute and its related methods
get_scale_units() and set_scale_units() must be implemented. Those
define the concrete type of data, that is displayed on each axis of
the diagram (e.g. cm, inch, kg...).

The 'axes' attribute and its related methods get_axes() and
set_axes(), which have to be implemented. denote the axes, which are
used to set the data and its results into relation. A typical
cartesian coordinate plane for example will have two axes (x and y).

The 'orientation' attribute should be respected by inheritors to
allow displaying data in a vertical or horizontal align.

diagram.orientation = ORIENTATION_HORIZONTAL
diagram.set_orientation (ORIENTATION_VERTICAL)

The Diagram contains a 'negative' attribute and set_negative()
method, which indicate, whether negative values should be shown or
not.

diagram.negative = True
diagram.set_negative = False

The 'origin' attribute and set_origin() method set the point of
origin of the diagram on its widget surface and denote a tuple of an
x and y value. Inheritors should use this to set the point of origin
of their diagram type. Most diagram implementors usually would use
this as a relative coordinate to the bottom left corner of the
widget surface.
Note, that this is different from a real relative position on the
widget surface, as those are related to the topleft corner

diagram.origin = 10, 10
diagram.set_origin (20, 20)

The 'data' attribute and set_data() method set the data to be
evaluated by the diagram inheritor using the evaluate() method. It
is up to the inheritor to perform additional sanity checks.

diagram.data = mydata
diagram.set_data (mydata)

An evaluation function, which processes the set data can be set
using the 'eval_func' attribute or set_eval_func() method. If set,
the evaluate() method will process the set data using the eval_func
and store the return values in its 'values' attribute. Otherwise, the
values will be set to the data.

def power_1 (x):
    return x**2 - x

diagram.eval_func = power_1

The evaluate() method of the widget distinguishes between the type
of data and will act differently, dependant on whether it is a
sequence or not. Lists and tuples will be passed to the eval_func
using the python map() function, else the complete data will be
passed to the eval_func:

# Data is list or tuple:
self.values = map (self.eval_func, data)

# Any other type of data:
self.values = self.eval_func (data)

The result values can also be set manually without any processing
using the 'values' attribute and set_values() method. This can be
useful for inheritors like a bar chart for example.

self.values = myvalues
self.set_values (myvalues)

A concrete implementation of the Diagram class can be found as
Graph2D widget within this module.

Default action (invoked by activate()):
None

Mnemonic action (invoked by activate_mnemonic()):
None

Attributes:
scale_units - The scale unit(s) to set for the axes.
units       - Pixels per unit to set.
axes        - The axes to show.
negative    - Indicates, that negative vaues should be taken into
              account.
orientation - The orientation mapping of the axes.
origin      - The position of the point of origin on the widget.
data        - Data to evaluate.
values      - Result values of the set data after evaluation.
eval_func   - Evaluation function to calculate the values.