
                        Anygui: Generic GUI for Python
                                       
                             Magnus Lie Hetland
                                      
                             February 8th, 2002
                                      
1. Introduction

   The Python standard library currently does not contain any
   platform-independent GUI packages. It is the goal of the Anygui
   project to change this situation. There are many such packages
   available, but none has been defined as standard, so when writing GUI
   programs for Python, you cannot assume that your user has the right
   package installed.
   
   The problem is that declaring a GUI package as standard would be quite
   controversial. There are some packages that are quite commonly
   available, such as Tkinter; but it would not be practical to require
   all installations to include it, nor would it be desirable to require
   all Python GUI programs to use it, since there are many programmers
   who prefer other packages.
   
   Anygui tries to solve this problem in a manner similar to the standard
   anydbm package. There is no need to choose one package at the expense
   of all others. Instead, Anygui gives generic access to several popular
   packages through a simple API, which makes it possible to write GUI
   applications that work with all these packages. Thus, one gets a
   platform-independent GUI module which is written entirely in Python.
   
   To get the latest Anygui distribution, or to get in touch with the
   developers, please visit the Anygui website: http://www.anygui.org.
   
  1.1 Design Goals
  
   A. Anygui should be an easy to use GUI package which may be used to
   create simple graphical programs, or which may serve as the basis for
   more complex application frameworks.
   
   B. Anygui should be a pure Python package which serves as a front-end
   for as many as possible of the GUI packages available for Python, in a
   transparent manner.
   
   C. Anygui should include functionality needed to perform most GUI
   tasks, but should remain as simple and basic as possible.
   
  1.2 Warning
  
   The Anygui API is currently very much in flux as the Anygui team keeps
   experimenting with it. Because of that, incompatibilities may occur
   between releases. The current release (0.1.1) should be regarded as a
   prototype.
   
  1.3 Tutorial
  
   There is also a short tutorial available, which is included in the
   installation (doc/tutorial.txt) and is available from the website
   (http://www.anygui.org).
   
2. Installation

   The Anygui package comes in the form of a gzip compressed tar archive.
   To install it you will first have to uncompress the archive. On
   Windows this can be done with WinZip. in Mac OS, you can use StuffIt
   Expander. In Unix, first move to a directory where you'd like to put
   Anygui, and then do something like the following:

      foo:~/python$ tar xzvf anygui-0.1.1.tar.gz

   If your version of tar doesn't support the z switch, you can do
   something like this:

      foo:~/python$ zcat anygui-0.1.1.tar.gz | tar xvf

   Another possibility is:

      foo:~/python$ gunzip anygui-0.1.1.tar.gz
      foo:~/python$ tar -xvf anygui-0.1.1.tar

   No matter which version you choose, you should end up with a directory
   named anygui-0.1.1.
   
  2.1 Running setup.py
  
   The simple way of installing Anygui is to use the installation script
   that's included in the distribution. This requires Distutils
   (http://www.python.org/sigs/distutils-sig), which is included in
   Python distributions from version 2.0. To install the Anygui package
   in the default location, simply run the setup script with the install
   command:

      foo:~$ python setup.py install

   This will install Anygui in your standard Python directory structure.
   If you don't have access to this directory (e.g. because Python was
   installed by a sysadmin, and you don't have root access) you can
   install it somewhere else with the --prefix option:

      foo:~$ python setup.py install --prefix=${HOME}/python

  2.2 Doing it Manually
  
   Since Anygui consists of only Python code, nothing needs to be
   compiled. And the only thing needed to install Python code is to
   ensure that the packages and modules are found by your Python
   interpreter. This is as simple as including the lib directory of the
   Anygui distribution in your PYTHONPATH environment variable. In bash
   (http://www.gnu.org/manual/bash/), you could do something like this:

      foo:~$ export PYTHONPATH=$PYTHONPATH:/path/to/anygui/lib

   To make this permanent, you should put it in your .bash_profile file,
   or something equivalent. If you don't want to mess around with this,
   and already have a standard directory where you place your Python
   modules, you can simply copy (or move) the anygui package (found in
   anygui-0.1.1/lib) there, or possibly place a symlink in that directory
   to the anygui package.
   
  2.3 Making Sure You Have a Usable GUI Package
  
   Once you have Anygui installed, you'll want to make sure you have a
   usable GUI package. This is easy to check: Simply start an interactive
   Python interpreter and try to execute the following:

      >>> from anygui import *
      >>> backend()

   The backend function will return the name of the backend in use. If it
   is neither 'curses' nor 'text' you should be all set for making GUI
   programs with Anygui. (The 'curses' and 'text' backends use plain text
   to emulate graphical interfaces on platforms that don't have them.)
   Anygui currently supports the following packages:

      PythonWin  (mswgui)    http://starship.python.net/crew/mhammond/win32
      Tkinter    (tkgui)     http://www.python.org/topics/tkinter
      wxPython   (wxgui)     http://www.wxpython.org
      Java Swing (javagui)   http://www.jython.org
      PyGTK      (gtkgui)    http://www.daa.com.au/~james/pygtk
      Bethon     (beosgui)   http://www.bebits.com/app/1564
      PyQt       (qtgui)     http://www.thekompany.com/projects/pykde
      Curses     (cursesgui) -- used when no GUI package is available
      Plain text (textgui)   -- used if curses is not available

   Add gui to name returned by the backend function to get the full name
   of the backend module (in the anygui.backends package). For instance,
   the msw backend is found in anygui.backends.mswgui module.
   
   In general, if you end up with a text-based solution, cursesgui will
   be preferred over textguiif your Python-installation has a wrorking
   curses module. The exception is if you are using Anygui in the
   interactive interpreter, in which textgui will be preferred, to avoid
   interfering with the terminal and locking up the interpreter prompt.
   (If you'd like to, for some reason, you can override this behaviour
   with the environment variable ANYGUI_FORCE_CURSES; see the API
   Reference below.)
   
   BeOS Note: The BeOS backend (beosgui) is currently not fully
   functional, but is included nonetheless.
   
   Of these, Tkinter is compiled in by default in the MS Windows
   distribution of Python (available from http://www.python.org),
   PythonWin (as well as Tkinter) is included in the ActiveState
   distribution, ActivePython (available from
   http://www.activestate.com), and Java Swing is automatically available
   in Jython, the Java implementation of Python.
   
   Note: In Mac OS 9, Anygui (using Tkinter) works with with Python
   Classic and recent versions of Python Carbon, but older versions have
   problems with Tkinter.
   
3. Using Anygui

   Note: For some examples of working Anygui code, see the test and demo
   directories of the distribution. Remember that the test scripts are
   written to test certain features of Anygui, not to represent
   recommended coding practices.
   
   Using Anygui is simple; it's simply a matter of importing the classes
   and functions you need from the anygui module, e.g.:

      from anygui import *

   After doing this you must create an Application object, at least one
   Window, and probably a few components such as Buttons and TextFields.
   The Windows are added to the Application (through its add method), and
   the various components are added to the Window. When you have done
   this, you call the run method of your Application instance.

      # Make components here
      win = Window()
      # Add components to the Window
      app = Application()
      app.add(win)
      app.run()

  3.1 Avoiding Namespace Pollution
  
   Importing everything from Anygui (as in from anygui import *) is fine
   for small programs, where you're certain that there will be no name
   clashes. You may also simply import the names you need:

      from anygui import Application, Window

   The preferred way to use modules like this is usually to avoid
   cluttering your namespace, by using simply import anygui. However, if
   you are going to create a lot of widgets, the anygui prefix may be
   cumbersome. Therefore, I suggest renaming it to gui, either with a
   simple assignment...

      import anygui; gui = anygui

   ... or, in recent versions of Python:

      import anygui as gui

   Then you can instantiate widgets like this:

      win = gui.Window()

   The examples in this documentation use the starred import, for
   simplicity.
   
  3.2 Importing the Backends Directly
  
   If you wish to import a backend directly (and "hardwire it" into your
   program), you may do so. For instance, if you wanted to use the
   wxPython backend, wxgui, you'd replace

      from anygui import *

   with

      from anygui.backends.wxgui import *

   This way you may use Anygui in standalone executables built with tools
   like py2exe (http://starship.python.net/crew/theller/py2exe/) or the
   McMillan installer (http://www.mcmillan-inc.com/install1.html), or
   with jythonc with the --deep option or equivalent.
   
   Note: Compiling jar files of Anygui programs with Jython may not work
   in the current version.
   
   Note that the namespace handling still works just fine:

      import anygui.backends.tkgui as gui

  3.3 Creating a Window
  
   One of the most important classes in Anygui is Window. Without a
   Window you have no GUI; all the other widgets are added to Windows.
   Knowing this, we may suspect that the following is a minimal Anygui
   program (and we would be right):

      from anygui import *
      app = Application()
      win = Window()
      app.add(win)
      app.run()

   This example gives us a rather uninteresting default window. You may
   customise it by setting some of its properties, like title and size:

      w = Window()
      w.title = 'Hello, world!'
      w.size = (200, 100)

   If we want to, we can supply the widget properties as keyword
   arguments to the constructor:

      w = Window(title='Hello, world!', size=(200,100))

  3.4 The set Method and the Options Class
  
   If you want to change some attributes of a widget, you can either just
   set them directly, or (if you'd like to set several at once), use the
   set method, just like the constructor:

      w.set(title='Hello, again', size=(300,200))

   Supplying the same attributes with the same values to a lot of widgets
   (if you are making several buttons with the same size, for instance)
   can be a bit impractical (you'll learn more about buttons in a little
   while):

      bt1 = Button(left=10, width=50, height=30, text='Button 1')
      bt2 = Button(left=10, width=50, height=30, text='Button 2')
      bt3 = Button(left=10, width=50, height=30, text='Button 3')

   To deal with this, the widget constructors (and the set method) can
   take Options objects as positional parameters:

      opt = Options(left=10, width=50, height=30)
      bt1 = Button(opt, text='Button 1')
      bt2 = Button(opt, text='Button 2')
      bt3 = Button(opt, text='Button 3')

   As you can see, this saves quite a lot of typing. You can use as many
   Options arguments as you like.
   
  3.5 The modify Method
  
   Just like set can be used to set the attributes of a Component, the
   modify method can be used to modify them, without rebinding them to
   another value. To show the difference, consider the following example
   (where foo is an attribute that does nothing special):

      >>> from anygui import *
      >>> btn = Button()
      >>> some_list = [1, 2, 3]
      >>> btn.foo = some_list
      >>> btn.modify(foo=[4, 5, 6])
      >>> btn.foo
      [4, 5, 6]
      >>> some_list
      [4, 5, 6]
      >>> btn.set(foo=[7, 8, 9])
      >>> btn.foo
      [7, 8, 9]
      >>> some_list
      [4, 5, 6]

   As you can see, using modify modifies the list, while set replaces it.
   The modify method is used for (among other things) implementing
   Model-View-Controller systems. (More about that later.)
   
   The modify method works as follows: If there is a specific internal
   method for modifying an attribute, that is called. Otherwise, the
   supplied value will be assigned to self.name[:] (where name is the
   attribute in question). If that doesn't work (a TypeError exception is
   raised), the value will be assigned to self.name.value. If that
   doesn't work either, the attribute will be rebound to the new value,
   with the same result as using set. So, to avoid any in-place
   modification, all you need to do is use immutable values:

      >>> from anygui import *
      >>> btn = Button()
      >>> some_list = [1, 2, 3]
      >>> btn.foo = tuple(some_list)
      >>> btn.modify(foo=[4, 5, 6])
      >>> btn.foo
      [4, 5, 6]
      >>> some_list
      [1, 2, 3]

  3.6 The refresh Method
  
   The modify method is used to modify attributes in-place, e.g. to keep
   them in sync with a widget. This is done automatically when you change
   a widget through the graphical interface. In a way, the refresh method
   works the other way: If you modify an attribute, you can call the
   refresh method to keep the widget's appearance in sync with its state.
   When you assign to an attribute, refresh is called automatically; you
   only have to call it yourself if you have an attribute which is a
   mutable object, and you modify that object.
   
   For more info about the use of refresh, see the section "About Models,
   Views, and Controllers", below.
   
  3.7 Adding a Label
  
   Simple labels are created with the Label class:

      lab = Label(text='Hello, again!', position=(10,10))

   Here we have specified a position just for fun; we don't really have
   to. If we add the label to our window, we'll see that it's placed with
   its left topmost corner at the point (10,10):

      w.add(lab)

  3.8 Layout: Placing Widgets in a Frame
  
   This section goves a simple example of positioning Components; for
   more information about the Anygui layout mechanism, please refer to
   the API Reference (below).

      win.add(lab, position=(10,10))
      win.add(lab, left=10, top=10)
      win.add(lab, top=10, right=10)
      win.add(lab, position=(10,10), right=10, hstretch=1)

   In the last example hstretch is a Boolean value indicating whether the
   widget should be stretched horizontally (to maintain the other
   specifications) when the containing Frame is resized. (The vertical
   version is vstretch.)
   
   Just like in component constructors, you can use Options objects in
   the add method, after the component to be added:

      win.add(lab, opt, left=10)

    3.8.1 Placing More Than One Widget
    
   The add method can also position a sequence of widgets. The first
   widget will be placed as before, while the subsequent ones will be
   placed either to the right, to the left, above (up), or below (down),
   according to the direction argument, at a given distance (space):

      win.add((lab1, lab2), position=(10,10),
              direction='right', space=10)

   Note: Remember to enclose your components in a sequence (such as a
   tuple or a list), since add allows you to use more positional
   arguments, but will treat them differently. If you want to use Options
   objects, place them outside (after) the sequence. For more information
   see the section about the Frame class in the API Reference below.
   
  3.9 Buttons and Event Handling
  
   Buttons (as most components) work more or less the same way as Labels.
   You can set their size, their position, their text, etc. and then add
   them to a Frame (such as a Window). The thing that makes them
   interesting is that they emit events. Each time the user clicks a
   button, it sends out a click event. You can catch these events by
   linking your button to one or more event handlers. It's really simple:

      btn = Button(text='Greet Environment')
      def greeting(**args):
          print 'Hello, World!'
      link(btn, greeting)

   The event handling is taken care of by the call to link. An event
   handler may receive several keyword arguments, and if you're not
   particularly interested in any of them, simply use something like
   **args above. (For more information about this, see the section about
   global functions in the API Reference below.)
   
  3.10 About Models, Views, and Controllers
  
   The Anygui MVC mechanism (based on the refresh method and the Assignee
   protocol) is described in the API Reference below. Here is a short
   overview on how to use it.
   
   A model is an object that can be modified, and that can notify other
   objects, called views, when it has been modified. A controller is an
   object that can modify the model, in particular as a direct response
   to a user action (such as clicking the mouse or typing some text). In
   Anygui, Components double as both views (showing a model's state to
   the user) and controllers (letting the user modify the model). Even
   though Anygui supports using models this way, you can also create
   complete application without using them.
   
   Models are in general instances of some subclass of the Model class,
   although they don't have to be; see the API Reference below for a
   description of how they work. (The Model class is currently internal
   to the Anygui package, but it can be found int he anygui.Models
   module.) The Models that are included in Anygui are:

      BooleanModel     -- represents a Boolean value
      ListModel        -- behaves like a list
      NumberModel      -- represents a numerical value
      TextModel        -- acts like a mutable string

   These all have a value attribute which may be used to change their
   internal value. They also support other operations, such as indexing
   and slicing etc. for ListModel. These are very easy to use: Just
   assign them to an attribute of a Component:

      # You'll learn about CheckBoxes in a minute
      cbx = CheckBox(text='Simple model test')
      state = BooleanModel(value=1)
      cbx.on = state

   Now, if you change state (e.g. with the statement state.value=0) this
   will automatically be reflected in the CheckBox (which will be acting
   like a view). If the user clicks the CheckBox, the model will be
   changed.
   
   To keep a view up-to-date manually you can call its refresh method.
   This can be useful if you use a simple (non-Model) mutable value such
   as a list in an attribute:

      btn = Button()
      rect = [0, 0, 10, 10]
      btn.geometry = rect
      rect[3] = 20
      btn.refresh()

   After modifying rect, the button will not have changed, since it can't
   detect the change by itself. (That's only possible when you use a real
   model.) Therefore, you call btn.refresh to tell it to update itself.
   
   If you assign a value to an attribute, the refresh method will be
   called automatically, so another way of doing the same thing is:

      btn = Button()
      rect = [0, 0, 10, 10]
      btn.geometry = rect
      rect[3] = 20
      btn.geometry = rect

   Warning: Because of the controller behaviour of Components, if the
   Button is resized, rect will be modified. If you don't want this
   behaviour, use a tuple instead of a list, since tuples can't be
   modified.
   
   If you want another object to monitor a model, you can simply use the
   link method, since all models generate an event (of the type default)
   when they are modified.
   
   Example:

      from anygui import *
      >>> mdl = BooleanModel()
      >>> mdl.value = 1
      >>> def model_changed(**kw):
      >>>     print 'The model has changed!'
      
      >>> link(mdl, model_changed)
      >>> mdl.value = 0
      The model has changed
      >>> mdl.value = 0
      The model has changed

   Note the last two lines: We haven't really changed the model, but the
   event handler is called nonetheless. If you want to know whether the
   model really changed, you must retain a copy of its state, and compare
   the new value.
   
  3.11 Using CheckBoxes
  
   A CheckBox is a toggle button, a button which can be in one of two
   states, "on" or "off". Except for that, it works more or less like any
   other button in that you can place it, set its text, and link an event
   handler to it.
   
   Whether a CheckBox is currently on or off is indicated by its on
   attribute.
   
  3.12 RadioButtons and RadioGroups
  
   RadioButtons are toggle buttons, just like CheckBoxes. The main
   differences are that they look slightly different, and that they
   should belong to a RadioGroup.
   
   A RadioGroup is a set of RadioButtons where only oneRadioButton is
   permitted to be "on" at one time. Thus, when one of the buttons in the
   group is turned on, the others are automatically turned off. This can
   be useful for selecting among different alternatives.
   
   RadioButtons are added to a RadioGroup by setting their group
   property:

      radiobutton.group = radiogroup

   This may also be done when constructing the button:

      grp = RadioGroup()
      rbn = RadioButton(group=grp)

   Note: The behaviour of a RadioButton when it does not belong to a
   RadioGroup is not defined by the Anygui API, and may vary across
   backend. Basically, a RadioButton without a RadioGroup is meaningless;
   use a CheckBox instead.
   
   RadioGroups also support an add method, as all other Anygui
   container-like objects:
   
   add(button)
   
   Adds the button to the group, including setting button.group to the
   group. As with the other add methods, the argument may be either a
   single object, or a sequence of objects.
   
  3.13 ListBox
  
   A ListBox is a vertical list of items that can be selected, either by
   clicking on them, or by moving the selection up and down with the
   arrow keys. (For the arrow keys to work, you must make sure that the
   ListBox has keyboard focus. In some backends this requires using the
   tab key.)
   
   Note: When using Anygui with Tkinter, using the arrow keys won't
   change the selection, only which item is underlined. You'll have to
   use the arrow keys until the item you want to select is underlined;
   then select it by pressing the space bar.
   
   A ListBox's items are stored in its attribute items, a sequence of
   arbitrary objects. The text displayed in the widget will be the result
   of applying the built-in Python function str to each object.

      lbx = ListBox()
      lbx.items = 'This is a test'.split()

   The currently selected item can be queried or set through the
   selection property (an integer index, counting from zero). Also, when
   an item is selected, a select event is generated, which is the default
   event type for a ListBox. This means that you can either do

      link(lbx, 'select', handler)

   or

      link(lbx, handler)

   with the same result. (This is similar to the click event, which is
   default for Buttons; for more information, see the API Reference
   below.)
   
  3.14 TextField and TextArea
  
   Anygui's two text widgets, TextField and TextArea are quite similar.
   The difference between them is that TextField permits neither newlines
   or tab characters to be typed, while TextArea does. Typing a tab in a
   TextField will simply move the focus to another widget, while pressing
   the enter key will send an enterkey event (which is the TextField's
   default event type).
   
   The text in a text component is stored in its text property (a string
   or equivalent), and the current selection is stored in its selection
   property (a tuple of two integer indices).
   
  3.15 Making Your Own Components and LayoutManagers
  
   Currently, you can create your own components by combining others in
   Frames, and wrapping the whole thing up as a class. One of the main
   reasons for doing this would be to emulate a feature (such as a tabbed
   pane) available in some backends, but not in others. One could then
   actually use the native version in the backends where it is available
   (such as wx, in this case), and use the "emulation" in the others.
   There is some limited support for this in the backend function (which
   will allow you to check whether you are currently using the correct
   backend), but in the future, a more complete API will be developed for
   this, allowing you access to the coolest features of your favorite GUI
   package, while staying "package independent".
   
   You can already create your own layout managers, by properly
   supporting the methods add, remove, and resized. The simplest way of
   doing this is to subclass LayoutManager, which gives you the add and
   remove methods for free. You can then concentrate on the method
   resized which takes two positional arguments, dw, and dh (change in
   width and change in height) and is responsible for changing the
   geometries of all the components in the Frame the LayoutManager is
   managing. (This frame is available through the private attribute
   self._container.)
   
   To get more control over things, you should probably also override the
   two internal methods add_components and remove_component:
   
   add_components(self, *items, **kws)
   
   Should add all the components in items, and associate them with the
   options in kws, for later resizing.
   
   remove_component(self, item)
   
   Should remove the given item.
   
4. API Reference

   The following reference describes the full official API of the current
   version (0.1.1) of Anygui.
   
  4.1 Environment Variables
  
   Some environment variables affect the behaviour of the Anygui package.
   These must be set in the environment of the program using Anygui. They
   may either be set permanently through normal operating system channels
   (check your OS documentation for this), or possibly just set
   temporarily when running your program. In Unix shells like bash, you
   can set the variables on the command line before your comand, like
   this:

      foo:~$ ANYGUI_SOMEVAR='some value' python someprogram.py

   where ANYGUI_SOMEVAR is some environment variable used by Anygui.
   
   Since Jython doesn't support OS environment variables, you'll have to
   supply them with the command-line switch -D:

      foo:~$ jython -DANYGUI_SOMEVAR='some value' someprogram.py

   You can also set these environment variables in your own program, by
   using code like the following before you import Anygui:

      import os
      os.environ['ANYGUI_SOMEVAR'] = 'some value'

   This will probably not work well in Jython, though.
   
   The environment variables used by Anygui are:
   
   ANYGUI_WISHLIST: A whitespace separated list of backend names in the
   order you wish for Anygui to try to use them. The backends are
   identified with a short prefix such as wx for wxgui, or tk for tkgui.
   For a full list of available backends, see the section "Making Sure
   You Have a GUI Backend" above. Only the backends in this list will be
   tried; if you don't set ANYGUI_WISHLIST, then the following is the
   default:

      'msw gtk java wx tk beos qt curses text'

   If you insert an asterisk in the wishlist, it will be interpreted as
   "the rest of the backends, in default order". So, for instance,

      ANYGUI_WISHLIST='tk wx * text curses'

   is equivalent to

      ANYGUI_WISHLIST='tk wx msq gtk java beos qt text curses'

   Example:

      foo:~$ ANYGUI_WISHLIST='tk wx qt' python someprogram.py

   ANYGUI_DEBUG: When Anygui tries to import a backend, it hides all
   exceptions, assuming they are caused by the fact that a given backend
   doesn't work in your installation (because you don't have it installed
   or something similar). However, at times this may not be the reason;
   it may simple be that a given backend contains a bug. To track down
   the bug, set the ANYGUI_WISHLIST to some true (in a Python sense)
   value. (If the value supplied can be converted to an integer, it will.
   Otherwise, it will be treated as a string.) This will make Anygui
   print out the stack traces from each backend it tries to import.
   
   There is one exception to this rule: If the true value supplied is the
   name of one of the backends (such as tk or curses) only the traceback
   caused by importing that backend will be shown. This can be useful to
   make the output somewhat less verbose.
   
   Example:

      foo:~$ ANYGUI_DEBUG=1 python someprogram.py

   ANYGUI_ALTERNATE_BORDER: This Boolean variable affects cursesgui,
   making it use the same border-drawing characters as textgui ('+', '-',
   and '|'). This may be useful if your terminal can't show the special
   curses box-drawing characters properly.
   
   ANYGUI_SCREENSIZE: Affects textgui. Gives the terminal ("screen")
   dimensions, in characters. This should be in the format widthxheight,
   e.g. 80x24. If this environment variable is not supplied, the standard
   Unix variables COLUMNS and LINES will be used. If neither is provided,
   the default size 80x23 will be used.
   
   ANYGUI_FORCE_CURSES: Normally, cursesgui will not be selected if you
   are in the interactive interpreter. If you want to force the normal
   selection order (trying to use cursesgui before resorting to textgui)
   you can set this variable to a true value. Note that this is not the
   same as setting ANYGUI_WISHLIST to 'curses', since that will ignore
   all other backends.
   
   ANYGUI_CURSES_NOHELP: If you don't want the help-screen that appears
   when an Anygui application is started using cursesgui (or textgui),
   you can set this variable to a true value.
   
  4.2 Global Functions
  
   application()
   
   Returns the current Application object.
   
   backend()
   
   Returns the name (as used in ANYGUI_WISHLIST) of the backend currently
   in use.
   
   Example:

      if backend() == 'wx':
          some_wx_code()
      else:
          some_generic_code()

   link(source, [event,] handler, weak=0, loop=0)
   
   Creates a link in the Anygui event system, between the source (any
   object) and the handler (any callable, or a (obj,func) pair, where
   func is an unbound method or function, and obj is an object which will
   be supplied as the first parameter to func). Supplying an event (a
   string) will make the link carry only information about events of that
   type. If no event is supplied, 'default' will be assumed. Setting weak
   to a true value will use weak references when setting up the link, so
   that no objects will be "kept alive" by the link.
   
   A send-loop occurs if an object sends an event "to itself" (i.e. it is
   the source argument of a call to send which hasn't returned at the
   point where one of its methods are about to be activated as a
   handler). The truth value loop decides whether this handler will be
   activated in such a loop. (If send was called with loop=1, loops will
   be allowed anyway.)
   
   Note that source, event, and handler are strictly positional
   parameters, while the others (weak, and loop) must be supplied as
   keyword parameters.
   
   Sometimes one might want an event handler that reacts to a specific
   event from any source, or any event from a specific source; or even
   any event from any source. To do that, simply use the special value
   any as either source, event, or both.
   
   Example:

      from anygui import *
      >>> def monitor_events(event, **kw):
      ...     print 'An event occurred:', event
      ...
      >>> link(any, any, monitor_events)
      >>> btn = Button()
      >>> send(btn, 'foobar')
      An event occurred: foobar

   If you use send(btn, 'click') in this example, you will get two
   events, since the Button will detect the click event (which is its
   default), and issue a default event as well.
   
   Note: You need to explicitly supply the event type if you want to
   respond to any event type; otherwise you will only respond to the
   default type.
   
   Event handlers that react to the same event will be called in the
   order they were registered (with link), subject to the following: (1)
   All handlers registered with a specific source will be called before
   handlers with the value any as source; (2) all handlers registered
   with a specific event (including default) are called before handlers
   with the value any as event.
   
   For more information on sending events, see send, below.
   
   send(source, event='default', loop=0, **kwds)
   
   When this is called, any handlers (callables) linked to the source,
   but which will not cause a send-loop (unless loop is true) will be
   called with all the keyword arguments provided (except loop), in the
   order in which they were linked. In addition to the supplied keyword
   arguments, the event framework will add source, event, and the time
   (as measured by the standard Python function time.time) when send was
   called, supplied with the time argument.
   
   Note that source, and event, are strictly positional parameters, while
   the others (loop, and any additional arguments the user might add)
   must be supplied as keyword parameters.
   
   Example:

      # Link an event handler to a button, and then manually send a
      # default event from the button. This event would have been
      # sent automatically if we clicked the button. Note that we
      # only use the arguments we need, and lump the rest in **kw.
      
      def click(source, time, **kw):
          print 'Button %s clicked at %f.' % (source.text, time)
      
      btn = Button(text='Click me')
      link(btn, click)
      
      send(btn) # Fake a button click -- will call click()

   For information about the order in which event handlers are called,
   see link, above.
   
   Important: Due to the current semantics of the any value, using it in
   send may not be a good idea, since the result might not be what you
   expect. For instance, calling send(any, any) will only activate event
   handlers which have been linked to the value any as both source and
   event, not to "event handlers with any source and any event". This may
   change in future releases. The current behaviour of send with any is
   consistent with unlink.
   
   unlink(source, [event,] handler)
   
   Undoes a call to link with the same positional arguments. If handler
   has been registered with either source or event as any, that parameter
   will be irrelevant when deciding whether or not to remove that link.
   For instance:

      link(foo, any, bar)
      unlink(foo, baz, bar)

   Here the link created by link(foo, any, bar) will be removed by the
   call to unlink.
   
   Note: This behaviour (unlinking handlers registered with the any
   value) may change in future releases.
   
   Default Events: When used without the event argument, both link and
   send use an event type called default. Most event-generating
   components have a default event type, such as click for Buttons. The
   fact that this event type is default for Button means that when a
   Button generates a click event it will also generate a default event.
   So, if you listen to both click events and default events from a
   Button, your event handler will always be called twice.
   
   unlinkHandler(handler)
   
   Removes a handler completely from the event framework.
   
   unlinkMethods(obj)
   
   Unlinks all handlers that are methods of obj.
   
   unlinkSource(source)
   
   Remove the source (and all handlers linked to it) from the event
   framework.
   
  4.3 Classes
  
   Base Classes and Common Behaviour
   
   All components are subclasses of corresponding abstract components
   which implement behaviour common to all the backends. So, for
   instance, Button subclasses AbstractButton. These abstract components,
   again, subclass AbstractComponent, which implements behaviour common
   to all components.
   
   Perhaps the most important behaviour is attribute handling (inherited
   from the Attrib mixin), which means that setting a components
   attributes may trigger some internal method calls. For instance,

      win.size = 300, 200

   will automatically resize the component win. Attributes common to all
   components are:

      x         -- x-coordinate of upper left corner
      y         -- y-coordinate of upper left corner
      position  -- equivalent to (x, y)
      width     -- component width
      height    -- component height
      size      -- equivalent to (width, height)
      geometry  -- equivalent to (x, y, width, height)
      visible   -- whether the component is visible
      enabled   -- whether the component is enabled
      text      -- text associated with the component

   These can all be set as keyword arguments to the component
   constructors. Also, Options objects (with similar constructors) can be
   used as positional arguments in the constructor, with all the
   Options's attributes being set in the component as well.
   
   Common to Application, Window, and Frame is the contents attribute, as
   well as the add and remove methods. These will be described with the
   individual classes below.
   
   All Attrib subclasses (including components, Application, and
   RadioGroup) share the following methods:
   
   set(*args, **kwds)
   
   Used to set attributes. Works like the Attrib constructor, setting
   attributes, and optionally using Options objects.
   
   modify(*args, **kwds)
   
   Works like the set method, except that the attributes are modified in
   place. That means the following (for an attribute named foo): (1) If
   there exists an internal method (implemented in Anygui) for modifying
   the attribute inplace (called _modify_foo), use that; otherwise (2)
   try to use slice assignment to change the value (will work for lists
   and ListModels etc.); if that doesn't work, (3) assign to the value's
   value attribute (used to modify Models. If neither of these approaches
   work, simply rebind the attribute (equivalent to using the set
   method).
   
   As with set and ordinary attribute assignment, the refresh method will
   automatically be called when you use modify.
   
   refresh()
   
   When an attribute of a Component (or Application, RadioGroup, or an
   instance of another Attrib subclass) is assigned a value, the
   Component is automatically updated to reflect its new state. For
   instance, if you have a Labellbl, assigning a value to lbl.geometry
   would immediately change the Label's geometry, and assigning to
   lbl.text would change its text.
   
   This is good enough for most cases, but sometimes an attribute can
   contain a mutable value, such as a list, and changing that will not
   update the Component. For instance, if you use a list to hold the
   items of a ListBox, you could end up in the following situation:

      lbx = ListBox()
      lbx.items = 'first second third'.split()
      # More code...
      lbx.items.append('fourth')

   After performing this code, nothing will have happened to the ListBox,
   because it has no way of knowing that the list has changed. To fix
   that, you can simply call its refresh method:

      lbx.refresh()

   This method checks whether any attributes have changed, and make sure
   that the Component us up to date.
   
   Updating Automatically
   
   Updating Components explicitly can be useful, but sometimes you would
   want it to be done for you, automatically, each time you modify an
   object that is referred to by a Component attribute. This can be taken
   care of by link and send. If your object uses send every time it's
   modified, and you link the object to your Component's refresh method,
   things will happen by themselves:

      class TriggerList:
          def __init__(self):
              self.list = []
          def append(self, obj):
              self.list.append(obj)
              send(self)
          def __getitem__(self, i):
              return self.list[i]
      
      lbx = ListBox()
      lbx.items = TriggerList()
      link(lbx.items, lbx.refresh)

   Now, if we call lbx.items.append('fourth'), lbx.refresh will
   automatically be called. To make your life easier, Anygui already
   contains some classes that send signals whend they are modified; these
   classes are called Models.
   
   Model and Assignee
   
   The Anygui models (BooleanModel, ListModel, TextModel, and
   NumberModel) are objects that call send (with the 'default' event)
   when they are modified.
   
   An Assignee (part of the Anygui Model-View-Controller mechanism) is an
   object that supports the methods assigned and removed. These are
   automatically called (if present) when the object is assigned to one
   of the attributes of an Attrib object (such as a Component). Models
   use this behaviour to automatically call link and unlink, so when the
   Model is modified, the refresh method of the Attrib object is called
   automatically.
   
   All models have a value attribute, which contains a "simple" version
   of its state (such as a number for NumberModel, a list for ListModel,
   etc.) Assigning to this attribute is a simple way of modifying the
   model in place.
   
   class Application
   
   To instantiate Windows, you must have an Application to manage them.
   You typically instantiate an application at the beginning of your
   program:

      app = Application()
      # Build GUI and run application

   In some cases subclassing Application might be a useful way of
   structuring your program, but it is in no way required.
   
   Application has the following methods:
   
   run()
   
   Starts the main event loop of the graphical user interface. Usually
   called at the end of the program which set up the interface:

      app = Application()
      # Set up interface
      app.run()

   add(win)
   
   Adds a Window to the Application, in the same way Components can be
   added to Frames (see below). A Window will not be visible until it has
   been added to the current Application object, and that Application is
   running. When constructing new Windows after Application.run has been
   called, you should ensure that you add your Window to your running
   Application after all the Components have been added to your Window;
   otherwise, you may see them appearing and moving about as Anygui takes
   care of the layout. (Before Application.run is called, this is not an
   issue, since no Windows will be appear before that time.)
   
   The parameter win can be either a single Window, or a sequence of
   Windows.
   
   remove(win)
   
   Removes a Window from the application. This will make the Window
   disappear.
   
   contents
   
   A read-only property containing a tuple of the Windows the Application
   currently manages.
   
   class Button
   
   A component which, when pressed, generate a 'click' event, as well as
   a 'default' event. Thus, in the following example, both handler1 and
   handler2 will be called when the button is pressed:

      btn = Button()
      def handler1(**kw): print 'Handler 1'
      def handler2(**kw): print 'Handler 2'
      link(btn, 'click', handler1)
      link(btn, handler2)

   class CheckBox
   
   CheckBox is a kind of button, and thus will also generate 'click' and
   'default' events when clicked. But in addition, each CheckBox has a
   Boolean attribute on, which is toggled each time the box is clicked.
   The state of the CheckBox can be altered by assigning to this
   attribute.
   
   The on property will be automatically modified (as per the MVC
   mechanism) when the user clicks the CheckBox. This will also cause the
   CheckBox to send a click and a defaultevent.
   
   The on attribute is a useful place to use a BooleanModel.
   
   class Frame
   
   Frame is a component which can contain other components. Components
   are added to the Frame with the add method:
   
   add(comp, [opts,] **kwds)
   
   Adds one or more components. The parameter comp may be either a single
   component, or a sequence of components. In the latter case, all the
   components will be added.
   
   The opts parameter containes an Options object (see below) which gives
   information about how the object should be laid out. These options can
   be overridden with keyword arguments, and all this information will be
   passed to the LayoutManager (see below) of the Frame, if any. This
   LayoutManager is stored in the layout property.
   
   remove(comp)
   
   Removes a component from the Frame.
   
   contents
   
   This is a read-only property which contains the contents (a tuple of
   Components) of the Frame.
   
   class Label
   
   A Label is a simple component which displays a string of text. (Label
   can only handle one line of text.)
   
   class LayoutManager
   
   A layout manager is responsible for setting the geometry properties of
   a set of components when their parent Frame changes shape. The default
   LayoutManager (and the only one supplied with the current release) is
   the Placer (see below).
   
   Note: Although Anygui 0.1 comes only with this layout manager, more
   will appear in the future.
   
   class ListBox
   
   Shows a list of options, of which one may be selected. The ListBox has
   two special attributes: items, a sequence of items to display, and
   selection, the currently selected (as an index in the items sequence).
   
   The selection property will be automatically modified (as per the MVC
   mechanism) when the user makes a selection. This will also cause the
   ListBox to send a select and a defaultevent.
   
   class Model
   
   See the section on Model and Assignee above.
   
   class Options
   
   Options is a very simple class. It is simply used to store a bunch of
   named values; basically a dictionary with a different syntax. (For
   more information about the bunch class, see
   http://aspn.activestate.com/ASPN/Cookbook/Python/Recipe/52308.)
   
   You can set the attributes of an Options object and then supply it as
   an optional first parameter to the constructors of widgets:

      opt = Options()
      opt.width = 100
      opt.height = 50
      opt.x = 10
      btn = Button(opt, y=10)
      lbl = Label(opt, y=70)

   Here btn and lbl will have the same width, height, and x attributes,
   but differing y attributes.
   
   You can also set the attributes of an Options object through its
   constructur, just like with components:

      opt = Options(width=100, height=50, x=10)

   Options objects can also be used when supplying arguments to the add
   method of Frame:

      # Assuming a Placer LayoutManager:
      opt = Options(left=10, right=10, hstretch=1)
      win.add(lbl, opt, top=10)
      win.add(btn, opt, top=(lbl,10))

   class Placer
   
   A simple but powerful layout manager. When adding components to a
   Frame whose layout attribute is set to a Placer, you can supply the
   following keyword arguments:

      left         -- the Component's left edge
      right        -- the Component's right edge
      top          -- the Component's top edge
      bottom       -- the Component's bottom edge
      hmove        -- move horizontally on resize
      vmove        -- move vertically on resize
      hstretch     -- stretch horizontally on resize
      vstretch     -- stretch vertically on resize
      direction    -- 'left', 'right', 'up', or 'down'
      space        -- spacing between multiple Components

   The geometry specifiers (left, right, top, and bottom) can be set to
   either None (the default; will use the Component's existing
   coordinates), a distance (from the corresponding Frame edge), a
   Component (will align the edge with the opposite edge of the given
   component), or a tuple (component, distance) (as with only a
   Component, except that a gap of size distance is inserted between the
   two).
   
   The movement arguments (hmove and vmove) specify (with a Boolean
   value) whether the Component should be moved (horizontally,
   vertically, or both) to maintain the given distance to the surrounding
   Frame's edges; the stretching arguments (hstretch and vstretch)
   specify whether the Component may be stretched to maintain these
   distances.
   
   class RadioButton
   
   A RadioButton is a toggle button, just like CheckBox, with slightly
   different appearance, and with the difference that it belongs to a
   RadioGroup. Only one RadioButton can be active (have its on attribute
   be a true Boolean value)in the RadioGroup at one time, so when one is
   clicked or programmatically turned on, the others are automatically
   switched off by the RadioGroup. Each RadioButton also has a value
   attribute, which should be unique within its RadioGroup. When one
   RadioButton is active, the value attribute of its RadioGroup is
   automatically set to that of the active RadioButton. The RadioGroup of
   a RadioButton is set by assigning the RadioGroup to the group
   attribute of the RadioButton. Setting the value attribute of the
   RadioGroup will automatically activate the correct RadioButton.
   
   class RadioGroup
   
   See RadioButton above.
   
   class TextArea
   
   A multiline text-editing Component. Its text is stored in the text
   attribute, which will be modified (according to the MVC mechanism)
   when the component loses focus. It also supports the Boolean editable
   property, which may be used to control whether the user can edit the
   text area or not.
   
   class TextField
   
   A one-line text-editing Component. (See also TextArea, above.) If the
   enter/return key is pressed within a TextField, the TextField will
   send a enterkey event.
   
   class Window
   
   A window, plain and simple. Window is a type of Frame, so you can add
   components to it and set its layout property etc. To make your window
   appear, you must remember to add it to your Application, just like you
   add other components to Frames and Windows:

      win = Window()
      app = Application()
      app.add(win)
      app.run()

   Windows have a title attribute which may be used by the operating
   system or window manager to identify the window to the user in various
   ways.
   
5. Known Problems

   For an overview of known bugs in the current release, see the file
   KNOWN_BUGS found in the distribution.
   
6. Plans for Future Releases

   For an overview of future plans, see the TODO file found in the
   distribution.
   
7. Contributing

   If you want to contribute to the Anygui project, we could certainly
   use your help. First of all, you should visit the Anygui web site at
   http://www.anygui.org, subscribe to the developer's mailing list
   (devel@anygui.org) and the user's list (users@anygui.org), and try to
   familiarise yourself with how the package works behind the scenes.
   Then, you may either help develop the currently supported GUI
   packages, or you may start writing a backend of your own. Several
   potential backend targets may be found at
   http://starbase.neosoft.com/~claird/comp.lang.python/python_GUI.html.
   
8. Anygui License

   Copyright © 2001, 2002 Magnus Lie Hetland, Thomas Heller, Alex
   Martelli, Greg Ewing, Joseph A. Knapka, Matthew Schinckel, Kalle
   Svensson, Shanky Tiwari, Laura Creighton, Dallas T. Johnston, Patrick
   K. O'Brien. .
   
   Permission is hereby granted, free of charge, to any person obtaining
   a copy of this software and associated documentation files (the
   "Software"), to deal in the Software without restriction, including
   without limitation the rights to use, copy, modify, merge, publish,
   distribute, sublicense, and/or sell copies of the Software, and to
   permit persons to whom the Software is furnished to do so, subject to
   the following conditions:
   
   The above copyright notice and this permission notice shall be
   included in all copies or substantial portions of the Software.
   
   THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND,
   EXPRESS OR IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF
   MERCHANTABILITY, FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT.
   IN NO EVENT SHALL THE AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY
   CLAIM, DAMAGES OR OTHER LIABILITY, WHETHER IN AN ACTION OF CONTRACT,
   TORT OR OTHERWISE, ARISING FROM, OUT OF OR IN CONNECTION WITH THE
   SOFTWARE OR THE USE OR OTHER DEALINGS IN THE SOFTWARE.
