Version 2.0

Over the years, libavg has accumulated some cruft I'd like to get rid of. While the API in general is very usable and easy to learn, there are also quite a few places that need improvement. A few API decisions (not many) are even downright stupid in retrospect.

Version 2.0 will, therefore, break completely with backwards compatibility to clean things up. The following is a list of possible changes. It's also a call for discussion: If you don't like what you see here, I'd like to know.

Error and Warning Handling

  • Use a libavg-defined exception type instead of RuntimeError to report errors.
  • Get rid of console WARNINGS where possible.
  • Remove all ERRORS - these should be exceptions.
  • Remove the python interface of the logger.

Node Positioning

Node positioning/rotation/scaling works well in simple cases, but there are several shortcomings:

  • div nodes can't be scaled,
  • positioning a rotated element is a pain and
  • it doesn't map well to OpenGL matrix transforms internally.

What libavg needs is a consistent transform hierarchy like those generally used in 3D engines. That means:

  • Add a scale (Point2D) attribute, make size read-only.
  • Change Node positioning to use pos/rotate/scale consistently.
  • Default pivot is (0,0), pivot is used for all transforms (including translation and scale).
  • Create a generic Transform class to replace libavg.ui.transform.
  • Vector nodes have the same pos/rotate/scale attributes.
  • div nodes get the scale attribute as well.
  • Possibly add a setAlignment() function so the node is left/center/right-aligned and/or top/center/bottom-aligned. Internally, this would just set the pivot appropriately.


libavg configuration is split between avgrc, Player.setOGLOptions() and environment variable settings (and has command line overrides). There is some logic behind this: system-wide and user-specific config goes into avgrc and setOGLOptions() is used for program-specific things. Parameters for a single execution of libavg are put into environment variables.

Most of this makes sense, but the environment variables can be moved to command line parameters or avgrc. Cruft like the audio section in avgrc and non-working OpenGL options need to be removed.

Event Handling

  • Remove Node.oncursorxxx attributes and Node.setEventHandler.
  • Add Player.connectKeyboardHandler()
  • Change event handler syntax to id = connectEventHandler(type, source, pyfunc) and disconnectEventHandler(id|pyfunc).
  • Change setEventHook() so it maintains a list of hooks internally; return an id so we can add a clearEventHook(id) function. Remove getEventHook().

Clean Up Namespaces

  • libavg.avg should disappear.
  • Clean up the libavg namespace.
  • Add player = libavg.avg.Player.get() to libavg/, remove get() method from public interface.
  • Clean up python namespaces.


ImageNode.href is a misnomer - it should be ImageNode.src. We can get rid of ImageNode.setBitmap and href="canvas:id" by making the src attribute polymorphic:

image.src = "file.png" 
image.src = bitmap
image.src = canvas

Then becomes superfluous and svg.createImageNode() can be replaced with ImageNode(src=svg.renderElement(...)).

Media Domains

The mediadir attribute is broken.

Instead, we'd like to introduce resource domains: Player manages a table of resource domains that have a name and a path. There is a default domain that is used to find files when no domain is given. src attributes can then use several different protocols:

filename (default domain)

There should be two new player functions:

player.setResourceDomain(domain, path)       # Sets the path used for a resource domain.
path = player.findFile(domain, resourceName) # Returns the full path of a resource.


  • Delete all deprecated functions.
  • HoldRecognizer.stopHandler should be .endHandler for consistency.
  • Clean up Camera parameter setting: It needs to be possible to query min/max values.
  • Rename Canvas::[un]registerCameraNode().
  • Refactor AVGApp
  • Rename Bitmap.getSize() -> Bitmap.size (readonly attr). See if there are more things that need this type of change.
  • Remove '.py' from utilities.
  • Button and TouchButton should have the same interface.