TOC PREV NEXT INDEX DOC LIST MASTER INDEX



Using the GUI

When Apex starts, it opens a directory-viewer window that displays a list of files and directories. The directory-viewer window is sometimes referred to simply as the directory viewer. You can use the directory-viewer window to navigate through the UNIX directory structure, open files and directories, and view other files and directories. The directory viewer window is a type of window called a viewer window. Many of the features of the directory-viewer window also apply to other viewer windows, such as the Apex editor window. This module gives you an overview of the Apex directory-viewer window, shows you how to use it and shows you how to manage the Apex windows.

Prerequisites for this Module

Topics in this Module

Average Time to Complete this Module

45 minutes.


Using This Module

As you study this module, you may find it useful to position a directory-viewer window next to this browser window so you can refer to it. Moving windows is a function handled by Motif.

If there is no directory-viewer window open on your screen, open a directory viewer by executing File > Open and entering the Filename ~ for your home directory.


What is the Directory-Viewer Window?

Directory-viewer windows help you navigate through the UNIX directory structure and provide access to the various operations available in Apex. Whenever you visit a directory, a directory-viewer window is displayed. You have your home directory displayed in a directory viewer.

The display area of a directory viewer shows the objects that appear in the current directory. The current directory is always the first object in the directory-viewer display.

All other objects listed in a directory-viewer window are displayed in the following hierarchical order:

By default, certain files and directories are hidden from the display. Notably, any object having a name that begins with a period (.) is hidden.

You can modify the display to:

All of these modifications are described later in this module.


The Location Cursor

When you move the pointer into a directory-viewer window (or into any other kind of viewer window), the location cursor appears. When the location cursor appears in the form of an outline around the name of an object, as shown here, no object is selected.

You can move the location cursor using the up and down cursor keys. As you do so, the cursor selects the current object. Selected objects are highlighted in reverse video.

When you double-click a line that contains the name of a directory, Apex opens a directory viewer listing the contents of the selected directory. When you double-click the name of a source or text file, Apex opens an editor window that displays that file.


Directory-Viewer Dialog Boxes

Many directory-viewer menu commands open dialog boxes. When a dialog box opens, Apex often places the names of selected objects in appropriate dialog-box fields. To illustrate:

1. . In a directory-viewer window, use the up and down cursor keys described previously to select the name of a directory.

2. . Choose the Open item from the File menu. (Another way to identify this menu item is File > Open). Apex then displays the Open dialog box:

When the Open dialog box appears, notice that the name of the directory you have selected in the directory viewer appears in the Filename text field.

If applicable, the context of the directory you have selected —— that is, the directory's enclosing pathname —— appears in the Context field.

Do not close the Open dialog box. You will use it to navigate to a file in the next topic, Dialog Box Features.


Dialog Box Features

Dialog Box Icons

Inside the Open dialog box, to the immediate right of the Filename field, there is an icon called the Navigator Icon. The Navigator Icon, shown below, can help you navigate to any available file:

The Navigator Icon is one of six kinds of icons that can appear inside Apex dialog boxes. These six icons are:

The six icons shown above are often used in Apex software-development projects. They are, from left to right:

Dialog Box Buttons

Most dialog boxes have five buttons at the bottom. These buttons allow you to:
OK
executes a command or a sequence of commands and then closes the dialog box. Commands executed by different dialog boxes vary, depending on the functions of the dialog boxes.
Apply
executes a command or a sequence of commands, like the OK button, but leaves the dialog box open.
Reset
restores the dialog box to its initial state.
Cancel
closes the dialog box without executing any commands.
Help
displays the online help for the dialog box being displayed.


Navigating to Files

1. . From the Open dialog box you opened in the previous topic —— Directory-Viewer Dialog Boxes —— left-click the Navigator Icon. In response, Apex opens the Open-Filename dialog box (referred to as the file selection dialog box):

2. . When the file-selection dialog box appears, notice that Apex has copied the contents of the Open dialog box's Context field into the Directory field of the file-selection dialog box.

