Chapter 5: The QEF Graphical User Interface

The GUI interface and related tools.

The QEF graphical user interface, qefgui, provides a point-and-click environment that makes it easy to navigate through projects and trees, invoke the various types of construction supported by the system and access its extensive on-line help facilities. The tool combines features from file system browsers, terminal window tools, and more conventional Integrated Development Environments.

qefgui also allows you to access tools such as your version-control software and basic file manipulation commands

Although the GUI makes it easier to learn to use QEF, you should still understand the underlying concepts that the system is based on. Without this understanding, you will find it difficult to use the GUI effectively.

One of the best reasons to use qefgui is its visual presentation of a project, showing the hierarchy of directories and configuration files, and providing instant access to the QEF components. From this environment, you can inspect configuration variables, edit configuration control files and source code, and create and build projects and workspaces with a couple of mouse clicks.

There are three major windows in qefgui:

The Navigator Window

The tree and project browser where you will spend most of your time.

The QEF Info Tool

The hypertext help system which provides access not only to QEF's help text but also to the standard man pages.

The Build Monitor

Monitors all commands detached within the qefgui, or using go, allowing you to view the logs of current and historical builds, re-run any logged build and bring any current build(s) to a graceful halt. Since you may want to run numerous concurrent builds for different platforms with varying options, the Build Monitor allows you to easily inspect and control all of the builds.

The initial display is shown in Figure 5.1. This window appears when the GUI is started. It allows you to quickly go to any tool in the GUI.

There are 9 choices:

1. Load Last Configuration, lets you resume working with the environment and set of projects and trees from the previous session. If you have not used qefgui before, this command button will be grayed out (unselectable).
2. Edit Working Tree Set: invokes the Tree Browser, allowing you to choose where you want to work from existing projects and trees.
3. Create New Project/Tree: allows you to create new trees (i.e., projects).
4. QEF Navigator: opens the Navigator window directly.
5. QEF Info Tool, opens a window to display the on-line hypertext help system.
6. QEF Build Monitor, opens a window to display the build logs and the results of any builds currently underway.
7. About QEF, displays the About dialog box which lists build date/time and version number of the program.
8. Help: opens the qef Info Tool to the Welcome item.
9. Quit: exits the qefgui program, closing any open associated windows. The exit dialog gives you the option to save your setup before exiting. Your current working tree set can be restored next time you run qefgui by selecting the Load Last Configuration button.

In the QEF system, working on a project is equivalent to establishing a working tree set. If you switch from one project to another, that simply means that you have substituted one working tree set for another. Each project tree you create is represented as a tree-record in the QEF directory server database.

When the Edit Working Set command is selected, the above window appears.

The tree set selection dialog is a graphical front end to the QEF directory server (qdsrv) database. All projects created by QEF are recorded in this database. The tree set selector allows you to inspect this database and select the trees that are of interest to you. Since the database may contain a very large number of projects records, this browser provides a set of drop-down filters to restrict what is displayed. The drop-down filters are described below. Using this dialog it becomes trivial to find out who is working on which project and where they are doing their work. (It should be noted that each record in the database frequently includes several directories. These directories combine to give you a single viewpathed tree.)

The tree set selector window is divided into two panes. The top pane lists the project records registered in the database, while the lower pane shows the records comprising the current working tree set. You can add records to or delete records from the current working set at will. To add a record or records, select them in the top pane and click on the Add button. To remove a record or records from the current working set select them in the lower pane and click on the Remove button. You can also double-click in either pane to add or remove a single record.

The drop-down filters appear across the top of the window. They allow you to restrict the project records displayed by any of the following:

By default, when the tree selection dialog is invoked, all of the trees in the database are displayed.

If you have invoked the Tree Browser directly from the Welcome Window, once you have created your working tree set the Welcome Window will be withdrawn and the Navigator window will appear.

The Navigator window is the primary interface to QEF facilities. This window allows you to navigate through the sets of trees that make up the projects on which you are working. It also provides easy access to the tools that allow you to query and edit various aspects of project configuration and launch constructions.

