[matplotlib-devel] agg21 and toolbar

I upgraded agg in cvs to agg 2.1.   Probably best to flush your build
dir before rebuilding.  Let me know if you have any build troubles -
on my system it was totally seamless.

In other news, I've ported the new toolbar and event handling to
wx/wxagg. The new buttons are as follows:

  HOME    : reset all axes to initial view

  BACK    : reset axes to previous view limits in stack

  FORWARD : reset axes to next view limits in stack

  PAN     : with left button press/release pan and with right button
            press/release zoom.  For pan, the coord under point at
            press will be moved to coord under point at release.  For
            zoom, movements to the right will zoom in on x axes and
            movements to the left will zoom out.  Ditto for y and
            up/down.  Amount of zoom will be proportionate to distance
            mouse travels over x and y between press and release.
            Diagonal movements will zoom both accordingly.

  ZOOM_TO_RECT  : self explanatory

  SAVE  : as in classic

The toolbar choice is determined by the new rc param 'toolbar' which
can be None, classic or toolbar2.

Todd, you may want to take a look at porting this to TkAgg and Gregory
to FLTK.  My guess is you (Todd) can do this in half an hour or so
since it's basically a slight generalization of the connect scheme you
came up with.  It may take a bit longer for you Gregory if you haven't
implemented FigureCanvas.connect yet.

The new toolbar class, backend_bases.NavigationToolbar2, does 95% of
the work and basically just uses the backend to load up the GUI
widgets and make the event calls.  I've uploaded several new (slicker)
widget icons to CVS that you should use to make the toolbar -
described below

The derived toolbar must define

    def set_cursor(self, cursor):
        'Set the current cursor to one of the cursors values'
        OPTIONAL

where the cursors are ints defined in backend_bases as

  # cursors
  class Cursors:  #namespace
      HAND, POINTER, SELECT_REGION = range(3)
  cursors = Cursors()

and you can use them (optionally) to set the screen pointer icon
depending on the user tool (eg HAND vs SELECT_REGION).  See
backend_gtk for an example mapping the constants to GTK cursor
constants.
     
    def _init_toolbar(self):

This is where you actually build the GUI widgets (called by __init__).
The  icons home.xpm, back.xpm, forward.xpm, hand.xpm, zoom_to_rect.xpm
and filesave.xpm are standard across backends (there are ppm versions
in CVS also).

You just need to set the callbacks

  home         : self.home
  back         : self.back
  forward      : self.forward
  hand         : self.pan
  zoom_to_rect : self.zoom
  filesave     : self.save_figure

You only need to define the last one - the others are in the base
class implementation.

    def save_figure(self, button):

identical to other toolbar

See backend_bases.FigureCanvasBase.mpl_connect,
backend_bases.FigureCanvasBase.mpl_disconnect and
backend_bases.MplEvent for information on the (slightly modified)
connection methods.  FigureCanvasBase.connect is deprecated and should
warn or do what you think appropriate.

The callback signature is now

  func(event)

rather than 

  func(widget, event)

since the former was GTK specific and I didn't see the logic of
including widgets in GUI neutral callbacks.  Also, the event contains
more information - x and y in display (flipped if nec.) coords, the
axes the pointer is over (if any) and the x and y in data coords if
the pointer is over an axes.  Both wx and gtk implement the connection
wrapper so it should be easy to follow them.

The examples/coords_demo.py is modified to work with the new code.

Some things are not finished yet - right now the navigation only
applies to the axes under point.  I'm still thinking about how this
should be handled.  

JDH