Rivet Programming Reference

Index

Overview

Background

Rivet is a Python programming interface to the Tk toolkit (of Tcl/Tk fame). Rivet is object oriented, and easy to learn. Although the Rivet interface is intentionally organized similar to the Tcl's Tk interface, a distinguishing feature of Rivet's implementation is that it contains no Tcl code.

This document covers the Python interface to Rivet. Other documentation covering the C interface, is to be determined. This document does not try to describe all the features of Tk, for that you should refer to material available for Tcl/Tk. (Translating from Tcl/Tk to Rivet is really easy.) Books on Tcl/Tk are suggested reading material. See http://www.sunlabs.com/research/tcl/docs.html for more information on available documentation.

The Basics

The Rivet interface is built as a python module. A python program gets access to it using the import statement (e.g. import rivet). There is also a collection of utilities in rivetutil.py, discussed later.

A rivetobj is the python object representing a tk "widget". These objects are created by functions in the rivet module. Typically, an application begins with the following statements: 

	import rivet
	top = rivet.init()
In this example, top is a rivetobj that represents the topmost widget in a tk application (known to Tcl/Tk programmers as "."). This widget may then be used to create more widgets. For example, This code creates a scale widget inside the top widget, packs it, and runs the event loop: 
	widget1 = rivet.scale(top)
	rivet.pack(widget1)
	rivet.mainloop()
Some widgets have convenience methods for shorthand creation of other widgets. The toplevel widget, for example, has button, checkbutton, etc. So the creation of widget1 in the previous example may be shortened to: 
	widget1 = top.scale()

Each rivetobj has a dictionary attached to it. This dictionary is intended to be used by applications, and it is not used by rivet internally. The dictionary can be populated using python instance.attribute notation. (E.g. "widget1.myname = 1" assigns "myname" to 1, "dir(widget1)" will report the keys in the dictionary, "del widget1.myname" will remove the reference from the dictionary, etc.) Attaching data to widget objects is a significant departure from the Tcl/Tk model, the main benefit from this appears to be less reliance on global variables.

Life Cycle Issues

Rivetobjs are created with an additional reference from the parent widget. As a result, they are not necessarily garbage collected (and destroyed) when all your references to it are removed. This relieves you from maintaining an additional reference to ensure the widget still exists.

Rivetobjs are explicitly destroyed by calling rivet.destroy(). This also destroys any rivetobjs that were created inside of the destroyed rivetobj, as well as releasing any references to callbacks used by the objects. A program may continue to have references to destroyed rivetobjs, but these references are essentially useless, and referring to any attribute of such a rivetobj will raise an exception.

Passing Parameters

Many rivet functions take an arbitrary number of parameters, depending on the function and its use. These typically appear in the same order as they would in Tcl/Tk. Arguments to rivet functions may be strings, integers, floats, but also may be lists, tuples, and dictionaries. Because the more complicated sequence and mapping types have no meaning to Tk, these are recursively flattened. Dictionaries are handled specially, the keys of dictionary elements are assumed to be tk attribute names and are automatically prepended with a hypen as required by tk. The following sets of statements illustrate equivalent operations: 

	widget1.configure( '-bg', 'white', '-fg', 'red', '-bd', 3)
	widget1.configure( {'bg': 'white'}, ('-fg', 'red'), ['-bd', 3])
	widget1.configure( bg='white', fg='red', bd=3 )

	rivet.pack(widget1, '-side', 'left', ('-fill', 'both'), '-expand', 1)
	rivet.pack(widget1, {'side':'left', 'fill':'both', 'expand':1})
	rivet.pack(widget1, side='left', fill='both', expand=1)
The keyword arguments only work in Python1.3 or greater, of course. These give the cleanest looking syntax.

One interesting trick to shorten code or to ease porting from Tcl/Tk is to use python's split function to simplify argument processing. For example, the following two examples have the same effect: 

	widget1.configure('-bg', 'white', '-fg', 'black',
			'-relief', 'raised', '-bd', 3)

	import string
	spl = string.split
	widget1.configure(spl('-bg white -fg black -relief raised -bd 3'))

Callbacks

Callbacks can be passed as arguments using two forms: a callable without arguments, or a callable as the first item in a tuple with an arbitrary number of additional parameters (the parameters are passed to the callback when it is invoked). Callables may be builtins, python defined functions, and python instance-methods. The use of tuples with callbacks is the one exception to the flattening of function arguments as stated above.

In some cases, parameters to callables are prepended with data. For example, the command callback for a scale always receives a float object representing the new position of the scale as its first argument. The following sample implements a callback for the ongoing example, using a tuple declaration of the callback to pass in a printable message: 

	def scale_moved(newvalue, message):
		print message, newvalue

	widget1.configure(command = (scale_moved, 'The new value is:'))
Using Rivet with Python Classes

