Embedding Veusz in Python programs

Here is an example program which demonstrates how to use the Veusz Python embedding interface:

   1 """An example embedding program. Veusz needs to be installed into
   2 the Python path for this to work (use setup.py)
   3 
   4 This animates a sin plot, then finishes
   5 """
   6 
   7 import time
   8 import numpy
   9 import veusz.embed as veusz
  10 
  11 # construct a Veusz embedded window
  12 # many of these can be opened at any time
  13 g = veusz.Embedded('window title')
  14 g.EnableToolbar()
  15 
  16 # construct the plot
  17 g.To( g.Add('page') )
  18 g.To( g.Add('graph') )
  19 g.Add('xy', marker='tiehorz', MarkerFill__color='green')
  20 
  21 # this stops intelligent axis extending
  22 g.Set('x/autoExtend', False)
  23 g.Set('x/autoExtendZero', False)
  24 
  25 # zoom out
  26 g.Zoom(0.8)
  27 
  28 # loop, changing the values of the x and y datasets
  29 for i in range(10):
  30     x = numpy.arange(0+i/2., 7.+i/2., 0.05)
  31     y = numpy.sin(x)
  32     g.SetData('x', x)
  33     g.SetData('y', y)
  34 
  35     # wait to animate the graph
  36     time.sleep(2)
  37 
  38 # let the user see the final result
  39 print "Waiting for 10 seconds"
  40 time.sleep(10)
  41 print "Done!"
  42 
  43 # close the window (this is not strictly necessary)
  44 g.Close()

The embed interface has the methods listed in the command line interface listed in the Veusz manual http://home.gna.org/veusz/docs/manual.html

Multiple Windows are supported by creating more than one Embedded object. Other useful methods include:

New-style object interface

Starting in versions of Veusz >1.8 is a new style of object interface, which makes it easier to construct the widget tree. Each widget, group of settings or setting is stored as a Node object, or its subclass, in a tree. The root document widget can be accessed with the Root object. The dot operator "." finds children inside other nodes. For instance, this constructs a simple x-squared plot which changes to x-cubed:

   1 import veusz.embed as veusz
   2 import time
   3 
   4 embed = veusz.Embedded('window title')
   5 page = embed.Root.Add('page')
   6 graph = page.Add('graph')
   7 function = graph.Add('function', function='x**2')
   8 
   9 time.sleep(2)
  10 function.function.val = 'x**3'
  11 # this is the same if the widgets have the default names
  12 Root.page1.graph1.function1.function.val = 'x**3'

If the document contains a page called "page1" then Root.page1 is the object representing the page. Similarly, Root.page1.graph1 is a graph called graph1 in the page. You can also use dictionary-style indexing to get child widgets, e.g. Root['page1']['graph1']. This style is easier to use if the names of widgets contain spaces or if widget names shadow methods or properties of the Node object, i.e. if you do not control the widget names.

Widget nodes can contain as children other widgets, groups of settings, or settings. Groups of settings can contain child settings. Settings cannot contain other nodes. Here are the useful operations of Nodes:

   1 class Node(object):
   2   """properties:
   3     path - return path to object in document, e.g. /page1/graph1/function1
   4     type - type of node: "widget", "settinggroup" or "setting"
   5     name - name of this node, e.g. "graph1"
   6     children - a generator to return all the child Nodes of this Node, e.g.
   7       for c in Root.children:
   8         print c.path
   9     children_widgets - generator to return child widget Nodes of this Node
  10     children_settinggroups - generator for child setting groups of this Node
  11     children_settings - a generator to get the child settings
  12     childnames - return a list of the names of the children of this Node
  13     childnames_widgets - return a list of the names of the child widgets
  14     childnames_settinggroups - return a list of the names of the setting groups
  15     childnames_settings - return a list of the names of the settings
  16     parent - return the Node corresponding to the parent widget of this Node
  17 
  18     __getattr__ - get a child Node with name given, e.g. Root.page1
  19     __getitem__ - get a child Node with name given, e.g. Root['page1']
  20   """
  21 
  22   def fromPath(self, path):
  23      """Returns a new Node corresponding to the path given, e.g. '/page1/graph1'"""
  24 
  25 class SettingNode(Node):
  26     """A node which corresponds to a setting. Extra properties:
  27     val - get or set the setting value corresponding to this value, e.g.
  28      Root.page1.graph1.leftMargin.val = '2cm'
  29     """   
  30 
  31 class SettingGroupNode(Node):
  32     """A node corresponding to a setting group. No extra properties."""
  33 
  34 class WidgetNode(Node):
  35     """A node corresponding to a widget.
  36    
  37        property:
  38          widgettype - get Veusz type of widget
  39 
  40        Methods are below."""
  41 
  42     def WalkWidgets(self, widgettype=None):
  43         """Generator to walk widget tree and get widgets below this
  44         WidgetNode of type given.
  45 
  46         widgettype is a Veusz widget type name or None to get all
  47         widgets."""
  48 
  49     def Add(self, widgettype, *args, **args_opt):
  50         """Add a widget of the type given, returning the Node instance.
  51         """
  52 
  53     def Rename(self, newname):
  54         """Renames widget to name given.
  55         Existing Nodes corresponding to children are no longer valid."""
  56         
  57     def Action(self, action):
  58         """Applies action on widget."""
  59 
  60     def Remove(self):
  61         """Removes a widget and its children.
  62         Existing Nodes corresponding to children are no longer valid."""

Note that Nodes are temporary objects which are created on the fly. A real widget in Veusz can have several different WidgetNode objects. The operators == and != can test whether a Node points to the same widget, setting or setting group.

Here is an example to set all functions in the document to be x**2:

   1 for n in Root.WalkWidgets(widgettype='function'):
   2   n.function.val = 'x**2'

EmbeddingPython (last edited 2010-07-01 21:17:04 by JeremySanders)