Quickly.Widgets API Design and Documentation

As I've been working of Photobomb and Bughugger, I've been using Quidgets, and extending or tweaking as I needed to do different stuff for the programs.

One thing is, Quidgets need a better name. "Quidgets" was a sort of as a joke. "Quidgets" does have teh advantage of being silly, and maybe keeps folks from taking it too seriously. It's good the name that expresses that. But maybe it's time to boost the configence of the project. So didrocks repackage quidgets as "quickly-widgets", now the namespace is quickly.widgets, quickly.prompts, etc... We'll see how it goes.

Any hoo...

Use
The start of quickly.widgets was focused on one-liners, making it take no more than a line or two to use a quickly.widget. It's good to try to make it easy and fun to write programs. So for instance, with DictionaryGrid, all you need is a dictionary and one line to create the DictionaryGrid, and you are displaying tabular information to users:

 #create a dictionary if you don't already have one
dicts = [{"test?":True,"price":100,"foo count":100,"Key4":"1004"},
{"test?":True,"price":100,"foo count":100,"Key4":"1004"},
{"test?":True,"price":100,"foo count":100,"Key4":"1004"}]
#create the DictionaryGrid
dg = DictionaryGrid(dictionaries=dicts)

It's consuming a quickly-widget, simply by "using" it. A quickly-widget when the underlying PyGtk library is just barely exposed, if at all, and covers up to about 80% of the use cases. In other words, you shouldn't always need to change anything to make it work for your program.

Configure
However, sometimes you have to tweak a quickly.widget for your needs. It's best when most of the essential functionality is provided, but perhaps you have to write a few more lines of code to configure the quickly.widget. This is the "configuring" level of consuming, You can write a few lines of code to set properties and call functions on a quickly.widget. It's a bit more work, but I the code should be easy to write as well. Somtimes the code for configuring a quickly.widget requires knowing or learning about a few parts of the underlying PyGtk library. Sometimes you have to learn about another quickly.widget. For instance, with DictionaryGrid you can configure the types of columns to use:

 #Define column types to use
hints = {"price": StringColumn}
dg = CouchGrid(dictionaries=dicts,keys=keys, type_hints = hints)

In some cases you confige using the underlying PyGtk library directly. For instance to configure a DictionaryGrid to use a different column label, you use the TreeView API like this:

 dg.get_column(0).set_title("Price")

I tried to make the GridFilter be a simple matter of configuring, so you can get special behiavior without the work deriving from a base class:

 blank_filter = BlankFilterCombo()
blank_filter.append("=",custom_equals_function )
blank_filter.append("<>",custom_no_equals_function )
filter_hints = {"status":blank_filter}
filt = GridFilter(grid, filter_hints)

Extend
For some applications there will be way way way too much code just configure an object, so you might end up extending a quickly.widget. For example, I was trying to add offline bug editing for Bughugger. The code was hard to modify starting after only about an hour into writing it because just configuing a DictionryGrid to save it's data in Desktopcouch required too much code strewn about the bughugger code file. So instead, I extended DictionaryGrid to be the new CouchGrid. Doing this required lots of knowledge of the DictionaryGrid widget, DesktopCouch, and PyGtk. However, my requirement was supported and the code is reusable.

I'm hoping to see in time an application library that is easy to use for task at hand, using, configuring, or extending.

Sadly, I have been totally lame about writing documentation for quickly widgets. So I have started doing proper pydoc documentation, adding a use, configure, and extend section to each module. For example, for couch_grid the module documentation now works in pydoc and includes an overview in addition to the reference for each function:

I've gotten dictionary_grid and grid_filter modules done so far, and in trunk.