To enable building abstractions for collections of widgets, object instances that contain rivetobjs may be used as arguments to rivet functions if they follow a naming convention. This convention uses a "__widget" attribute. For example, here is an example of a scale widget class wink built using trivial classes: 

	import rivet
	
	class nudge:
		def __init__(self):
			self.__widget = rivet.init()

	class wink:
		def __init__(self, parent, *initialoptions1, **initialoptions2):
			self.__widget = rivet.scale(parent,
					    initialoptions1, initialoptions2)

		__getattr__ = rivet.__getattr__

	top = nudge()
	widget1 = wink(top, showvalue=0)
	widget1.pack()
	rivet.mainloop()
The function rivet.__getattr__ allows instances to "inherit" the functions from the widgets that they wrap. The usage widget1.pack() above is an example of this: pack is a method of the scale object and available to the instance through python's __getattr__ mechanism.

The wink.__init__ method declaration shows how to declare and pass arguments so that initial tk configuration options are passed along with the creation of the widget. See the python documentation for more details on variable argument length and keyword arguments.

Using Variables

Tk has it's own set of variables that you can get access to through the stringvar, intvar, and floatvar classes. These are defined in rivetutil.py. You may subclass from these classes for other types. Once instanciated, you may change the value of the variable with the set method, retrieve its value with the get method, monitor changes to it with the trace method. You can also pass the variable instance to a rivet function. Typically, this is used with variable options on widgets. For example, the varexample.py sample program makes use of this to automatically update the contents of a label widget based on the value of a scale widget.

There is a lower level set of variable manipulation routines defined inside the rivet module, but these are not recommended for use.

Comparison to Tcl/Tk