3. . Double-click on the name of a directory in the Directories scroll list. Notice that the names of the files in the directory you have chosen then appear in the Files scroll list. Meanwhile, the name of the directory you have selected appears in the Directory field.

4. . Place the cursor inside the Files scroll list and select the name of a file you want to open.

5. . Click the Apply button or OK button in the file-selection dialog box's button bar. Apex then copies the name of the file you have selected into the Filename field of the Open dialog box.

6. . When the name of the directory you want appears in the Filename field of the Open dialog box, open the file you have selected by clicking the OK button or the Apply button in the Open dialog box's button bar. (Clicking the OK button closes the Open dialog box and opens the file you have selected. Clicking the Apply button opens the file you have selected without closing the Open dialog box.)


Direct-Action Menu Commands

Some menu commands do not display dialog boxes, but act directly on any object selected in the display area of the directory-viewer window. By moving the location cursor, you can select the object to be operated on:

1. . Use the up and down cursor keys to select any object in the directory-viewer window.

2. . Click the Navigate > Visit menu item.

If the object you have selected is a directory, Apex displays the directory in a new directory-viewer window. If the object is a file, Apex displays the file in a new editor window.

3. . Close the window you just opened by clicking on File > Close in its menu bar.

Deselecting an Object

To deselect an object:

1. . First, select the object.

2. . To deselect it, press the Control key while you click the left mouse button on the object that has the location cursor. Another way to describe this operation is Control-click. Control-click toggles the selection state of an object.

When you complete these two steps, the location cursor is open and no object is selected.


Navigating With the Directory Viewer

The directory viewer lets you navigate through the UNIX directory structure. In this topic you will use the Visit and Enclosing commands to traverse the directory structure.

Using the Visit Command

In Apex, traversing the directory structure is referred to as visiting. When you visit an object, the new object is displayed in a new window by default. You can override this default behavior by visiting an object in place. Apex then places the new object in the current window, replacing the old object. By visiting objects in place, you can reduce the number of windows open on your screen at the same time. By definition, visiting in place is meaningful only when it is applied two like objects. For example, you can visit a directory in place from another directory.

If you pull down the Navigate menu in the directory viewer, you can see both the Visit and Visit In Place menu buttons. Both buttons allow you to visit either files or directories. You used the Visit menu button in the previous topic.

Using the Enclosing Command

Also on the Navigate menu are Enclosing and Enclosing In Place. The Enclosing menu button opens a new directory viewer displaying the parent directory. Enclosing In Place opens the parent directory in the current directory viewer window. Both these commands ignore any objects that may be selected. The names of the current directory and the parent directory appear on the first line of the directory viewer window.

Follow these steps to become familiar with how enclosing works. To conserve screen space, you will traverse in place.

1. . In the current directory viewer, select an object that is a directory.

Directory names, except for the current directory, are followed by a slash (/).

2. . Click on Navigate > Visit In Place.

This command places the selected directory into the directory viewer.

3. . Click on Navigate > Enclosing In Place.

This command places the parent directory in the directory viewer. Successive enclose operations would traverse higher in the directory structure.

Notice that the previous directory is now selected. In an earlier topic you learned that you can deselect an object in the display. Here is another way to do the same thing.

4. . Click Edit > Deselect Window.

This command deselects all selected objects in the current window. If you pull down the Edit menu once again, you can see the Deselect Other Windows and Deselect All Windows menu buttons. This is important if you have multiple viewers open at the same time. Apex recognizes selected windows across all viewers. These commands make it easier to ensure that you do not have an object selected in a viewer that is hidden by other windows.

Using the Mouse to Visit

Another way to visit an object in the current directory viewer window is to double-click on it.

1. . In the current directory viewer, place the pointer on an object an object and double-click on it.

2. . In the window created by the previous step, click on File > Close.

You can also use the mouse to visit an object in place.

3. . With the pointer on the same object, hold the Shift key down while you double-click.

4. . To return to the original directory, select Navigate > Enclosing In Place.


Using the Menus

