Workbench layout

The Fable user interface is in the form of a workbench. It is laid out with a main menu, a main toolbar, and a collection of editors, views, and controls.

Workbench Layout

Perspectives

There can be many layouts, in fact, and they are called perspectives. A perspective is a particular arrangements of the views, editors, and controls. The perspective shown in the example above is the PeakSearch Perspective, as can be seen by the fact that it is highlighted in the set of perspectives. This perspective consists of three views (PeakSearch Options, Image Navigator, and Console) in two different groups. There are two editors, both named peaks_50.flt. (Editors are typically named with the name of the file they are editing.) The two editors do different kinds of editing on the same or different files.

In general, perspectives are the way you will organize your Fable workbench. They are very customizable. For example, you can drag the views around and dock them pretty much wherever you like, even making new groups. To do this just drag the tab. Editors are a little different. There is one area of the layout that is called the editor area. It is outlined in red in the example. All editors stay in this area. Since Fable uses editors that are not just simple text editors, but rather editors which have controls in them, it is often difficult to tell a view from an editor. If you have trouble moving a view, it may be because you are trying to move it into the editor area. Similarly, if you can't move a tab, then it may be an editor. With experience you will learn which are views and which are editors. In addition to moving things around, you have much more complete control over the perspectives via the Window menu. There are several items there, such as Customize Perspective, Save Perspective As, and Reset Perspective in that menu. Feel free to experiment. Fable remembers the last way you left your perspective the next time it opens.

There are several ways you can change the perspective. You can click on one of the perspectives in the set of perspectives. You can often get to a perspective via one of the menus. For example, you can open the ImageViewer perspective from the ImageViewer menu at the top. You can get to any of the available perspectives by selecting Window -> Open Perspective in the top menus. Some operations, such as opening a particular type of file, will switch you to the appropriate perspective automatically.

Editor and Views

There are several differences between views and editors besides the fact they can only be in their own parts of the workbench. Editors typically contribute items, such as Save and Save As to the main File Menu and items such as Copy and Paste to the main Edit menu. Views cannot do this. Views have their own local toolbars and menus as shown in the example. Editors do not. Views can be moved nearly anywhere except into the editor area. Editors cannot be moved out of the editor area, but you can drag them around the editor area, making them be side by side, for example. For either an editor or view, you can double click its tab, and it will expand to fit the available space. Most views can be detached from the workbench via the right-click menu on the tab. Editors cannot. Some views have been constrained to not allow this as well.

You can dismiss views or editors you do not want by clicking the X that appears on the tab. If there is no X, then the developers do not want you to have this freedom. You can also access other options by using the right-click menu on the tabs. If the view you want is not visible, you can make it visible via Window -> Show View.

Editors and views are known as workbench parts. There is always an active part. That is the one with the highlighted tab, as shown in the example. For editors what appears in things like the File menu depends on which editor is active. The last used editor remains active if a view is the current active part.

Console

Note the Fable console in the example above. Many of the Fable applications use this for output. If it is not visible, you can make it visible using Window -> Show View -> Other -> General.

Preferences

You can set your own preferences for many settings in Fable. You do this via Window -> Preferences. It is worthwhile to explore the options available there and become familiar with them. It can make your life much more pleasant.

It is good to set the following preferences at the beginning if they are not set by default:

Window | Preferences | General | Workspace: Check “Automatically”.
Window | Preferences | Configuration: Check “Large screen” (unless you have a very small screen).

Help

Fable has an extensive help package. (It should get even larger as the developers have more time left over from fixing bugs and adding features.) If things aren't clear to you, try the help first. It is found, not too surprisingly, under the main Help menu.

Python

Fable is Java graphical user interface (GUI) which uses a number of Python scientific routines under the hood. You will not be able to do much until your Python is set up correctly. Be sure to read the Python section of the Fable help. There are two items in the workbench, in particular, that may be of help in getting Python set up. Under Tools -> Python -> Python Information, you will find a dialog that tells you about environment variables, such as the PATH and PYTHONPATH, and also tells you if Fable is able to load required Python modules or not. It needs to be able to load most of these there in order to work. Loading Tk is probably not required for Fable but is required if you run ImageD11 alone. Secondly, you can set your PYTHONPATH under Window -> Preferences -> Python. If you are having trouble, you can perhaps play with these two until you get it to work. This will only help you find the required Python modules. Installing them in the first place is a more difficult task. See the Python part of the Fable help for more information.

Workspace location

By default your Fable workspace will be located in a directory named, excitingly enough, workspace, which is in the directory where the Fable executable is located. Many things are stored there including everything Fable remembers about your preferences and how you left things when you exited. You can choose to have your workspace located somewhere else. In fact, if you do not have access permission to the directory where Fable is located, you will have to have it someplace else. Even if permissions are not a problem, it is almost always better to to have your workspace located somewhere else for several reasons, the most important being that your settings will be remembered even if the Fable directory is replaced with a new version.

In Windows you can make a shortcut to your fable.exe and change the target to something like:

C:\Fable\fable.exe -data c:\MyWorkSpaceLocation

This makes it use c:\MyWorkSpaceLocation for the workspace.  If you also change the starting directory to c:\MyWorkSpaceLocation, then the log will be there also.

