Manipulating the SideBar from your ViewerParcel

In its simplest form, a ViewerParcel (What's a ViewerParcel?) just exists within the viewerParcel frame, but one of the things that many parcels may want to do is to manipulate the SideBar. Such actions might include:

• Adding child entries (for sub-views)
• Removing entries
• Changing what happens when a url is clicked
• Determining if a certain entry exists
• Getting the children of a specific entry
• Renaming entries
• Changing the color or bold state of entries
• Expanding or collapsing items in the tree
• Adding an icon to entries (currently not supported due to a limitation in wxWindows, but planned)

Structure

To understand how the SideBar works, first you have to understand where it gets its information. The SideBar is designed to support multiple Chandler windows, each with their own instance of SideBar. As a result, the SideBar is actually only a view onto the application’s URLTree, which stores the actual data describing Chandler's URL's. Therefore, whenever you want to modify a URL (add, remove, rename, etc.), you actually do so by modifying application.URLTree. Any changes to URLTree will be propagated to all instances of SideBar.

There are also certain operations which apply only to individual instances of SideBar (rather than application wide). These operations include expanding or collapsing a URL, or setting the color of a URL. These operations are performed by accessing the specific SideBar you are interested in.

By default, when you create a ViewerParcel, it is added to the URLTree for you. The displayName of the parcel is used as its entry in the SideBar.

Each entry in the URLTree has a ViewerParcel associated with it. When an item is clicked in the SideBar, GoToURL is called on the ViewerParcel associated with that entry. Your parcel model will inherit a GoToURL from ViewerParcel, but you can override GoToURL to add additional features.

URLTree

The instance application.Application.app.model contains a member variable URLTree that represents the current tree of URL's within Chandler. URLTree makes the following methods accessible to ViewerParcels. (See osaf/chandler/Chandler/application/URLTree.py for specifics about each method)

• URLExists(self, url)
  • Used to determine whether or not the supplied URL exists.
• GetURLChildren(self, url)
  • Returns a list of all the urls that are children of the supplied URL.
• AddURL(self, parcel, url)
  • Adds the supplied url to the URLTree. The supplied parcel will be associated with that url and will receive any future GoToURL calls generated by selecting that URL.
• RemoveURL(self, url)
  • Removes the supplied URL from URLTree.
• SetParcelAtURL(self, url, newParcel)
  • Changes which parcel will receive calls to GoToURL when this URL is clicked.

The following methods are still in flux and may be unified

• RenameURL(self, oldURL, newURL)
  • Renames oldURL to be newURL. This allows you to change the name of any one level of a URL at a time.
• MoveParcel(self, oldURL, newURL)
  • Moves the ViewerParcel contained at oldURL to newURL.

SideBar

Each wxChandlerWindow contains a member variable SideBar that represents that window’s SideBar. SideBar exports the following methods to ViewerParcels.

• SelectURL(self, url)
  • Selects the supplied URL within the SideBar.
• ExpandURL(self, url)
  • Expands the supplied URL.
• CollapseURL(self, url)
  • Collapses the supplied URL.
• SetURLColor(self, url, color)
  • Sets the color of the supplied URL.
• SetURLBold(self, url, isBold=true)
  • Sets whether or not the supplied URL should be bold.

To be done later

• Allowing parcels to add icons to the SideBar

-- JedBurgess - 13 May 2003