You are already familiar with the menu bar, or you would not be reading this tutorial. However, there are other ways of selecting Apex commands than using the mouse with the menu bar. You can use the following methods for viewer or editor windows in Apex.

Using the Button Bar

Below the menu bar, you will find the button bar. It contains buttons that have the same effect as certain buttons in the pull-down menus. To use a command on the button bar, move the pointer to that button and click on the left mouse button.

The button bar has different default configurations, depending on which type of window it is in. You can configure the button bar for your own use.

For some windows, such as the Output window, the button bar is hidden by default. You can expose the button bar, or make more room for it, using the sash. To move the sash, point to it, press the left mouse button, and drag up or down.

You can find information on customizing the button bar in the online command reference.

Using Popup Menus

Many of the viewers and editors in Apex have popup menus that contain some of the more common commands available in the menu bar. To use the popup menu, follow these steps. In this example you will visit an object:

1. . In the directory viewer, click on a subdirectory to select it.

2. . With the pointer in the display area of the window, press the right mouse button.

3. . Drag the mouse to the Visit In Place popup menu button and release the right mouse button.

The popup menu disappears and Apex opens the selected directory in place.

You will return to the enclosing directory in the exercise on the next topic.

Using the Keyboard

You can select items from the menu bar without using the mouse. To select commands using the keyboard, follow these steps:

1. . Make certain the pointer is inside the frame of the window.

2. . Press the F10 key.

This highlights the File menu on the menu bar.

Use the cursor keys to move the highlighting among the menu buttons.

3. . Once you are comfortable with the way the cursor keys move selection among the menu buttons, stop the selection on Navigate > Enclosing In Place.

4. . To invoke the command, press the Return key.

If you decide not to select any command, you can exit from keyboard mode by pressing the Esc key.


Expanding and Eliding the Display

You can display multiple levels of subdirectories within a single directory viewer. This feature is controlled by the View > Expand and View > Elide menu buttons.

Using Expand, you can display successive levels in the directory structure.

1. . Open a directory viewer by executing File > Open and entering the directory

$APEX_HOME/doc/html/all/tutorial/example_dir

2. . In the directory viewer created above, move the location cursor to select the directory man.

3. . Select View > Expand twice.

This changes the display, adding the objects under the directory man. In this case, there is only one object.

4. . Now select View > Elide.

This has the opposite effect of Expand, hiding the lowest level of objects under the directory man1.

5. . Once again, select View > Elide.

This command returns the display to its original state. Thus, using Expand and Elide, you can selectively display multiple levels of directories in a single directory viewer.

Retain the current directory viewer for the next exercise.


Changing the Display Format

By default, the directory viewer displays the simple names of objects. The View > Format Submenu allows you to selectively display additional information.

1. . Using the directory viewer used in the previous exercise, select the directory man.

2. . Select View > Format > File Attributes.

If you are not familiar with cascading menus, you can select this item by dragging the pointer down the View menu to the Format submenu, then right onto the submenu to select File Attributes.

Note: Your menus menu include additional menu items based on what you have installed.

The display for the directory man now contains information similar to that available through the UNIX command ls -l. Here is an example of the File Attributes format:

3. . To return to the simple name format used as the default display, select View > Format > Names.

It is also possible to change the format for all objects in the directory viewer at the same time. To do so, make sure all objects are deselected.

4. . Select Edit > Deselect Windows

5. . Select View > Format > File Attributes.

All objects in the display now have the File Attributes format.

Changes to the display format only affect selected objects in the current viewer. If you open new directory viewers, they will use the default format.


Filtering the Display

By default, the directory viewer filters, or hides, some objects from display. Among these objects are files and directories that Apex creates and maintains as part of its operation. You can change the filtering, as shown in the following exercise. The first step is intended to return you to your home directory without adding another window.

1. . Do one of the following things:

2. . In case you have any objects selected in your home directory viewer, select Edit > Deselect Window. Otherwise, the next command will only affect the selected objects.

