Monday, February 15, 2010

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.

12 comments:

  1. This is great news, I'll think about making a Wiki page on the french Ubuntu wiki just like I did with Quickly.

    ReplyDelete
  2. Thanks for helping me to understand basic concepts.Your post will be helpful for everyone
    Mulesoft Online Training
    Mulesoft Training in Hyderabad

    ReplyDelete
  3. very interesting, good job and thanks for sharing such a good blog. Seo Services Delhi

    ReplyDelete
  4. I read this post your post so nice and very informative post thanks for sharing this post. Youtube Mp3 Converter

    ReplyDelete
  5. Receive the No.1 Selenium Training in Chennai from Infycle Technologies, for techies, freshers, and students at the best offers. In addition to the Selenium, other in-demand courses such as Java, Power BI, Digital Marketing, Python, Big Data, Web Development & Design, Oracle, Cyber Security also will be trained with hands-on practical classes. Get a free demo and more info by calling 7504633633.

    ReplyDelete
  6. more information about IT world you can find on Mobilunity for details

    ReplyDelete
  7. Fortunately, 2019 accompanied the arrival of independent VR frameworks. The year was supposed to be over and above anyone's expectations for augmented reality development as customers are liberated from wires, laptops, and telephones. What's more, it figured out how to satisfy hopes. As independent VR frameworks offer expanded convenience, solace, and movability, it appears to be computer generated reality is going towards the standard achievement its been pursuing. Interest and development are supposed to keep on rising. It is anticipated that computer generated experience will be a $38 billion industry by 2026.

    With respect to the year 2020, the VR/AR industry has reached $18.8 billion internationally. The nations that put more in VR programming advancement are the USA and China. Augmented reality advancement cost and ubiquity accompany its possibilities in medical services, military, and science>> Mobilunity

    ReplyDelete
  8. Data engineers are named, and most importantly, highly specialized specialists, and at an interview you can ask a huge number of questions that you need to be prepared for - by clicking on the website link you will get access to a collection of basic interview questions, so you can prepare and increase your chances for success.

    ReplyDelete
  9. This comment has been removed by the author.

    ReplyDelete