The Navigator browser has a number different tool boxes corresponding to the tabs displayed beneath the menu bar. As each tab is clicked, the corresponding tool box comes into view. You can click the appropriate tab at any time to display its command buttons.

Each of these tool boxes provides a set of related operations which are described briefly below. Each tab also has a help button containing a question mark. Clicking on this button will bring the on-line help entry for that item. Finally, each tool button has an associated tool tip, a short description of the buttons function that appears when the mouse cursor is moved over the button for a period of time.

No matter which tool box is displayed, the lower portion of the Navigator screen remains the same: a graphical outline of the current directory tree in the left pane, and the results from the last command issued in the output pane (to the right).

The directory tree pane of the Navigator window allows you to move around in the file system. Clicking the left mouse button on an icon in this pane will take you to that directory. It will also cause a viewpathed listing of the directories contents to be displayed in the output pane. Clicking the right mouse button in the directory tree pane displays a menu of options to speed up navigation. These items include a button to return you to your previous directory, direct-access buttons to all of the parallel (viewpathed) trees in the current tree set and items to let you bookmark particular directories that can then be directly accessed.

For the most part, the Navigator tool uses the object-action approach. The output pane in the Navigator usually provides the objects upon which you will act. You select some text (the object) in the output window and then click on a tool box button to invoke that action on the object. The Navigator is unusual in that you select sections of text within the window rather than always selecting complete objects. This is necessary because the complete set of object types that you may want to process is impossible to predict. Since you can select arbitrary sections of text, there are no constraints on the type of information that can be manipulated.

Just below the tool box area, there is a panel containing three text entries:

• The left-most entry displays the current tree's type.
• The middle entry displays the current directory.
• The right-most entry displays the current operand.

It is important to be aware of the last entry. In many case, you will want to perform a series of operations on the same file. For example, you may select a file, press the View File button to display it, then press the Check-Out File button to check out a writable version of the file, and finally launch the editor on this checkout file using the Edit File button. These buttons are available through the menu raised by the right menu button in the display area.

The final section of the navigator is the command line at the bottom of the window. This command line allows you to run any (non-interactive) shell command by typing it into the Cmd field at the bottom of the window. Interactive commands can be run using the Main Tab's Run button with the Xterm option. Commands are added to the Cmd Hist (Command History) list, from which they can be re-run by double-clicking them.

There are a number of special commands supported within the command entry:

cd