Rivet is very much like Tcl/Tk in many respects. There are a few comparisons that can be made to illuminate the differences:

  • Rivet is organized as a Python module. The functions that appear in the rivet module are similar to Tk commands appearing in Tcl's global namespace.
  • Creating a rivet object does not create a global command, but creates a new python object.
  • Rivet objects use an object oriented programming interface. This applies to rivet objects and their methods, but also applies to various other things such as image and timer objects.
  • The dictionaries on rivet objects provide the means to associate arbitrary data with an object, reducing the need for global associative arrays.
  • Return types from rivet functions are native python types.
  • Rivet provides a flexible parameter passing interface.
    •

    Interface Summary

    In the following, most functions take an arbitrary set of arguments, unless explicitly noted. The order of the arguments usually maps directly to that in Tk (one notable exception is shorthand methods). Return values with more than one result are always wrapped in a tuple, regardless of the number of values.

    after
    Schedules a callback to be invoked later, and returns an object that can be used to cancel the invocation. If no callback is specified, execution will pause for the time specified. 

    	Example:
	timer1 = rivet.after(1000, callback)
	timer2 = rivet.after('idle', callback)
	timer2.cancel()

    bell
    Rings the display bell. Pass either no arguments for the default display or a rivetobj from which to determine the display.

    bind
    Set or query bindings for a rivetobj. Usually you pass in a rivetobj or instance for the first argument, but you can also pass in a string for the first argument to set or query a class of bindings. 

    	Usage:					Returns:

	rivet.bind(id)				String description of bindings
	rivet.bind(id, string)			Tuple of callbacks
	rivet.bind(id, string, callback)	None
	rivet.bind(id, string, callback, append) None
    Where append is any value.

    id indicates a class name (a string), a rivetobj, or an instance. As a string, class name refers to the Tk id for a class, such as "Button", "Scale", or may be a set of bindings of your own creation for use with rivet.bindtags.

    A shorthand method exists for this function. For example widget1.bind('<1>', callback, 1) is equivalent to rivet.bind(widget1, '<1>', callback, 1).

    The callback may be a simple callable, or it may be a tuple with the first item as a callable. The remaining tuple items have special meaning if they are string objects with the first character as a percent symbol. These items are substituted with values (either a string or an integer) when the event occurs. These conversions correspond directly to substitutions done by Tcl/Tk's bind. The following example illustrates this feature. 

    
	import rivet

	def print_click_position(widget, xposition, yposition):
		print 'widget ', widget, 'clicked at', xposition, yposition

	top = rivet.init()
	button = top.button('-text', 'click me')
	button.bind('<1>', (print_click_position, '%w', '%x', '%y'), 1)
	rivet.mainloop()
    A function invoked by bind returning anything other than None will stop any further invocations of function invocations for bindings that match that event. None is equivalent to Tk's continue, and any other value is equivalent to Tk's break.

    bindtags
    Implements Tk's bindtags features. 

    	Usage:					Returns:

	rivet.bindtags(rivetobj)		Tuple of rivetobjs and strings
	rivet.bindtags(rivetobj, ...)		None

    clipboard
    Manipulates the Tk clipboard. 

    	Usage:					Returns:

	rivet.clipboard.clear(...)		None
	rivet.clipboard.append(...)		None

    destroy
    Destroys a Tk object. 

    	Usage:					Returns:

	rivet.destroy(id)			None
    Where id is a rivetobj or a instance.

    fileevent
    Given a file descriptor, a mode ("readable" or "writeable") and a function, fileevent schedules a callback to be invoked when I/O is ready. Without a callback arg, this returns the function assigned previously. The callback may be removed by passing in None for the third argument. The file descriptor should be an unbuffered file object, such as a pipe. 

    	Usage:					Returns:
	rivet.fileevent(fd, mode, callback)	None
    focus
    Manage the input focus. 
    	Usage:					Returns:

	rivet.focus()				A Rivetobj or None
	rivet.focus(...)			A string object

    getvar

    The routines getvar, setvar, unsetvar, tracevar, and untracevar are lowlevel routines to manage tk variables. The recommended interfaces are the stringvar, intvar, and floatvar classes in rivetutil.py.

    grab
    Confine pointer and keyboard events to a window sub-tree. 

    	Usage:					Returns:

	rivet.grab.current(...)			A tuple of Rivetobjs
	rivet.grab.release(...)			None
	rivet.grab.set(...)			None
	rivet.grab.status(...)			A String object or None
    image
    Create and manipulate images. 
    	Usage:					Returns:

	rivet.image.create(...)			Rivet image object
	rivet.image.delete(Rivet image object)	None
	rivet.image.height(Rivet image object)	Int
	rivet.image.width(Rivet image object)	Int
	rivet.image.names()			A dictionary
	rivet.image.types()			A tuple of strings
	rivet.image.type(Rivet image object)	String

    Rivet "bitmap" image objects have the following methods: 

    	bitmap_image.cget(optionname)		depends on argument
	bitmap_image.configure(...)		depends on arguments

    Rivet "photo" image objects have the following methods: 

    	photo_image.blank(...)			A string or None
	photo_image.cget(optionname)		depends on argument
	photo_image.configure(...)		depends on arguments
	photo_image.copy(...)			A string or None
	photo_image.get(...)			A tuple of ints
	photo_image.put(...)			A string or None
	photo_image.read(...)			A string or None
	photo_image.redither()			None
	photo_image.write(...)			A string or None

    init
    Initialize rivet. The arguments may specify the values for any of the following attributes "-display", "-geometry", "-name", "-sync". 

    	Usage:					Returns:

	rivet.init(...)				The "." rivetobj
    lower
    Lowers a windows position in the window stacking order. 
    	Usage:					Returns:

	rivet.lower(...)			None
    mainloop
    Run the event processing loop. 
    	Usage:

	rivet.mainloop()			None.
    mainwidget
    Returns the topmost rivetobj (equivalent to tk's "." widget). 
    	Usage:					Returns:

	rivet.mainwidget()			The "." rivetobj
    option
    Add/retrieve window options to/from the option database 
    	Usage:					Returns:

	rivet.option.add(...)			None
	rivet.option.clear()			None
	rivet.option.get(...)			A string or None
	rivet.option.readfile(...)		None
    pack
    The infamous packer. 
    	Usage:					Returns:

	rivet.pack(...)				None
	rivet.pack.forget(rivetobj)		None
	rivet.pack.info(rivetobj)		A tuple containing pack information
	rivet.pack.propagate(...)		A string or None
	rivet.pack.slaves(rivetobj)		A tuple of rivetobjs.
    place
    The pack geometry manager. 
    	Usage:					Returns:

	rivet.place(...)			None
	rivet.place.forget(rivetobj)		None
	rivet.place.info(rivetobj)		A tuple containing pack information
	rivet.place.propagate(...)		A string or None
	rivet.place.slaves(rivetobj)		A tuple of rivetobjs.
    raise
    Raises a windows position in the window stacking order. 
    	Usage:					Returns:

	rivet.raise(...)			None
    selection
    Manipulate the X selection. 
    	Usage:					Returns:

	rivet.selection.clear(...)		None
	rivet.selection.get(...)		A string
	rivet.selection.handle(...)		None
	rivet.selection.own(...)		None
    setvar
    The routines getvar, setvar, unsetvar, tracevar, and untracevar are lowlevel routines to manage tk variables. The recommended interfaces are the stringvar, intvar, and floatvar classes in rivetutil.py.
    tk_appname
    Sets the name of the application. Typically used for setting the main window's title string. 
    	Usage:					Returns:

	rivet.tk_appname(...)			The current value, a string.
    tkwait
    	Usage:					Returns:

	rivet.tkwait.variable(...)		none
	rivet.tkwait.visibility(...)		none
	rivet.tkwait.window(...)		none
    tracevar
    The routines getvar, setvar, unsetvar, tracevar, and untracevar are lowlevel routines to manage tk variables. The recommended interfaces are the stringvar, intvar, and floatvar classes in rivetutil.py.
    unsetvar
    The routines getvar, setvar, unsetvar, tracevar, and untracevar are lowlevel routines to manage tk variables. The recommended interfaces are the stringvar, intvar, and floatvar classes in rivetutil.py.
    untracevar
    The routines getvar, setvar, unsetvar, tracevar, and untracevar are lowlevel routines to manage tk variables. The recommended interfaces are the stringvar, intvar, and floatvar classes in rivetutil.py.
    update
    	Usage:					Returns:

	rivet.update()				none
	rivet.update('idletasks')		none
    winfo
    Implements the Tk winfo command. 
    	Usage:					Returns:

	rivet.winfo.atom(...)			integer
	rivet.winfo.atomname(...)		string
	rivet.winfo.cells(...)			integer
	rivet.winfo.children(...)		tuple of rivetobjs
	rivet.winfo._class(...)			string (same as "winfo class")
	rivet.winfo.containing(...)		rivetobj
	rivet.winfo.depth(...)			integer
	rivet.winfo.exists(...)			integer
	rivet.winfo.fpixels(...)		float
	rivet.winfo.geometry(...)		string
	rivet.winfo.height(...)			integer
	rivet.winfo.id(...)			string
	rivet.winfo.ismapped(...)		integer
	rivet.winfo.manager(...)		string or none
	rivet.winfo.parent(...)			rivetobj
	rivet.winfo.pathname(...)		rivetobj
	rivet.winfo.pixels(...)			integer
	rivet.winfo.reqheight(...)		integer
	rivet.winfo.reqwidth(...)		integer
	rivet.winfo.rgb(...)			tuple of integers
	rivet.winfo.screen(...)			string
	rivet.winfo.screencells(...)		integer
	rivet.winfo.screendepth(...)		integer
	rivet.winfo.screenheight(...)		integer
	rivet.winfo.screenmmheight(...)		integer
	rivet.winfo.screenmmwidth(...)		integer
	rivet.winfo.screenvisual(...)		string
	rivet.winfo.screenwidth(...)		integer
	rivet.winfo.toplevel(...)		rivetobj
	rivet.winfo.viewable(...)		integer
	rivet.winfo.visual(...)			string or none
	rivet.winfo.visualsavailable(...)	string
	rivet.winfo.vrootheight(...)		integer
	rivet.winfo.vrootwidth(...)		integer
	rivet.winfo.vrootx(...)			integer
	rivet.winfo.vrooty(...)			integer
	rivet.winfo.width(...)			integer
	rivet.winfo.x(...)			integer
	rivet.winfo.y(...)			integer
    A Rivet equivalent for Tk's "winfo interps" or "winfo name" does not exist.

    wm
    Tk wm command. 

    	Usage:					Returns:

	rivet.wm.aspect(...)			tuple of integers
	rivet.wm.client(...)			string or none
	rivet.wm.colormapwindows(...)		tuple of rivetobjs
	rivet.wm.command(...)			string or none
	rivet.wm.deiconify(...)			none
	rivet.wm.focusmodel(...)		string
	rivet.wm.frame(...)			string
	rivet.wm.geometry(...)			string
	rivet.wm.grid(...)			tuple of integers
	rivet.wm.group(...)			rivetobj
	rivet.wm.iconbitmap(...)		string
	rivet.wm.iconify(...)			none
	rivet.wm.iconmask(...)			string
	rivet.wm.iconname(...)			string
	rivet.wm.iconposition(...)		tuple of integers
	rivet.wm.iconwindow(...)		rivetobj
	rivet.wm.maxsize(...)			tuple of integers
	rivet.wm.minsize(...)			tuple of integers
	rivet.wm.overrideredirect(...)		integer
	rivet.wm.positionfrom(...)		string or none
	rivet.wm.resizable(...)			tuple of integers
	rivet.wm.sizefrom(...)			string
	rivet.wm.state(...)			string or none
	rivet.wm.title(...)			string
	rivet.wm.tracing(...)			string
	rivet.wm.transient(...)			rivetobj
	rivet.wm.withdraw(...)			none
	rivet.wm.protocol(...)			tuple of strings|callback|none
    Widget Creation Commands

    These functions return a newly created rivetobj. The first parameter identifies the parent, the second parameter identifies the name of the widget (not the whole path as in Tcl/Tk, but it must start with a dot, as in ".mywidget"). The name parameter is optional, and is useful with the option database. Any remaining arguments are configuration options.

    rivet.button(...)
    rivet.canvas(...)
    rivet.checkbutton(...)
    rivet.entry(...)
    rivet.frame(...)
    rivet.label(...)
    rivet.listbox(...)
    rivet.menu(...)
    rivet.menubutton(...)
    rivet.message(...)
    rivet.radiobutton(...)
    rivet.scale(...)
    rivet.scrollbar(...)
    rivet.text(...)
    rivet.toplevel(...)
    Most rivetobjs have shorthands methods for creating children. For example, to create a new button under a frame, use the button method on the frame object. In this case the parent is implied and is not needed for the first argument. Shorthand for creation of widgets: 
    	newwidget = parentwidget.newwidgetclass([name], args...)
    Rivetobj Methods

    Each rivetobj has a number of methods associated with it, the set of methods available depends on the type of the widget.

    All rivetobjs have cget and configure methods, which preform identical to the Tk equivalent. The type of the return value to these operation depends on the arguments. For cget, it may be integer, float, string, callback, or rivetobj. For configure, it may be None if the option is being specified, a tuple describing the option (name, dbname, dbclass, default value, value), or a tuple of descriptive tuples.

    Most rivetobjs have these shorthand methods:

    menu, toplevel, pack, place, bind, parent, children, name, destroy.
    Where appropriate, rivetobjs have a larger set of these methods:
    button, canvas, checkbutton, entry, frame, label, listbox menu, menubutton, message, radiobutton, scale, scrollbar text, toplevel.
    The shorthand methods operate the same as the function by the same name in the rivet module, but self is automatically implied as the first parameter. For example, the following two statements are equivalent: 
    	rivet.pack(button1, side='left')
	button1.pack(side='left')
    Note for the canvas and text objects: The method tag_bind is binds an event to a canvas item callback, as provides the same functionality as Tk's canvas bind item method. The name has only been changed to avoid conflict with the bind shorthand method.

    button methods

    	Usage:					Returns:

	w.bind(...)				depends on arguments
	w.cget(...)				depends on arguments
	w.children(...)				tuple of rivetobjs
	w.configure(...)			depends on arguments
	w.destroy(...)				none
	w.flash(...)				none
	w.invoke(...)				none
	w.menu(...)				new menu rivetobj
	w.name()				a string, widget's resource id
	w.pack(...)				none
	w.parent(...)				rivetobj
	w.place(...)				none
	w.toplevel(...)				new toplevel rivetobj
    canvas methods
    	Usage:					Returns:

	w.addtag(...)				none
	w.bbox(...)				tuple of ints
	w.bind(...)				depends on arguments
	w.button(...)				new button rivetobj
	w.canvas(...)				new canvas rivetobj
	w.canvasx(...)				float
	w.canvasy(...)				float
	w.cget(...)				depends on arguments
	w.checkbutton(...)			new checkbutton rivetobj
	w.children(...)				tuple of rivetobjs
	w.configure(...)			depends on arguments
	w.coords(...)				tuple of ints
	w.create(...)				string
	w.dchars(...)				none
	w.delete(...)				none
	w.destroy(...)				none
	w.dtag(...)				none
	w.entry(...)				new entry rivetobj
	w.find(...)				typle of strings
	w.focus(...)				integer or none
	w.frame(...)				new frame rivetobj
	w.gettags(...)				tuple of strings
	w.icursor(...)				none
	w.index(...)				string
	w.insert(...)				none
	w.itemcget(...)				depends on arguments
	w.itemconfigure(...)			depends on arguments
	w.label(...)				new label rivetobj
	w.listbox(...)				new listbox rivetobj
	w.lower(...)				none
	w.menu(...)				new menu rivetobj
	w.menubutton(...)			new menubutton rivetobj
	w.message(...)				new message rivetobj
	w.name()				a string, widget's resource id
	w.move(...)				none
	w.pack(...)				none
	w.parent(...)				rivetobj
	w.place(...)				none
	w.postscript(...)			# not implemented yet
	w.radiobutton(...)			new radiobutton rivetobj
	w.raise(...)				none
	w.scale(...)				none
	w.scan_dragto(...)			none
	w.scan_mark(...)			none
	w.scrollbar(...)			new scrollbar rivetobj
	w.select_adjust(...)			none
	w.select_clear(...)			none
	w.select_from(...)			none
	w.select_item(...)			string
	w.select_to(...)			none
	w.tag_bind(...)				depends on arguments
	w.text(...)				new text rivetobj
	w.toplevel(...)				new toplevel rivetobj
	w.type(...)				string or none
	w.xview(...)				tuple of two floats or ()
	w.yview(...)				tuple of two floats or ()
    checkbutton methods
    	Usage:					Returns:

	w.bind(...)				depends on arguments
	w.cget(...)				depends on arguments
	w.children(...)				tuple of rivetobjs
	w.configure(...)			depends on arguments
	w.deselect(...)				none
	w.destroy(...)				none
	w.flash(...)				none
	w.invoke(...)				none
	w.menu(...)				new menu rivetobj
	w.name()				a string, widget's resource id
	w.pack(...)				none
	w.parent(...)				rivetobj
	w.place(...)				none
	w.select(...)				none
	w.toggle(...)				none
	w.toplevel(...)				new toplevel rivetobj
    entry methods
    	w.bind(...)				depends on arguments
	w.cget(...)				depends on arguments
	w.children(...)				tuple of rivetobjs
	w.configure(...)			depends on arguments
	w.delete(...)				none
	w.destroy(...)				none
	w.get(...)				string
	w.icursor(...)				none
	w.index(...)				int
	w.insert(...)				none
	w.menu(...)				new menu rivetobj
	w.name()				a string, widget's resource id
	w.pack(...)				none
	w.parent(...)				rivetobj
	w.place(...)				none
	w.scan_dragto(...)			none
	w.scan_mark(...)			none
	w.selection_adjust(...)			none
	w.selection_clear(...)			none
	w.selection_from(...)			none
	w.selection_present(...)		int
	w.selection_range(...)			none
	w.selection_to(...)			none
	w.toplevel(...)				new toplevel rivetobj
	w.xview(...)				tuple of two floats or ()
    frame methods
    	Usage:					Returns:

	w.bind(...)				depends on arguments
	w.button(...)				new button rivetobj
	w.canvas(...)				new canvas rivetobj
	w.cget(...)				depends on arguments
	w.checkbutton(...)			new checkbutton rivetobj
	w.children(...)				tuple of rivetobjs
	w.configure(...)			depends on arguments
	w.destroy(...)				none
	w.entry(...)				new entry rivetobj
	w.frame(...)				new frame rivetobj
	w.label(...)				new label rivetobj
	w.listbox(...)				new listbox rivetobj
	w.menu(...)				new menu rivetobj
	w.menubutton(...)			new menubutton rivetobj
	w.message(...)				new message rivetobj
	w.name()				a string, widget's resource id
	w.pack(...)				none
	w.parent(...)				rivetobj
	w.place(...)				none
	w.radiobutton(...)			new radiobutton rivetobj
	w.scale(...)				new scale rivetobj
	w.scrollbar(...)			new scrollbar rivetobj
	w.text(...)				new text rivetobj
	w.toplevel(...)				new toplevel rivetobj
    label methods
    	Usage:					Returns:

	w.bind(...)				depends on arguments
	w.button(...)				new button rivetobj
	w.canvas(...)				new canvas rivetobj
	w.cget(...)				depends on arguments
	w.checkbutton(...)			new checkbutton rivetobj
	w.children(...)				tuple of rivetobjs
	w.configure(...)			depends on arguments
	w.destroy(...)				none
	w.entry(...)				new entry rivetobj
	w.frame(...)				new frame rivetobj
	w.label(...)				new label rivetobj
	w.listbox(...)				new listbox rivetobj
	w.menu(...)				new menu rivetobj
	w.menubutton(...)			new menubutton rivetobj
	w.message(...)				new message rivetobj
	w.name()				a string, widget's resource id
	w.pack(...)				none
	w.parent(...)				rivetobj
	w.place(...)				none
	w.radiobutton(...)			new radiobutton rivetobj
	w.scale(...)				new scale rivetobj
	w.scrollbar(...)			new scrollbar rivetobj
	w.text(...)				new text rivetobj
	w.toplevel(...)				new toplevel rivetobj
    listbox methods
    	Usage:					Returns:

	w.activate(...)				none
	w.bbox(...)				tuple of ints
	w.bind(...)				depends on arguments
	w.cget(...)				depends on arguments
	w.children(...)				tuple of rivetobjs
	w.configure(...)			depends on arguments
	w.curselection(...)			tuple of ints
	w.delete(...)				none
	w.destroy(...)				none
	w.get(...)				a string (1 index given) or a
						tuple of strings (2 indexes)
	w.index(...)				integer
	w.insert(...)				none
	w.menu(...)				new menu rivetobj
	w.name()				a string, widget's resource id
	w.nearest(...)				integer
	w.pack(...)				none
	w.parent(...)				rivetobj
	w.place(...)				none
	w.scan_dragto(...)			none
	w.scan_mark(...)			none
	w.see(...)				none
	w.selection_anchor(...)			none
	w.selection_clear(...)			none
	w.selection_includes(...)		integer
	w.selection_set(...)			none
	w.size(...)				integer
	w.toplevel(...)				new toplevel rivetobj
	w.xview(...)				tuple of two floats or ()
	w.yview(...)				tuple of two floats or ()
    menu methods
    	Usage:					Returns:

	w.activate(...)				none
	w.add(...)				none
	w.bind(...)				depends on arguments
	w.cget(...)				depends on arguments
	w.children(...)				tuple of rivetobjs
	w.configure(...)			depends on arguments
	w.delete(...)				none
	w.destroy(...)				none
	w.entrycget(...)			depends on arguments
	w.entryconfigure(...)			depends on arguments
	w.index(...)				string
	w.insert(...)				none
	w.invoke(...)				none
	w.menu(...)				new menu rivetobj
	w.name()				a string, widget's resource id
	w.parent(...)				rivetobj
	w.post(...)				none
	w.postcascade(...)			none
	w.toplevel(...)				new toplevel rivetobj
	w.type(...)				string or none
	w.unpost(...)				none
	w.yposition(...)			integer
    menubutton methods
    	Usage:					Returns:

	w.bind(...)				depends on arguments
	w.button(...)				new button rivetobj
	w.canvas(...)				new canvas rivetobj
	w.cget(...)				depends on arguments
	w.checkbutton(...)			new checkbutton rivetobj
	w.children(...)				tuple of rivetobjs
	w.configure(...)			depends on arguments
	w.destroy(...)				none
	w.entry(...)				new entry rivetobj
	w.frame(...)				new frame rivetobj
	w.label(...)				new label rivetobj
	w.listbox(...)				new listbox rivetobj
	w.menu(...)				new menu rivetobj
	w.menubutton(...)			new menubutton rivetobj
	w.message(...)				new message rivetobj
	w.name()				a string, widget's resource id
	w.pack(...)				none
	w.parent(...)				rivetobj
	w.place(...)				none
	w.radiobutton(...)			new radiobutton rivetobj
	w.scale(...)				new scale rivetobj
	w.scrollbar(...)			new scrollbar rivetobj
	w.text(...)				new text rivetobj
	w.toplevel(...)				new toplevel rivetobj
    message methods
    	Usage:					Returns:

	w.bind(...)				depends on arguments
	w.button(...)				new button rivetobj
	w.canvas(...)				new canvas rivetobj
	w.cget(...)				depends on arguments
	w.checkbutton(...)			new checkbutton rivetobj
	w.children(...)				tuple of rivetobjs
	w.configure(...)			depends on arguments
	w.destroy(...)				none
	w.entry(...)				new entry rivetobj
	w.frame(...)				new frame rivetobj
	w.label(...)				new label rivetobj
	w.listbox(...)				new listbox rivetobj
	w.menu(...)				new menu rivetobj
	w.menubutton(...)			new menubutton rivetobj
	w.message(...)				new message rivetobj
	w.name()				a string, widget's resource id
	w.pack(...)				none
	w.parent(...)				rivetobj
	w.place(...)				none
	w.radiobutton(...)			new radiobutton rivetobj
	w.scale(...)				new scale rivetobj
	w.scrollbar(...)			new scrollbar rivetobj
	w.text(...)				new text rivetobj
	w.toplevel(...)				new toplevel rivetobj
    radiobutton methods
    	Usage:					Returns:

	w.bind(...)				depends on arguments
	w.cget(...)				depends on arguments
	w.children(...)				tuple of rivetobjs
	w.configure(...)			depends on arguments
	w.deselect(...)				none
	w.destroy(...)				none
	w.flash(...)				none
	w.invoke(...)				none
	w.menu(...)				new menu rivetobj
	w.name()				a string, widget's resource id
	w.pack(...)				none
	w.parent(...)				rivetobj
	w.place(...)				none
	w.select(...)				none
	w.toplevel(...)				new toplevel rivetobj
    scale methods
    	Usage:					Returns:

	w.bind(...)				depends on arguments
	w.cget(...)				depends on arguments
	w.children(...)				tuple of rivetobjs
	w.configure(...)			depends on arguments
	w.coords(...)				tuple of ints
	w.destroy(...)				none
	w.get(...)				float
	w.identify(...)				string or none
	w.menu(...)				new menu rivetobj
	w.name()				a string, widget's resource id
	w.pack(...)				none
	w.parent(...)				rivetobj
	w.place(...)				none
	w.set(...)				none
	w.toplevel(...)				new toplevel rivetobj
    scrollbar methods
    	Usage:					Returns:

	w.activate(...)				none
	w.bind(...)				depends on arguments
	w.cget(...)				depends on arguments
	w.children(...)				tuple of rivetobjs
	w.configure(...)			depends on arguments
	w.delta(...)				float
	w.destroy(...)				none
	w.fraction(...)				float
	w.get(...)				tuple of float
	w.identify(...)				string or none
	w.menu(...)				new menu rivetobj
	w.name()				a string, widget's resource id
	w.pack(...)				none
	w.parent(...)				rivetobj
	w.place(...)				none
	w.set(...)				none
	w.toplevel(...)				new toplevel rivetobj
    Note that the scrollbar set method supports only the tk version 4 style programming interface. This method takes two float arguments both between 0 and 1, describing the beginning and ending ranges.

    text methods

    	Usage:					Returns:

	w.bbox(...)				tuple of ints
	w.bind(...)				depends on arguments
	w.button(...)				new button rivetobj
	w.canvas(...)				new canvas rivetobj
	w.cget(...)				depends on arguments
	w.checkbutton(...)			new checkbutton rivetobj
	w.children(...)				tuple of rivetobjs
	w.compare(...)				int
	w.configure(...)			depends on arguments
	w.debug(...)				string
	w.delete(...)				none
	w.destroy(...)				none
	w.dlineinfo(...)			tuple of integers
	w.entry(...)				new entry rivetobj
	w.frame(...)				new frame rivetobj
	w.get(...)				string
	w.index(...)				string
	w.insert(...)				none
	w.label(...)				new label rivetobj
	w.listbox(...)				new listbox rivetobj
	w.mark_gravity(...)			string
	w.mark_names(...)			string
	w.mark_set(...)				none
	w.mark_unset(...)			none
	w.menu(...)				new menu rivetobj
	w.menubutton(...)			new menubutton rivetobj
	w.message(...)				new message rivetobj
	w.name()				a string, widget's resource id
	w.pack(...)				none
	w.parent(...)				rivetobj
	w.place(...)				none
	w.radiobutton(...)			new radiobutton rivetobj
	w.scale(...)				new scale rivetobj
	w.scan_dragto(...)			none
	w.scan_mark(...)			none
	w.scrollbar(...)			new scrollbar rivetobj
	w.search(...)				string
	w.see(...)				none
	w.tag_add(...)				none
	w.tag_bind(...)				depends on arguments
	w.tag_cget(...)				depends on arguments
	w.tag_configure(...)			depends on arguments
	w.tag_delete(...)			none
	w.tag_lower(...)			none
	w.tag_names(...)			tuple of strings
	w.tag_nextrange(...)			tuple of strings
	w.tag_raise(...)			none
	w.tag_ranges(...)			tuple of strings
	w.tag_remove(...)			none
	w.text(...)				new text rivetobj
	w.toplevel(...)				new toplevel rivetobj
	w.window_cget(...)			depends on arguments
	w.window_configure(...)			depends on arguments
	w.window_create(...)			none
	w.window_names(...)			tuple of rivetobjs
	w.xview(...)				tuple of two floats or ()
	w.yview(...)				tuple of two floats or ()
    toplevel methods
    	Usage:					Returns:

	w.bind(...)				depends on arguments
	w.button(...)				new button rivetobj
	w.canvas(...)				new canvas rivetobj
	w.cget(...)				depends on arguments
	w.checkbutton(...)			new checkbutton rivetobj
	w.children(...)				tuple of rivetobjs
	w.configure(...)			depends on arguments
	w.destroy(...)				none
	w.entry(...)				new entry rivetobj
	w.frame(...)				new frame rivetobj
	w.label(...)				new label rivetobj
	w.listbox(...)				new listbox rivetobj
	w.menu(...)				new menu rivetobj
	w.menubutton(...)			new menubutton rivetobj
	w.message(...)				new message rivetobj
	w.name()				a string, widget's resource id
	w.parent(...)				rivetobj
	w.radiobutton(...)			new radiobutton rivetobj
	w.scale(...)				new scale rivetobj
	w.scrollbar(...)			new scrollbar rivetobj
	w.text(...)				new text rivetobj
	w.toplevel(...)				new toplevel rivetobj
    The Rivet Table Widget

    Rivet contains a table widget suitable for positioning other widgets in a non overlapping row and column style. The table supports:

    The table widget does not directly support automatic rearrangement in response to item geometry changes. To accomplish rearrangement, you must invoke the table's arrange method from event binding callbacks (e.g. using rivet.bind) on the items that might change size. For performance considerations, it might also be advisable to schedule arrange to be called from a rivet.after callback.

    The table widget is implemented in the file rivettable.py. There is an example at the end of that file which gives a working example of most of its functionality. To run this demo, just type python rivettable.py.

    The Rivet Outline List Widget

    Rivet also contains an outline list widget. This widget is a work in progress, but may be useful for some projects. The source for this widget is in the outlinelist directory. To run the self included demo, type python rivetlist.py.

    Miscellaneous

    Utility Functions
    The file rivetutil.py contains these routines:

    associate_scrollbar(client, scrollbar)

    This is a convenience function to configure a client (usually a canvas, entry, listbox, or text) and a scrollbar so that they operate together.
    option_menu(parent, variable, ...)
    This is the equivalent to Tk's tk_optionMenu routine. The second parameter should an instance of rivetutil.stringvar or one of its subclasses, it may be None, in which case a variable will be automatically generated for you. The remaining parameters are strings that should be used to label the menu entries. This function returns a menubutton widget that must be packed.
    rivetutil.py also contains the definitions for stringvar, intvar, and floatvar classes. An example of using these can be found in varexample.py.

    Threads

    Rivet is thread aware, but not thread safe. Rivet relinquishes control of python's global lock before it is about to block, allowing other python threads to run. Calling Rivet functions from multiple thread is unwise. If you did not enable threads when compiling Python, this should not be of concern to you.
    Author: Brian Warkentine
    Email: brianw@veritas.com