CS349 A03: Custom Widgets

Due: 26-Feb-2012 10:00pm

Updates

Feb 16:

Modified the Assessment section to come closer to the goal of mark breakdowns that are no larger than 20% per section. Under Submission, added an optional opt-out file. Added a section indicating that clarifications are to happen via Piazza. Changes are bordered in red.

Feb 13:

A reference to a tutorial was posted on Piazza that essentially does the TreeView and DirView. I'm not happy about it; I think your educational goals would have been better served by figuring this out based less-specific examples so that you had some material left to reason out on your own. Nevertheless, you are free to use this tutorial.

You are strongly encouraged to first study the code and then to rewrite it on your own from scratch as the best approach to learning.

The outline of the marking scheme has been changed to place less weight on the parts covered by the tutorial and more on the TimeView. Given the increased emphasis on TimeView, you are strongly encouraged to test your design ideas (before implementation) with someone not familiar with the course to get their feedback.

Introduction

The standard file explorer in most operating systems shows a tree-like directory (folder) structure. Each directory is a container for files and other directories. Unfortunately, many users do a poor job of sorting their files into directories. Whether a lack of motivation, a lack of knowledge, or some other factor results in poor file organization, the fact remains that, for many users, it happens.

One dimension that is usually poorly supported in default file explorers on many operating systems is time. It is surprising that time has been so poorly explored because so many of the pieces of information we generate are related by temporal proximity. Consider, for example, web pages browsed while creating a lecture. Consider the APIs one looks at when completing an assignment. The temporal proximity of these various data indicates a relationship that can be explored in only limited ways in default file explorers.

Your task for this assignment is to create a custom file viewer for the files on a user's disk. The default file explorer with a tree-view on the left and a file view for the current directory on the right should be augmented with a tabbed container on the right, maintaining the tree view on the left. The tabbed container will have one tab for a customary file view and another tab with a custom widget for a timeline view.

Learning Goals

• To learn how to implement a custom widget.
• To be creative in designing a functional and easy-to-use user interface.
• To correctly use the Swing toolkit to implement a Model-View-Controller architecture for the project.

Requirements

The following figure is a basic example layout for your file browser. (Click to enlarge.)

Figure 1a	Figure 1b

The interface is composed of three custom widgets:

• The TreeView widget is on the left and shows a standard tree view of the file system -- much like the leftmost pane in Windows Explorer. It may contain both files and directories or directories only.
• The DirView widget is in one tab on the right side as shown in Figure 1a. It shows the contents of the currently selected directory in a table with one row for each element in the directory and columns for the name, size, and modification date. If a file is selected in the TreeView, the DirView shows a list containing exactly that file. This widget is much like the right pane in Windows Explorer.
• The TimeView widget is shown in another tab on the right. The Timeline, on the bottom, is used to control which files are shown in the data area above it. The two areas, together, make up the TimeView widget. See Figure 1b for an illustration of these two areas. The user can choose whether to use TimeView or DirView to view the currently selected directory.

All three widgets will be self-contained, extending either JComponent or JPanel. They will all make use of a BrowserModel, much like JTable makes use of TableModel. Programmers familiar with the Swing library should feel at home using your custom widgets. For example, names for adding and removing listeners should feel familiar; interfaces should be defined for listeners; listener methods should make use of an event object; etc. You may want to consult the slides from the Abstract Models lecture.

Selecting a file or directory in one of the views should cause the other views select the same file or directory.

TimeView

The basic requirements for the TimeView widget you create:

