![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
Basic Operations The Apex GUI is based on the X Window System and Motif. The GUI is window-based and each window is associated with a menu bar of commands available from that window. Some commands require additional information and display a dialog box to obtain the information. Designating objects may be done using the mouse. Several levels of online help is also available.
About this Chapter
The chapter describes the basic operations used in Apex. The topics covered are:
- The Mouse and Mouse Buttons
- Windows and Menus
- Apex Dialog Boxes
- Using the Apex Dialog Box
- Drag-and-Drop
- Learning More About Apex
The Mouse and Mouse ButtonsMost mouse devices used with X Windows have three buttons: left, middle, and right.
X allows you to interchange the functions of the left, middle, and right mouse buttons. For example, you can reassign the functionality of the logical right button to the physical left button, and vice-versa —— a change you might find convenient if you are left-handed.
This guide refers to mouse buttons by their default (positions) left, middle, and right.
To invoke operations you position the pointer and then perform one of the mouse operations described in Table 1 .
Windows and MenusThe main features of any Apex window are shown in Figure 1. The features labeled in Figure 1 are described in Table 2.
Figure 1 Apex Window Features
![]()
In Apex, the layout of menus and the operations performed are consistent from window to window. Once you are familiar with one kind of Apex window, you will find it easy to use the other windows as well.
Mnemonics and Accelerator Keys
Mnemonic and accelerator keys provide shortcuts for invoking the commands associated with Apex menu items directly from your keyboard.
A mnemonic is a unique letter abbreviation for a menu item. On the menu item, the mnemonic is underlined in the menu item label. Once the menu is displayed, you can select a button by typing its mnemonic letter, which is not case-sensitive. For example, the mnemonic for File > Print is P (or p), as indicated by the underline in the button label: Print.
An accelerator is a unique key combination for a menu item. On the menu item, the accelerator is shown to the right of the menu item label. Without displaying the menu, you can select a button by typing its accelerator keys. For example, the accelerator for Edit > Search is Control-s.
Pop-up Menus and the Right Mouse Button
Apex provides pop-up menus that contain commonly used buttons from the menu bar. Each type of window has it own pop-up menu. To use a window's pop-up menu:
- 1 . Place the pointer in the window's display area.
- 2 . Press the right mouse button.
- 3 . Drag the pointer to the button you want to select and release the mouse button.
An example of a pop-up menu from the directory-viewer window is illustrated in Figure 2.
Figure 2 Pop-Up Menu from the Directory Viewer
![]()
Cancelling a Menu
If you have a menu displayed and decide you do not want to execute a command on this menu, you can enter an Escape key or left-click the mouse outside of the menu.
Using the Keyboard to Select Commands
If you have a menu displayed and a specific command highlighted, you can enter a Space or a Return key to execute the command.
Apex Dialog BoxesMany Apex menu items open dialog boxes. You can also open dialog boxes from other dialog boxes.
The design of a particular dialog box depends on the job it performs. However, many Apex dialog boxes contain the same kinds of controls.
Radio Buttons
Radio buttons, which are diamond-shaped, offer a choice of mutually exclusive options; you can choose only one option at a time. An example of Radio Buttons can be found in Figure 3.
Figure 3 Radio Buttons
![]()
To select a radio button, left-click it. Selecting one radio button automatically deselects the previously selected radio button.
Check Boxes
Check boxes are small square buttons that offer a choice of nonexclusive options. An example is illustrated in Figure 4.
Figure 4 Check Boxes
![]()
To select a check box, left-click it. To deselect it, left-click it again. Other check boxes are unaffected.
Text Fields
A text field is a field in which you can enter text and is illustrated in Figure 5.
Figure 5 Text Field
![]()
Often text fields are accompanied by the icons described in Figure 7. These icons can be used to fill in the appropriate information in the text field.
Scroll Lists
A scroll list contains a list of objects such as files or directories. From a scroll list, you can choose one or more objects and perform an action on the object or objects you have chosen. For example, in a dialog box that selects files, you can choose a file by selecting its name in a scroll list.
Every scroll list is equipped with a pair of scroll bars that can scroll the items in the list vertically and horizontally to display all the information in the list. An illustration of a scroll list can be found in Figure 6.
Figure 6 Scroll Lists and Bars
![]()
Selecting an Item from a Scroll List
To select an item from a scroll list, scroll the list until the item is visible and then left-click it. To select several sequentially listed objects, drag instead of clicking. A left-click or left-drag also deselects all other objects in the list.
A Control-left-click selects an object or, if the object is already selected, deselects it. Other selected objects remain selected.
A Shift-left-click selects all objects from the last object selected with a left-click or Control-left-click to the current object. If this range contains some objects previously selected by a Shift-left-click, they are deselected.
Selecting Multiple Items from a Scroll List
You can select multiple items from a scroll list simultaneously by using these techniques:
- To select the name of just one item, position the cursor over the first item you want to select and press the left mouse button.
- To select multiple items that appear consecutively in a scroll list, position the cursor over the first item you want to select and press the left mouse button. Hold the Shift key down and drag the mouse to the name of the last item you want to select. Notice that all items between the first item and the last item you select are highlighted. In this way, you can select as many consecutive names as you want.
- To select items that do not appear consecutively in a scroll list, select the first item you want by clicking the left mouse button. Then hold the Control key down and click the left mouse button again over the second item you want. Continue this process until you have highlighted all items you want to select. This way, you can select as many items as you like.
Adding and Removing Items from a Scroll List
When a scroll list appears in conjunction with a Text Field, you can add object names to the scroll list by inputting the name in the text field and clicking the Add button as illustrated in Figure 7.
To remove objects from a scroll list, select the object and click Remove as illustrated in Figure 7.
Figure 7 Scroll List Dialog Box
![]()
Cancelling a Selection
If you have a selection and you want to cancel it, you can select an invalid item, for example the screen background is usually such a place.
In Motif there is a standard key used to cancel things. This is usually the Escape key. Pressing the cancel key will abort the selection.
Dialog Box Icons
Many dialog boxes contain icons that can help you enter correct values in text fields. These icons are illustrated in Figure 8.
Figure 8 Dialog Box Icons
![]()
The six icons used in dialog boxes are as follows:
- Navigator Icon
- Left-clicking the Navigator Icon displays a File Selection dialog box (see The File Selection Dialog Box). Right-clicking the Navigator Icon brings a pop- up menu of subsystems, system configurations, and other destinations to choose from.
- History Icon
- Left-click the History Icon to retrieve earlier values for a text field.
- Completion Icon
- Left-click the Completion Icon to complete the partial pathname you have typed in a text field.
- Alternatives Icon
- Left-click or right-click the Alternatives Icon to pop up a menu of alternative text-box entries from which you can choose.
The Subsystems and System Configurations Icons are available only by first clicking the Navigator Icon, which brings up the File Selection dialog box.
- Subsystems Icon
- Navigate to any subsystem in a project by clicking the Subsystems Icon. Apex displays a cascading menu listing all subsystems in your project. If you choose the name of a subsystem, the pathname of that subsystem replaces any subsystem pathname in the field associated with the Subsystems Icon.
- System Configurations Icon
- Helps you navigate to any system configuration that is part of an open project . You choose the name of the system configuration from a list of specified in a project. That name then appears in the text field associated with the System Configurations Icon.
Dialog Box Buttons
Most Apex dialog boxes have a row of buttons at the bottom as illustrated in Figure 9.
Figure 9 Dialog Box Buttons
![]()
The function of these buttons are described in Table 3.
The File Selection Dialog Box
The Navigator Icon, illustrated in Figure 10, can help you navigate to any available file.
Figure 10 Navigator Icon
![]()
When you left-click the Navigator Icon, Apex opens another dialog box called the File Selection dialog box. You can use the File Selection dialog box to navigate to any available file.
Controls in the File Selection Dialog Box
The controls in the File Selection dialog box include:
- A Directory text field in which you can type the name of a directory you want to locate.
- A text field labeled Filter. By default, the Filter field contains an asterisk ("*") the UNIX symbol for all files. You can limit the types of files shown in the File Selection dialog box by changing the contents of the Filter field, using standard UNIX filename and wildcard conventions —— for example, *.txt.
- Check boxes labeled In, Out, Uncontrolled, Deleted, Out-Of-Date, and Hidden. Check one or more of these boxes if you want to see only files that are checked in, checked out, uncontrolled, deleted, or out of date. (For more information on files that are checked in, checked out, and uncontrolled, see Using and Customizing Summit/CM
.for Apex/Summit) When the Filter button is pressed, the directory specified in the Directory field is read and entries in it that match the filter are displayed in the Directories list and the Files list.- A Directories scroll list that contains the names of subdirectories contained in the selected directory.
- A Files scroll list that contains the names of the files in the currently selected directory.
- A row of buttons to perform actions described in Dialog Box Buttons.
- A group of five icons including the Subsystems icon, System Configurations icon, Alternatives icon, History icon and Completion icon. See Dialog Box Icons for a description of these icons functions.
Note: In the title area of the File Selection dialog box, the title shown will be the name of the dialog box you accessed the Navigator Icon from. For example, if you are using the Open dialog box and click the Navigator Icon next to the Filename field, the File Selection dialog box will have Open - Filename in the title area.
When you select a file or directory using the File Selection dialog box and click the OK button or the Apply button, the name of the file or directory you have selected is copied automatically to the field of the dialog box from which the File Selection dialog box was started. You can select multiple directories if you like.
Using the Apex Dialog BoxApex uses many kinds of dialog boxes, but all of them have certain features in common. For example, the Open dialog box contains a number of features that are common to many other Apex dialog boxes.
This section uses the features of the Open dialog box to describe some of the common general features of Apex dialog boxes.
The Open Dialog Box
The Open dialog box is illustrated in Figure 11.
The Open dialog box contains these controls:
- A Filename text field with a Navigator Icon, a History Icon, a Completion Icon, and a Clear button that clears all text from the Filename field. These three icons are described on Dialog Box Icons.
- A Context text field with the same three icons. The Context text field is used as the context for unqualified names in the Filename field.
- A check box labeled In Place. If In Place is checked, Apex reuses the window from which the Open dialog box was selected. Otherwise, Apex opens a new window and displays the selected file in that window.
- A row of buttons you can click to perform the actions described in Dialog Box Buttons.
Figure 11 Open Dialog Box
![]()
Using the Open Dialog Box
To open a file using the Open dialog box, type the name of the file you want to open in the Filename field, and click OK or Apply.
Note: When you enter a pathname in an Apex dialog-box text field, you can include wildcards in the pathname you type. The wildcards recognized in file and directory text fields are the standard UNIX wildcard symbols: ? matches any single character, and * matches zero or more characters.
Suppressing the Display of a Dialog Box
You may notice that some of the commands on the directory-viewer menu bar end with the ellipsis symbol "...". For example, the File > Open... command displays the Open dialog box.
How "..." Commands Work
When a command on the menu bar ends with an "...", Apex opens a dialog box from which you can select options and parameters required by the command. Then you can execute the command by clicking the OK or Apply button inside the dialog box.
`Just-Do-It' Commands (Shift Modifier)
In some cases you can override the default behavior of a command that is followed by a "...". Overriding a "..." command is sometimes referred to as issuing a "just-do-it" command. When you issue a "just-do-it" command, Apex does not display a dialog box. Instead, Apex executes the command immediately, using default settings for any options or parameters the command might require.
To execute a "just-do-it" command, press the Shift key while choosing the command you want to execute. If the menu item you have chosen offers a "just-do-it" option, the command executes immediately using default settings. The Shift key is called a modifier.
If you attempt to issue a "just-do-it" command from a menu item that does not offer the "just-do-it" option, the command displays its usual dialog box.
Forcing the Display of a Dialog Box (Control Modifier)
Sometimes a menu item that is followed by a "..." on the menu bar does not display a dialog box as you might expect, but immediately executes its associated command using default values. For example, if you execute the Compile > Code... command from the directory viewer, Apex displays a dialog box, but if you execute Compile > Code from a language editor, a dialog box is not displayed. Instead, Apex executes the Compile > Code command immediately using default values.
When a menu item behaves in this fashion, you can override this behavior and force it to display a dialog box by pressing the Control key when you choose the command. Then, instead of executing immediately, the command opens a dialog box that allows you to set options and parameters in any way you like. You can then execute the command —— using customized parameters instead of accepting the command's defaults —— by clicking the OK or Apply button inside the dialog box. The Control key is called a modifier.
Job Control from Dialog Boxes
Job control is provided from all Apex boxes. To access the Job Control dialog and other commands, right click on any OK or Apply dialog button. A new menu will appear. The top selection, Job Control ..., invokes the Job Control dialog box while the rest of the entries simply change settings in the Job Control dialog. The Job Control dialog box enables users to define or modify how a job is to be run.
Customizing Dialog BoxesAny dialog can be customized by putting a dialogName.ext file in the user's $HOME/.Rational directory. Here, dialogName stands for the name of the dialog (and it is assumed that there exist a file dialogName.dlg in the release area).
Advantages and Disadvantages
In Apex 3.2 and higher, whenever a dialog file .dlg is read, Apex looks for a file with same name but extension .ext and reads it, if found. The main advantage of this is that we can customize any dialog personally, without modifying the original .dlg file. In the past, if we wanted to customize a dialog, we copied it over from $APEX_HOME/dialogs and put it under ~/.Rational. This would replace the standard dialog. Now, the user has the option of adding his/her own specific customizations to the dialog definition using a .ext file. The dialog file .dlg from the release area is read first and then the customizations in the .ext file in ~/.Rational. The presence of a .dlg in user's ~/.Rational will replace the standard existing one.
Advantages of having .ext (instead of .dlg) in user's ~/.Rational
- The user needs to concentrate on that particular feature of the dialog that he wants to customize. No need to go through the whole maze.
- Whenever a new Apex release is installed, there is no need to copy the new .dlg file (if it has changed) over to ~/.Rational and then redo his/her customizations. Thus the .ext file can be carried over from release to release, even if the original .dlg file has changed.
Disadvantages of having .ext (instead of .dlg) in user's ~/.Rational
There is a limit to the customization that can be achieved by way of the .ext file in user's ~/.Rational. For instance, we can never entirely change the command to be run by the dialog (though we can influence the options that are passed to the command). This is because, the exec function (which is the action module) of any dialog cannot be modified in .ext file.
In some cases, the .ext file will be closely related to the .dlg file. In a new release, if the corresponding .dlg file is changed substantially, the user will be in trouble. For example, if the user refers to a widget name in the .ext and if that widget is not present in the new .dlg, the .ext will be useless.
Functionality
Let us consider the following examples:
- 1 . If you want the hostname to appear on the title of the main Apex window that comes up first, you simply create a file ~/.Rational/main_apex_panel.ext and insert the following three lines:
%prog post_init set title = \Qvalw main_apex_panel\Q setw main_apex_panel "$title is on \Qhostname\Q"
The title of any dialog can be changed this way, by using the dialog name in place of main_apex_panel.
- 2 . If you want the Exit Apex dialog box to come up with the Restore this session on next startup button turned off, create a file ~/.Rational/exitApex.ext and insert the following two lines:
In each of these examples, we used post_init after the predefined init routine (which will be in the .dlg file). If you want to replace that init routine, you can define your own %prog init routine.
Summary
To summarize, the .ext feature is ideal for small customizations. Especially for changing default behavior when you don't have other options. and don't want to put the entire .dlg file in ~/.Rational. If you want to default to Private Check Out in your Check Out dialog, it is enough to set the environment variable APEX_PRIVATE to True; but there is no shortcut way in the Exit Apex dialog for setting that switch to False. The main draw back of putting the entire .dlg file in ~/.Rational is that we don't get the newest version if this has changed in a later release of Apex.
Drag-and-DropApex supports the user interface metaphor known as "drag-and-drop". It can be used to perform manipulations of the button bar, to initialize sections in dialog boxes, to perform in-place visit and show operations, and to directly perform Apex commands that operate on "two" objects, such as File > Copy Objects.The Apex treatment of drag-and-drop is based directly on the standard Motif drag-and-drop mechanisms.
Performing a Drag-and-Drop
To do a drag-and-drop operation, you first move the mouse cursor over a piece of a window which has been enabled by the application to support dragging. In the Motif terminology such a place is called a Drag Source.
You depress the second mouse button and keep it pressed. If the mouse cursor is over a legal drag source its shape will change into a new icon called the Drag Icon.
If that occurs, then to do the drag, you move the mouse until the drag icon is positioned over the place where you want to do the drop. Places that have been enabled by the application to receive a drop are referred to as Drop Sites.
As you move the drag icon over a legal drop site, the mechanisms will place a thin box around that area. This may provide some visual help in knowing if the cursor is over a legal drop site. To do the drop, release the second mouse button.
If the place was not a legal drop site then you will see a visual effect of the drag icon being sucked back to the drag source. This indicates that no drop operation occurred. Even if a drop operation occurs at the mechanism level, at the application level there may be not be a drop operation defined for the given object types involved and an error message will be given and no change will occur.
Cancelling a Drag
If you have started a drag and you want to cancel it, you can do the drop over a site that you know to be illegal, for example the screen background is usually such a place.
In Motif there is a standard key used to cancel things. This is usually the Escape key. Pressing the cancel key during a drag will abort it.
Within Apex, things have been set up so that doing a drop on the same item from which a drag started is a no-op. So, for example, if you press the second button, hold it, don't move the mouse, and then release the button, at the application level no drop should occur.
Drag Icons
When doing a drop it is important to be aware of the so-called hot spot of the drag icon when positioning it over a drop site. For the standard drag icons there is a small pointer on the top left corner. The tip of that pointer is the significant area to position over the drop site.
Apex currently uses the standard drag icons that Motif provides. For drags initiated from textual areas, the Motif mechanisms use a different shaped icon from that which they use for drags from other areas.
Object Kinds in Apex
There are the usual filesystem objects corresponding to files and directories like subsystems (.ss), Rational (.rss), Apex/Summit views (.wrk or .rel), switch files, configuration files (.cfg). In Apex/Summit, there are other object types specific to Apex which don't directly correspond to filesystem objects. These include such things as version objects, history objects, export_set objects, the imports set of a view.
The resulting operation which occurs will depend on the types of the two objects involved. The object being dragged is called the source object. The object being dropped upon is called the target object.
The general kind of operation where drag-and-drop is appropriate is what we might call a "two" object operation. Two object operations require two arguments which may be of the same or of different object kinds. Examples of two object operations include grepping for a text string in an Apex/Summit view or Rational subsystem, or for Apex/Summit, accepting changes from one view to another or adding an import to some view's import set.
Object Sources and Targets
In order to have these typed objects as drag sources, one needs a place to drag them from and a place to drop on them. The most frequent place from which this can be done is from one of the many different directory-type windows in Apex. Each line in one of these windows represents an object of a particular type. When you point the mouse cursor at one of these lines and start a drag you will be dragging an object of that type. When you do a drop onto one of these lines you will be dropping on an object of that type.
For certain operations there can be more than one object being dragged or dropped on at a time. This is done by using selections.
If you point at a line which isn't selected only that object is dragged independent of whether there is a selection somewhere else in the window. If there is a selection and you point at any one of the selected items, then all of the selected items in that window are dragged.
Similarly, if you drop on an unselected line, only that object is dropped on. If there is a selection and you drop on any one of the selected lines, then you are dropping on all of the selected objects.
Learning More About ApexApex provides several help facilities. The online tutorial, online help files, and online manuals are accessible from the Help command menu as illustrated in Figure 12. The manual pages provided by Apex are accessible from the UNIX command line within an Apex shell window.
Figure 12 Help Menu
![]()
For additional information regarding Help resources see Getting More Information in the Rational Apex Getting Started guide.
Rational Software Corporation http://www.rational.com support@rational.com techpubs@rational.com Copyright © 1993-2002, Rational Software Corporation. All rights reserved. |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |
![]() |