Any object having a name that begins with a period (.) is hidden by default. The following step will make those files visible.

3. . Select View > Filter > Show All.

4. . To return the directory viewer display to the default filter, select View > Filter > Original Filter.

Changes to the filter only affect selected objects in the current viewer. If you open new directory viewers, they will use the default filter.


Using the Windows Window

The Windows window displays the names and types of Apex windows currently open. From this window, you can perform a variety of operations on the active windows including raising, iconifying, and closing. This makes it useful if you work with a large number of windows open at the same time.

1. . From any open directory viewer window, select Navigate > Windows.

This displays the Windows window. If you open this window as the first action after invoking Apex, the display looks similar to this:

2. . Move the Windows window to somewhere it will only be partially covered by other windows.

A good scheme is to place this window in one of the lower corners of the screen.

3. . In the directory viewer, visit any object.

A quick way to visit an object in the directory viewer is to double-click on it.

When Apex opens the new object, the Windows window adds it to the display. For example, if the new object is the text file new_topic, the Windows display changes to this:

4. . In the Windows window, select the window you just opened.

5. . In the Windows window, select Navigate > Iconify.

This command is also available on the button bar.

The window is still open, but iconified. You could restore the window using the Motif window menu on the icon, but it is also possible to do this from the Windows window.

6. . In the Windows window, make sure the iconified object is still selected.

7. . In the Windows window, select Navigate > Raise.

Here is another way to raise a window:

8. . In the Windows window, double-click on the debugger.

By now, there is a good chance your directory viewer window is at least partially covered by other windows. You can use the Raise command (or double-click) to raise hidden windows.

9. . In the Windows window, select the directory viewer window (or any other window that is hidden).

10. . Select Navigate > Raise.

In this way, you can quickly locate any Apex window, even if it is hidden from view.

As with other windows, you can perform operations on multiple windows at the same time.

11. . Drag the pointer down the Windows window display area to select all Apex windows at once.

12. . In the Windows window, select Navigate > Iconify.

All of your Apex windows are iconified.

One strategy for dealing with severe window clutter is to use the Iconify command and then selectively restore needed windows.

Correspondingly, you can raise multiple windows with a single command.

13. . In the Windows window, with all objects still selected, select Navigate > Raise.

You can close selected Apex windows from the Windows window:

14. . In the Windows Window, select the object that you opened in step 3.

15. . Select Navigate > Close Selected.

Apex closes the window and removes the corresponding object from the display area of the Windows window.


Controlling Output and Message Windows

How to Tell the Difference Between the Output and the Message Window

Output windows display messages being output by jobs executing under Apex. If there are two or more jobs running at the same time, there is an Output window for each. Message windows display messages from Apex to you. Both of these windows are editors, rather than viewers.

Apex reuses these windows interchangeably, renaming them as needed. Thus, an Output window can become a Message window, and then an Output window again. Try this demonstration:

To open a Message window:

1. . Open a shell window by executing the Tools > Shell command.

2. . In the Apex xterm, enter:

Notice the Title bar:

3. . Change the window to an Output window by entering the following in the Apex xterm:

Notice how the Title bar has changed:

You can close any Message or Output window using File > Close. It may prove more convenient to leave at least one window open and placed somewhere on the screen where it causes the least bother. In this way you won`t have a window appearing in the middle of the screen when Apex has output to display.

4. . Move the Message window to a relatively unused portion of the screen, such as one of the lower corners.

In the scheme above, the Message window overlaps the Windows window. To raise the Windows window, click anywhere on its frame.

Window Options

If the Message or Output window is hidden on the screen, Apex automatically raises it to display output. If you iconify the window, Apex automatically restores it to display output. You can modify this behavior using the buttons in the Options menu.

If a toggle button is on (appears to be depressed), the following behavior is enabled:

If you toggle the Auto Restore option off and then iconify the window, it will continue to collect output from Apex, but remain iconified until you restore it yourself.

Reusing Windows

By default, Message and Output windows are reusable for the next user message or job output. By deselecting Options > Allow Reuse, you can cause it to stop receiving output. This allows you to control the output that collects in a particular window. Once you deselect Allow Reuse the rules are:
Window Type
Rule
Message
Accepts all user messages; rejects job output. Output collects in a separate window.
Output
Rejects all user messages and all job output.

Modify the current Output window to reject reuse:

1. . In the Output window, select Options > Allow Reuse.

If you pull down the Options menu again, the Allow Reuse button is now off.

2. . Send more job output by entering in the Apex xterm:

You should now have a second Output window displayed.

3. . In the new Output window, select File > Close.

4. . In the remaining Output window select Options > Allow Reuse to toggle the option back to the on setting.

5. . Send a final bit of job output by entering in the Apex xterm:

6. . One reason to collect output selectively like this is to save it into a separate file for later analysis. You'll learn how to do that in the next topic.

Context

For editor windows such as the Message and Output windows, the context is the directory to which they belong. For Message windows, the context is always your home directory. For Output windows, the context is the directory from which job output was last sent to the window.

Saving Window Output

You can save the contents of an Output window to a file. For example, assume that you want to save the output from steps 1. and 2.

1. . In the Output window, select File > Save As.

This brings up the Save As dialog box. The Context field displays the name of the context from which job output was last sent to the Output window.

You can change the context by replacing it with a pathname for the context, if desired.

2. . In the Filename field of the dialog box, type the name you want to give the new file.

3. . In the dialog box, click on OK.

Deleting Objects

Now that this exercise is almost finished, the file you just created no longer needed. To remove it, follow these steps:

1. . In the directory viewer, click on the file to select it.    

2. . Select File > Delete Object.

This displays the Delete Object dialog box. The pathname for the selected file should appear in the right list box.

3. . In the Delete Object dialog box, click on OK.

Three things happen as a result:

Controlling the Jobs window is the subject of the next topic.


Controlling the Jobs Window

When a job is executing, Apex displays this fact in the Jobs window. By default, when job execution is complete, the window remains displayed. You can change the behavior of the Jobs window through the Options menu. Use the Navigate > Jobs command to if the Jobs window is not displayed.

If a toggle button is on (appears to be depressed), the following behavior is enabled:

In looking at the options above, you can see that one solution is to set the Auto Create option to off. Once you close the Jobs window, Apex will not create it automatically during the current session. This means you have to open the Jobs window manually to perform the operations available through its menus.

Another solution is to leave it open, but move it somewhere out of the way. If you are already doing this with the Message window, there may not be an attractive place to park the Jobs window.

A third solution is to set Options > Auto Iconify to on. This causes Apex to iconify the Jobs window automatically when the last job completes. The exercise in the next topic demonstrates this feature.

In the following exercise, you will modify the behavior of the Jobs window. As an artifact of the exercise, we will create and remove the file tut_file in your home directory.

Note: If you already have a file named tut_file in your home directory, it will be removed as a result of this exercise.

1. . To create or raise the Jobs window, execute the File > New > New File command and enter $HOME/tut_file in the Name field. (This job creates the file tut_file.) Click OK.

You will notice that the Jobs window displays a job and then clears the display.

2. . In the Jobs window, select Options > Auto Iconify to toggle the option to the on setting.

3. . Watch the Jobs window as you remove the file tut_file by executing the File > Delete Object command and entering $HOME/tut_file in the Objects to delete field. Click OK.

When the job completes, Apex iconifies the Jobs window. Unless you have set the Auto Create option to off, Apex will restore the Jobs window the next time it starts a job.

4. . Watch the last position of the Jobs window as you try to remove the $HOME/tut_file again (step 3.) The Jobs window appears for the duration of the job and then iconifies once again. If you missed the action, you can repeat step 3 again.


Rational Software Corporation 
http://www.rational.com
support@rational.com
techpubs@rational.com
Copyright © 1993-2001, Rational Software Corporation. All rights reserved.
TOC PREV NEXT INDEX DOC LIST MASTER INDEX TECHNOTES APEX TIPS