• The widget will have some sort of time line that allows the user to (for example) jump to a given time or broaden/narrow the range of times shown. Other interactions are certainly possible and are encouraged.
• The user interface should represent temporal clusters of files in some manner. In a basic implementation it could show a histogram of the number of files in various "bins" representing a unit of time.
• Selecting a specific file or directory will cause its name to be clearly displayed (if it isn't already) and, in the case of a file, show it's size and modification date.
• Users should be able to choose between two modes:
  • display the files in the currently selected directory
  • display the files in the currently selected directory and all of its subdirectories (recursively).
• You should be able to filter the displayed files by file type.

Pay special attention to the data region. In this region, you have a chance for some creativity. How will data be displayed? How can users interact with the data items? How does that interaction affect the timeline below the data area? These two areas of the widget are obviously linked. You might implement them as separate (internal) views that both interact with and listen to the file system model.

Restrictions

In light of the results of A02, the following restrictions apply:

• Once a component is added to a view, it may not be removed. This implies that removeAll and related methods may not be used.
• The use of invalidate, revalidate, updateUI and related methods is strictly prohibited.
• Calling repaint is allowed in TimeView but not in TreeView or DirView.
• The three views may not interact with each other except via their independent responses to the model.

Tips

1. Make three packages, model, view, and app.

2. The model is a combination of the actual file system and the currently selected file. On the other hand, you will almost certainly want to use JTree and JTable widgets in your user interface and thus need a TreeModel and a TableModel.

   There are several ways to fit this together. I recommend one of:

   • A single BrowserModel class that implements both the TreeModel and TableModel interfaces.
   • A BrowserModel class together with a adapter class that implements TreeModel. The adapter class takes the BrowserModel as a parameter and implements the TreeModel classes in terms of it. Similarly for a TableModel adapter.

   Of the two, I'd recommend the second approach.

3. Root the file system at the user's home directory. You can get that with

   this.root = new File(System.getProperty("user.home"));

4. Remember that the model classes should not reference the views in any way except via listeners. Suggestions:
   • Use a PropertyChangeListener in the BrowserModel class. Fire it whenever the selected file/directory changes.
   • You'll need to also handle listeners for your table and tree models. They will likely change whenever the PropertyChangeListener is fired.
5. Classes you may find useful: File, PropertyChange{Listener, Event}, ArrayList, Collections, Date, List, LinkedList, TableModel, TreePath, TreeModel, SimpleDateFormat, TableModel{Listener, Event}, TreeModel{Listener, Event}, TreeSelection{Listener, Event}, DefaultTreeCellRenderer, ListSelection{Listener, Event}, JPanel, JComponent, JTabbedPane, JSplitPane, JScrollPane.
6. When you fire a PropertyChange event you need to give the old value and the new value. For the benefit of TreeView, it's cool to give an array of File objects that make the path to the selected file/directory. When making this list, consider using the getParentFile() method in File. But you can't compare File objects directly to tell when you get to the root. Compare paths (strings) instead.
7. The views will need to register some listeners to change the model. For example, the TreeView should have a TreeSelectionListener registered that tells the model when a new file/directory has been selected.
8. Tables and trees can have one or many things selected. For this application you should set each to just allow a single selection.
9. To get selections from a JTable, you need to use it's getSelectionModel() method to get the (surprise!) SelectionModel. It can (and will) fire valueChanged many times in what seems (to us) to be a single selection. Read up on getValueIsAdjusting in the event and only pass the event on to the BrowserModel if getValueIsAdjusting is false and the first index is non-negative.
10. Refer to the sample code from class for ideas on how to implement the TimeView.

Assessment

Submission will be assessed roughly as follows:

By "effectiveness" we mean:

• The user can accomplish their (reasonable) goals.
• The interaction is intuitive. It seems evident that the design was tested with someone not in CS349. An "Evaluation" section in the README.txt describing the user testing and what you learned can help boost your mark here.

Submission

Submit the following:

• Your Java source files. Any additional files required to build the program.
• A Makefile with two targets: build and run that do the obvious things.
• A README.txt file that explains what the marker should look for. Describing scenarios that walk the marker through using your user interface is one way to do this. You may also want to describe any user testing you performed.
• Your program should be testable on any machine running Java version 6 or later. Your program will be tested on the undergrad environment unless you include an empty file named Test.VM.
• Your program may be selected for in-class critique unless an empty file named your_userid/a03/No_Critique.txt is present.

Submission will be via your personal svn repository.

¹I shouldn't have to say this, but... Only programs that satisfy a reasonable number of the other requirements are eligible for these marks.