# $Id: Diagram.py,v 1.7 2006/07/02 13:08:53 marcusva Exp $
#
# Copyright (c) 2006, Marcus von Appen
# All rights reserved.
# Redistribution and use in source and binary forms, with or without
# modification, are permitted provided that the following conditions are met:
#
# * Redistributions of source code must retain the above copyright notice,
# this list of conditions and the following disclaimer.
# * Redistributions in binary form must reproduce the above copyright notice,
# this list of conditions and the following disclaimer in the documentation
# and/or other materials provided with the distribution.
#
# THIS SOFTWARE IS PROVIDED BY THE COPYRIGHT HOLDERS AND CONTRIBUTORS "AS IS"
# AND ANY EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
# IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE
# ARE DISCLAIMED. IN NO EVENT SHALL THE COPYRIGHT OWNER OR CONTRIBUTORS BE
# LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL, EXEMPLARY, OR
# CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO, PROCUREMENT OF
# SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS; OR BUSINESS
# INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY, WHETHER IN
# CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR OTHERWISE)
# ARISING IN ANY WAY OUT OF THE USE OF THIS SOFTWARE, EVEN IF ADVISED OF THE
# POSSIBILITY OF SUCH DAMAGE.
"""An abstract widget for diagram and graph implementations."""
from BaseWidget import BaseWidget
from Constants import *
import base
class Diagram (BaseWidget):
"""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.
"""
def __init__ (self):
BaseWidget.__init__ (self)
# Negative values. Influences the axes.
self._negative = False
# Horizontal or vertical mapping of the axes.
self._orientation = ORIENTATION_HORIZONTAL
# Coordinates of the point of origin on the widget.
self._origin = (0, 0)
# The data to evaluate and the return values.
self._data = None
self._values = None
# The eval func.
self._evalfunc = None
def get_scale_units (self):
"""D.get_scale_units (...) -> None
Gets the scale units of the axes.
This method has to be implemented by inherited widgets.
"""
raise NotImplementedError
def set_scale_units (self, units):
"""D.set_scale_units (...) -> None
Sets the scale units of the axes.
This method has to be implemented by inherited widgets.
"""
raise NotImplementedError
def get_units (self):
"""D.set_units (...) -> None
Gets the pixels per unit for dimensioning.
This method has to be implemented by inherited widgets.
"""
raise NotImplementedError
def set_units (self, units):
"""D.set_units (...) -> None
Sets the pixels per unit for dimensioning.
This method has to be implemented by inherited widgets.
"""
raise NotImplementedError
def get_axes (self):
"""D.get_axes (...) -> None
Gets the amount and names of the axes.
This method has to be implemented by inherited widgets.
"""
raise NotImplementedError
def set_axes (self, axes):
"""D.set_axes (...) -> None
Sets the amount and names of the axes.
This method has to be implemented by inherited widgets.
"""
raise NotImplementedError
def set_negative (self, negative=True):
"""D.set_negative (...) -> None
Sets the indicator, whether negative values should be shown.
"""
self._negative = negative
self.dirty = True
def set_orientation (self, orientation=ORIENTATION_HORIZONTAL):
"""D.set_orientation (...) -> None
Sets the orientation of the axes.
Raises a ValueError, if the passed argument is not a value of
the ORIENTATION_TYPES tuple.
"""
if orientation not in ORIENTATION_TYPES:
raise ValueError("orientation must be a value of ORIENATION_TYPES")
self._orientation = orientation
self.dirty = True
def set_origin (self, x, y):
"""D.set_origin (...) -> None
Sets the coordinates of the point of origin on the widget.
Raises a TypeError, if the passed arguments are not integers.
"""
if (type (x) != int) or (type (y) != int):
raise TypeError ("x and y must be integers")
self._origin = (x, y)
self.dirty = True
def set_data (self, data):
"""D.set_data (...) -> None
Sets the data to evaluate.
This method does not perform any consistency checking or
whatsoever.
"""
self._data = data
if self.data != None:
self.evaluate ()
else:
self.values = None
def set_values (self, values):
"""D.set_values (...) -> None
Sets the values without processing the data.
"""
self._values = values
self.dirty = True
def set_eval_func (self, func):
"""D.set_eval_func (...) -> None
Sets the evaluation function for the data.
Raises a TypeError, if func is not callable.
"""
if not callable (func):
raise TypeError ("func must be callable")
self._evalfunc = func
if self.data != None:
self.evaluate ()
else:
self.dirty = True
def evaluate (self):
"""D.evaluate () -> None
Calulates the result values from the set data.
Calculates the result values from the set the data using the set
evaluation function.
If the set data is a sequence, eval_func will be applied to each
item of it (using map()) to build the return values:
values = map (eval_func, data)
If the set data is not a list or tuple, the data will be passed
in it entirety to eval_func in order to calculate the return
values:
values = eval_func (data)
The 'negative' attribute neither does affect the data nor the
return values.
"""
if self.eval_func != None:
if self.data != None:
if type (self.data) in (list, tuple):
self.values = map (self.eval_func, self.data)
else:
self.values = self.eval_func (self.data)
return
self.values = self.data
scale_units = property (lambda self: self.get_scale_units (),
lambda self, var: self.set_scale_units (var),
doc = "The scale units of the axes.")
units = property (lambda self: self.get_units (),
lambda self, var: self.set_units (var),
doc = "The pixels per unit to set.")
axes = property (lambda self: self.get_axes (),
lambda self, var: self.set_axes (var),
doc = "The axes to show.")
negative = property (lambda self: self._negative,
lambda self, var: self.set_negative (var),
doc = "Indicates, whether negative values are shown.")
orientation = property (lambda self: self._orientation,
lambda self, var: self.set_orientation (var),
doc = "The orientation of the axes.")
origin = property (lambda self: self._origin,
lambda self, (x, y): self.set_origin (x, y),
doc = "Coordinates of the point of origin on the " \
"widget")
data = property (lambda self: self._data,
lambda self, var: self.set_data (var),
doc = "The data to evaluate.")
values = property (lambda self: self._values,
lambda self, var: self.set_values (var),
doc = "The calculated values of the set data.")
eval_func = property (lambda self: self._evalfunc,
lambda self, var: self.set_eval_func (var),
doc = "The evaluation function for calculation.")
syntax highlighted by Code2HTML, v. 0.9.1