the navigator changes to the specified directory. If the argument is `', then it changes back to the previous directory.

edit

The editor, as specified by the user's preference (see Preferences in the Menu Bar descriptions), is invoked.

exit

The GUI exits.

go -d

The argument command is run and the Build Monitor is raised to examine the resulting output go file.

help

The QEF Info Tool window is opened, displaying the argument item or the previously displayed item if no argument is specified.

qd

The navigator changes the current directory to the one selected by the qd command -- see Using qd and Chapter 6.4: The Path Database, Qds, and Qd.

setenv

The environment variable named by the first argument is set to the second and subsequent arguments, or unset if there is not a second argument.

There are 6 sub menus in the menu bar at the top of the window. These are described below and documented in the on-line help.

Immediately below the menu bar are the tabs for eight tool boxes or tabs, one of which will be displayed. Figure 5.4 displays the Main Tab. Each tool box contains a number of command buttons which are described below. A tool box can be raised (i.e., made visible) by hitting its tab with the mouse button 1 or by selecting the tab using the left or right arrow keys and hitting the Enter key.

Note:

The tab and left and right arrow keys can be used to change the currently selected entry or button and the space key can be used to activate the currently selected item.

The Main tab includes the most commonly used operations:

This tab contains commands used in accessing information pertaining to your builds. This includes the build history of any individual target, generating a list of valid build targets, and obtaining library and include file use for particular files.

From this tab you can view and manipulate the configuration environment as specified by the qvrs files that are relevant to the current directory. qvrs is described in detail in Chapter 8.

The commands listed under this tab allow for the creation of new files and trees.

These commands allow basic file manipulation such as deletions and renames.

The Version Commands tab presents a series of command buttons corresponding to the major actions you can take with a version-control system. This is not intended to be a comprehensive interface to the version control system. It merely makes the common day-to-day operations immediately available. It is expected that more complex operations will be performed through the native interfaces provided by the version control system.

This tab presents miscellaneous commands, such as "tailing" or cleaning up the Install Log (see cleanilog), listing or creating Touch files (see touchfiles), and checking the validity of the qdsrv database entries (see qdchk).

This tab provides a place for users to add their own commands. Through the Preferences menu Add Command Button, you can add new command buttons to any tab. The user tab exists to collect commands that are inappropriate for the other tabs.

The Build Monitor is accessible from the qefgui Welcome Window, and the Windows menus of the Navigator and QEF Info tool. The Build Monitor gives access to the logs of current and past builds as well as the logs from from tasks started using go d, qremote g, or josh d. These tools allow the user to redirect the outputs to a file saved in the user's /.qtree/goes/host directory. Such files can then be viewed and managed using either the Build Monitor or g. Active builds can be monitored from here and can be easily halted or rerun with the push of a button.

The upper pane of the build monitor lists available current and historic builds or other jobs. The lower pane shows the logfile for the selected build. If the selected job is still running, the text area will display the changes as they happen. There are commands to delete existing logs, to re-run any particular job or halt a currently running job. The various commands and buttons on the build monitor are extensively documented in the on-line help.

Note:

Figure 5.12 shows build logs from three different hosts, gobo, matt, and kent. The Re-Run and Chg&Run buttons will use qremote to re-run the job if requested.

Figure 5.13 shows the QEF Info Tool's primary window, the Information Tool Browser. The Info Tool is raised by the qefgui Welcome Window, the help menus or buttons contained in every window or dialogue, and a variety of other mechanisms. It can also be invoked from the shell using the command qefinfo.

The main text display shows the Topic Information, the body of the current topic. Hyper-links in the display area appear underlined in blue (if you are using a color display). Clicking on a hyper-link will take you to that item.

At the top of the Topic Body area, there is an entry widget and a series of buttons. The entry widget displays the current topic, and can be used to enter a new topic. You can also specify a topic by selecting text or by clicking on the arrow to display the history of previous queries. The syntax for specifying topics is described later.

You can get help about the QEF Info Tool itself by clicking on the ? buttons.

The buttons let you handle most queries with a click:

Look up the current topic in the x-db databases.

Look up the current topic in the on-line man pages.

If the topic is a QEF command, run the command with a x flag for built-in information.

Search the x_db and the quete databases for matched items and list them in the Topic area.

Raise a dialogue box to allow the specification of the x_db databases to be searched for topics.

Raise a menu list to select one of three available dialogues boxes that support the selection and/or specification of man directories and sections to be searched, and to build the quete databases.

Jump back to a previous topic in the topic stack.

Re-read the current topic.

Swap the current topic with the previous topic.

The Info Tool's menu bar has four pull-down menus, File, Edit, Windows and Help.

File Menu

provides buttons to print and to close the window.

Edit Menu

contains buttons to invoke the search dialogues and to create a new pop-up window displaying the current item. The latter facility may be useful if you want to view an item such as the Table of Contents or a tutorial guide while accessing other help items.

Windows Menu

provides buttons to raise the other major windows in the GUI.

Help Menu

buttons to get help on Help itself, the Table of Contents, and other helpful information.

An entry in the entry widget, whether entered directly or by clicking on the selected text, can have one of several forms. The form of the entry can specify the database to be used or can use a regular expression matching against the database.

Form	Example	Query
term	qefdirs	Look in the x_db databases
term(x-cmd)	qefdirs(x-qef)	Look in a specific x_db database
*term	*tools	List the x_db items in the group *term
*term(x-cmd)	*tools(x-qef)	List group *term items in specific x_db database
term(*)	qefdirs(*)	Look up the man page
term(n)	ls(1)	Look up man page term in section n
term(1) <dir>	ls(1) /usr/man	Look up the section 1 man page in specified directory tree.
term(-x)	qef(-x)	Display -x output for Q-Tree program term
? rxp	? (x-q.*)	List items from all databases that match regular expression
? rxp1 & rxp2	? (1) & tree\.vrs	List items from all databases that match both regular expressions