Chandler User Interface: the Inside Story

Four Key Concepts: Widgets, Blocks, Collections and BlockEvents

To understand how the user interface works inside Chandler you need to first learn a little bit about 4 key concepts: Widgets, Blocks, Collections and BlockEvents.

A Widget is a wxPython user interface object.

Blocks, Collections and BlockEvents are persistent Python objects stored in the Chandler Repository. Persistent objects are like other objects, except they exist after you quit and restart Chandler -- so you don't need to write any code to serialize and unserialize them when starting or quitting Chandler -- and you can assume they always exist.

To illustrate how these four kinds of objects fit together, let's start with a simple example: the summary table in Chandler 0.6.

The Widget is a wxTable object -- a subclass of wxGrid. According to the wxWidgets documentation, "wxGrid and its related classes are used for displaying and editing tabular data. They provide a rich set of features for display, editing, and interacting with a variety of data sources." If you are familiar with desktop user interface class libraries, wxGrid will be familiar.

The Block contains data that describes the table, including information about the column headings, which attributes are displayed in which columns, the width of the columns, various style information and the data displayed in the table.

In the Model View Controller (MVC) paradigm, the Widget is the View and the Block is the Model.

Keep in mind that we're only talking about Model and View of the User Interface, not to be confused with Chandler's domain or content model, which we'll talk about shortly.

When the Widget changes an aspect of the table, for example the width of the column, it stores the new value in the Block. Since the Block is persistent, when you quit and restart Chandler the column width retains its last value.

Blocks have an optional attribute (or instance variable) called "contents" that contains the data that the block's widget displays. It is the Chandler's domain Model. For the Table Block, used in the summary table, its contents is a Collection of User Items.

User Items are persistent Python objects stored in the Repository just like Blocks, Collections and BlockEvents. Examples of User Items are events, e-mail, notes and tasks.

A Collection is a list of Items. An example of a Collection is the list of all e-mail items in the repository -- or to be more precise all the e-mail items minus the items in the Trash Collection. Collections are always kept up-to-date, so when new e-mail arrives it is automatically added to the Collection of e-mail, or when items are added to the Trash Collection, the collection of e-mail minus Trash automatically removes the trashed item.

When a Collection changes, its Block is notified so that its Widget can reflect the change.

A BlockEvent is an event object. When the user selects an item in the summary table, the Widget's "OnRangeSelect" handler is called which broadcasts a "SelectItems" BlockEvent. The Block that displays the detail view responds to the SelectItems event and updates the detail view.

Most high-level user actions in Chandler, e.g. Cut, Copy Paste, generate BlockEvents, which are dispatched to Blocks which update their model and delegate changes to the Widget.

Chandler doesn't have a distinct controller object. For the user interface, the Widget often implements controller functionality. Methods on Block handle BlockEvents, which one could argue is domain controller functionality.

So, that's it -- the rest of the Chandler's user interface is a variation of this example, except for different Widgets, Blocks, Collections and BlockEvents.

Links

• An Introduction to Blocks
• BlockEvents
• Collections