This is an example where the executable is in c:\Fable and your workspace is in c:\eclipseWorkspaces\FableWork:

Windows Shortcut Properties

On UNIX you can make a script to run Fable with a "cd myWorkspaceLocation" and using "-data c:\MyWorkSpaceLocation" as above. This leaves the executable fable, fable.ini, and everything in inaccessible directories and lets you have full control and access in your own space.  You can even have lots of workspaces if you want. You can also specify your PATH, PYTHONPATH, LD_PRELOAD (if required), and other things in the script. If the script is in your PATH, you are all set to run it from anywhere.

This is an example:

#!/bin/csh -f
# Script to run Fable
set WORK=~/src/FableWork
set EXEC=~/linux/Fable/fable
set VARGS="-vmargs -Xmx512M -Xms128M -XX:MaxPermSize=128m"
cd $WORK
set JAVA_HOME=/usr/java/latest
setenv LD_PRELOAD ~/linux/lib/libpython2.5.so.1.0
setenv PYTHONPATH ~/linux/Fable/FablePython/latest/linux_x86
setenv SPDVERSION new
$EXEC -data $WORK $VARGS &
In this example the executable is ~/linux/Fable/fable and the workspace is ~/src/FableWork. The script also sets some environment variables and specifies some additional arguments to Java via the -vmargs option to the Fable command line.

Cleaning up your workspace

If you think your workbench is brain dead and trashed beyond repair, you can always try cleaning it up. This may be necessary when installing a new version of Fable, for example. The most moderate way to do this is to start Fable with the -clean option. (Remember to remove it the next time you start.) The most drastic way to do it is to delete the .metadata directory. (You might just want to rename it until you are sure.)

Projects and the Navigator

Starting with Fable 2 the most convenient way to use Fable is to make a Fable project of the files you are analyzing. This is most easily done if the files are under one top-level directory, for example, SimulationAl20081209 in the figure below.

Workspace with Navigator

[Full Size Image]

Navigator

The Navigator view on the left shows your projects and the files in them as a tree. You can open many of the files in the appropriate editor merely by double clicking them. There are more options available by right clicking. The Navigator acts as a file system viewer, so that you can copy, paste, delete, and move files much the same as you can in external file system viewers, such as Windows Explorer. You should be able to edit, run, and manage most of the files in your project entirely in Fable, which is the real purpose of the workbench concept.

In particular, if a file has an editor associated with it, for example, the .ini files above, then you can open it in that editor by double clicking it. If you right click a file and select "Open With", you can choose to edit the file with other editors. The Text Editor is usually an option and may be appropriate for files that are not associated with editors. Fable remembers your last choice, and double-clicking will open the file with that editor. When you right click on a file or a folder, there will also be an option "Open With (Other)". This option can be used to open certain files that may not have editors associated with them. These include .spt, .flt, PeakSearch .xml files, .par files, and images. Some of these (e.g. .flt and images) will work with multiple selections, and "Open ImageViewer File" will also work with folders. This menu performs actions that are available on other menus, but with the convenience of staying in your project and without having to find the file through a file selection dialog.

This is what the right-click menu, also known as the context menu, may look like:

Open With (Other) Menu

Projects

To make a project, right click in the Navigator and select New -> Project -> General -> Project and click Next. Give the project a name, uncheck the "Use default location", and browse for the location of your directory. When you click Finish, a .project file will be created in your directory and the files will appear in the Navigator. If you don't see the Navigator in the GrainSpotter perspective, the select Window -> Reset Perspective. If you are in another perspective, then you can use Window -> Show View -> Other -> General -> Navigator. You can import existing projects by right clicking in the Navigator and selecting Import... .

New Project Dialog

Note that the projects in the Navigator appear as though their root is your workspace. The actual files may be anywhere in the file system though. You can right click a file or folder and select "Properties". This will show you the "Path" which is the location relative to your workspace and as shown in the Navigator and also the "Location" which is the actual location in the file system. You can think of the Navigator view as a mapping from the file system to the Fable internal representation. You can thus leave your files wherever they are created in the file system, yet still be able to manipulate them as a project.

It is suggested you organize your files as in the pictures above; that is, with the images in one folder and your analysis in one or more other folders, such as GrainSpotter, ImageD11, and PolyXSym above, all of these under a common folder denoting the experiment or study. However, you are free to organize them in any way that is appealing to you. Keeping them all under one common folder, however, makes it easier to access them in the Navigator.

Logging

Fable logs events in two different ways. It uses Apache Log4j to log events both into fable.log, which is located where your workspace is if you set up as above, and also into the console from which you are running Fable. On Windows, you typically do not run Fable from a console, so you will have to look at the log. Other types of messages, mostly unexpected ones, are logged into a file called .log under the .metadata directory where your workspace is. You can set the logging level under Window -> Preferences -> Tools -> Logger. It is set at Info by default. There are actually two loggers that both write to the same places. The main logger is expected be logging at all times. The root logger is mostly used by developers for specific debugging.

Utilities

Fable comes with some utilities that do not fit under other categories, and it may have more as time passes. Jmol is available and there is a Memory Usage. You can find these via Window -> Show View -> Tools.