2010-02-13

TKWeek 1.1.4: Widget für den Home screen

Ich freue mich, die Version 1.1.4 von TKWeek ankündigen zu können. Sie ist ab sofort im Android Market verfügbar. Neu ist ein Widget für den Home Screen, das das nächste Ereignis aus der von TKWeek verwalteten Liste von Ereignissen und Feiertagen anzeigt. Neben benutzerdefinierten Ereignissen kennt TKWeek zahlreiche Feiertage, zum Beispiel Valentinstag, Ostern, Pfingsten, Advent, Thanksgiving, usw.

How to use CommandMenu

Please note: This article was previously posted on my weblog Tommis Swing Musings. I started that blog with high hopes, but due to a lack of time I decided to cancel Tommis Swing Musings. I have deleted that blog.

In my previous post I introduced you to a component called CommandMenu. Since the class itself is rather small, one might expect that using it could mean having to write lots of code. As you shall see shortly, this is not the case.

First, we need some instance variables:

// the content pane
private final JPanel contentPane;

// the command area
private final CommandMenu commandMenu;

// the module area
private final JScrollPane moduleScrollPane;
Java2html

Here is how to set them up:

// the module area
moduleScrollPane = new JScrollPane();
moduleScrollPane.setBorder(BorderFactory.createEmptyBorder());
// the command area
commandMenu = new CommandMenu();
createAndAddModule(DaysBetweenDates.class);
createAndAddModule(Settings.class);
createAndAddModule(About.class);
// the content pane
contentPane = new JPanel(new BorderLayout(20, 0));
contentPane.setBorder(BorderFactory.createEmptyBorder(10, 10, 10, 10));
contentPane.add(commandMenu, BorderLayout.WEST);
contentPane.add(moduleScrollPane, BorderLayout.CENTER);
Java2html

So, the basic thing is to create some sort of content pane (contentPane) which holds the command menu (commandMenu) and the pane that shall be shown when a command menu item is selected. This pane is wrapped in a scrollpane (moduleScrollPane).

The example above invokes a method called createAndAddModule() three times. Here is how the method looks like:

private void createAndAddModule(Class<? extends JComponent> panelClass) {
  try {
    String className = panelClass.getSimpleName();
    String title = TKWeek.get(className + ".title");
    final JComponent module = (JComponent) panelClass.newInstance();
    module.setName(title);
    commandMenu.addCommand(new AbstractAction(title) {

      @Override
      public void actionPerformed(ActionEvent e) {
        moduleScrollPane.setViewportView(module);
      }
    });
  } catch (Throwable thr) {
    Logger.getLogger(TKWeekMainFrame.class.getName()).log(Level.SEVERE, null, thr);
  }
}
Java2html

To add a command menu item to the CommandMenu, its addCommand() method is called. It is passed an Action, which is used to determine the displayed text. Additionally, its actionPerformed() method is invoked when a command menu item is clicked. As you can see it just sets the viewport view of a scrollpane. Have you noticed that the component need not be referenced anywhere outside this method?

As you can see, there is not much code needed to populate a command menu. What do you think? I am looking forward to hearing from you.

On multi-page views

Please note: This article was previously posted on my weblog Tommis Swing Musings. I started that blog with high hopes, but due to a lack of time I decided to cancel Tommis Swing Musings. I have deleted that blog.

A dialog with tabs

It has been common practice to implement multi-page views using tabs, as shown in the screenshot on the left hand side.

While the tab methaphor works well for few panels, it may be difficult to find the right one, if there are so many of them  that the tabs have to be arranged in more than one row. For this reason the Windows User Experience Interaction Guidelines suggest to layout the tabs vertically if there are more than seven tabs. Here are some implementations of the “vertical tabs” metaphor:

Microsoft Security Essentials
Microsoft Security Essentials

Visual C++ 2008 Express Edition 
Visual C++ 2008 Express Edition

Microsoft Word 2007
Microsoft Word 2007

So far we have seen multi-page views in modal dialog boxes. Did you notice that at least two implementations (Visual C++ and Microsoft Security Essentials) seem to resemble a list rather than vertical tabs?

Now let us take a look at non-modal multi-page views.

Control panel in Windows Vista
Control panel in Windows Vista

The control panel in Windows Vista and Windows 7 consists of hierarchically organized pages. As you can see in the screenshot above, a navigation panel on the left hand side of the window displays sub-pages, just like clicking on the name of a tab.

the current page the current page is highlighted by printing its name in bold letters and showing a small bullet in front of it. The following screenshot shows how the names of pages not currently on display look like:

Names of pages not on display
Names of pages not on display

The control panel in Windows 7 works the same, but uses slightly more subtle colours:
The Windows 7 control panel
The Windows 7 control panel

While the page layout hardly resembles the tab metaphor, the underlying concepts are similar. The main area of the view is reserved for the content. A list of links or button-like controls switches between subpages, which are displayed in the main area.

How could multi-page views be implemented in Swing?

I am going to answer that question in a few seconds. But first, please take a look at, well, yet another screenshot:

TKWeek with the Windows Look and Feel
TKWeek with the Windows Look and Feel

TKWeek is an application I have written for the Android Platform. It is a small date and calendar tool you can use to compute the number of days between dates or the week number of some date. A few days ago I thought it might be fun porting it to Swing. Android UIs are based upon the concept of so-called Activities, which represent “screens”. Programs usually consist of several Activities. For example, TKWeek has a screen where the users decides what to do. Subsequent Activities perform the requested computation. When the user has finished using an Activity he/she returns the the main menu.

On the desktop, there is no need to hide the menu. It is always visible, which allows the user to quickly jump to different functions or modules. The left-hand side of the above screenshot shows what I call a command menu. Each of its elements represents a page which is displayed when the corresponding menu item is clicked. The command menu resembles non-modal multi-page views in Windows:

image

The active page is highlighted by printing its name in bold letters and showing a small bullet in front of it. Pages not on display are written in plain letters. A subtle rollover effect shows the menu item under the mouse pointer.

TKWeek with the Nimbus Look and Feel
TKWeek with the Nimbus Look and Feel

CommandMenu is part of TKSwingComponents, a small component library which I have released under the terms of the GNU Lesser General Public Licence. It is just a JList wrapped inside a JScrollPane and a small ListCellRenderer implementation. As you can see here, the source file consists of only 254 lines of code including comments.

In the next weblog entry, I will show you how to use this component. If you have questions or comments, please leave a comment.