TOC PREV NEXT INDEX DOC LIST MASTER INDEX




Drag-and-Drop Interface

Apex supports for the user interface metaphor known as "drag-and-drop". There are several different contexts within Apex where drag-and-drop can be used to conveniently perform certain operations which would otherwise be tedious or impossible. 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 accept_changes, file copy, add import, compare views, show differences, show usage, grep...

The Apex treatment of drag-and-drop is based directly on the standard Motif drag-and-drop mechanisms.

HOW to Use Drag-and-Drop

To do a drag-and-drop operation, 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.

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.

When that occurs, to do the drag, 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 the drag icon is moved over a legal drop site, a thin box will be placed around that area. This provides visual help in knowing if the cursor is over a legal drop site. To do the drop, release the second mouse button.

If a legal drop site was not selected, you will see a visual effect of the drag icon being sucked back to the drag source. This indicates that no drop operation occurred. An error message will be displayed and no change will occur.

Cancelling a Drag

There are several ways to cancel a drag operation.

Within Apex, doing a drop on the same item from which a drag started will have no effect. So, for example, if you press the second button, hold it, don't move the mouse, and then release the button, no drop occurs.

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.

Apex Windows

It is important to be aware of the different kinds of entities which Apex places on the screen. There are two distinct kinds of screen entities which Apex creates.

The first is the dialog box. It does not have a menu bar but rather has a row of buttons along the bottom. It has a distinctive color. Each dialog has a varied contents to suit the operation it represents.

The other kind of entity produced by Apex is referred to by various names, including editor window and viewer. These windows have a menu bar at the top, followed by a button bar (also known as a command bar or tool bar) which may be initially hidden for some windows and a main window area. These windows use the standard Motif list and text widgets for the main area.

Object Kinds in Apex

To understand the semantics of various drag-and-drop operations in Apex, it's important to be aware of the various kinds of objects which exist within Apex.

There are the usual filesystem objects corresponding to files and directories. Apex also includes are more specific object types derived from these, like view, subsystem, switch file, configuration file, etc.

Other object types exist for Apex which don't directly correspond to filesystem objects. These include version objects, history objects, export_set objects, the imports set of a view, job objects, Ada declarations, individual switches, etc.

There are also primitive value objects such as text objects, location objects and time objects.

All of these objects can be directly manipulated with drag-and-drop.

The resulting operation which occurs depends 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 specific operations which are available will be described later.

The general kind of operation where drag-and-drop is appropriate is what we might call a "two" object operation. Most of the operations in Apex are "one" object operations, that is, an operation where one object kind is involved.

Two object operations require two arguments which may be of the same or of different object kinds. Examples of two object operations include, accepting changes from one view to another, adding an import to some view's imports set, running show usage of an Ada item in a particular scope, or grepping for a text string in a view.

These kinds of examples and several others are where drag-and-drop can be useful.

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 mouse cursor is pointed at one of these lines and a drag is started, an object of that type will be dragged. When a drop is done onto one of these lines, an object of that type will be dropped.

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, all of the selected items in that window are dragged.

Similarly, if you drop on a non selected line, only that object is dropped on. If there is a selection and you drop on any one of the selected lines, you are dropping on all of the selected objects.

So, for example, if you want to accept_changes from one view to five others, place a selection on the five views in a subsystem window. Then, drag the source view from wherever it occurs in any window, possibly the same window, and drop it on any one of the selected lines in the subsystem window.

Hold_Window Use in a Drag-and-Drag Context

To see what the type is of an object being dragged, use the Hold window. Objects can be placed into this window for various reasons, including to see what they are, to accumulate items for a future drag, to get at derived objects from a given object, to do type conversions of an object before a drag, or to use them as drop sites.

You can access the Hold window by either selecting the Tools > Hold Set > Show or selecting the Hold menu item which is on many popup menus (or at Tools > Hold Set > Hold). This latter menu item both raises the window and places the selected items in the hold set.

To see what is being dragged, raise the Hold window, drag something and drop it on either the menu bar of the Hold window or on the white space at the end of the window. Dropping on the menu bar replaces the contents of the window with the dropped items. Dropping on the white space adds the dropped items to those already in the hold set.

For example, to visit or drag the model of a view, place the view in the Hold window and use the menu item Hold > Model which replaces the contents of the hold set with the view's model. You can then visit it or use that line as a drag source.

If you have a file that you want to edit without changing the update time, place the file in the hold set. Do Hold > Update_Time. This places a time object in the hold set. Edit the file and when you are finished drag the time object and drop it on the line for the file in its directory window. The update time will be reset to that value.

Similarly, to accept the latest version of a C++ header file for which you have verified that it has only upward compatible changes from the version currently in your view, and you don't want to wait for the three hours of recompilation that would occur if you just accepted the file, save the update time before the accept, do the accept, and drop the time on the file after the accept.

When you drag an object of a derived file type, the semantics of the drop operation is based on the derived type. For example, if you drag a configuration file and drop it on a view, you get the semantics based on those types of objects. To treat the configuration file as just a file, use the Hold window to convert it to the base type using Hold > Convert > To_Base_Kind and then do the drag from there.

Given the atomic nature of drag-and-drop, it is required that the source and target objects both be visible on the screen at the same time. This may be difficult or impossible if, for example, the objects are both in the same linear list window and can't both fit on the screen at the same time. To do drag-and-drop in this case, place one of the objects in the hold set and start the drag from there.

When the hold set is replaced, the previous set is not lost but retained in a history list. Previous hold sets can be displayed using View > Previous (Control-P)

Filesystem objects in the Hold window can also be used as drop sites just as if they were in a directory-type window.

Object List Windows

The Hold window is generally used for short lived object interactions within one session. There is a also a mechanism for creating other windows which can be used to hold arbitrary objects. These windows can be saved and used in future sessions.

To create one of these windows, use File > New > New File to create a file with the extension .apexdt, for example, objects.apexdt. This creates an empty object list window. To add objects to it, drag them from anywhere on the screen and drop them on the menu bar or the blank space at the end of the window. This places the dropped objects at the end of the list of objects in the window (if any). To delete objects from the window, select them and do Edit > Delete.

To retain the window's current contents across sessions, select File > Save. In a later session, simply visit the file.

Objects in this kind of window can be visited or serve as drag sources or as drop sites.

Such a window can be used to hold task objects or commonly visited files or commonly visited places in files.

For example, this mechanism can be used to hold Ada_items of the ten places, one of which, you always find yourself setting a breakpoint at when you debug the program you've been working on for the last three years. You could then drag an Ada_item from this window and drop it on the Breakpoints window to set the breakpoint.

You could also drag breakpoints from the Breakpoints window and drop them on an object list window to retain them for later use. Breakpoint objects are line based. Ada_items are name based and thus more immune to editing changes in the source.

Modifier use in Drag-and-Drop

Given any two objects, there might be several different useful operations one would like to perform on those objects.

For example, given two views, one might want to either accept_changes between them or compare them. Given a file and a directory, one might want to copy it into the directory, move it into the directory, or create a link to it in the directory.

The way that you can specify that a drag-and-drop operation should do an alternative operation is by using a keyboard modifier when the drag is started. The three keyboard modifiers that have a special significance are Shift, Control, and Mod1 (Mod1 is usually bound to the Alt or Meta key).

Modifier use in Apex drag-and-drop is consistent with modifier use in other Apex contexts. The Shift modifier is used to indicate that you want the first alternative to the default operation (if there is one). The Mod1 modifier is used to indicate that you want the second alternative to the default operation (if there is one).

For example, for view onto view drops, the default operation is accept_changes. The first alternative is compare.

For file onto file drops, the default operation is copy onto (or accept_changes). The first alternative is show differences.

For uncontrolled file onto directory drops, the default operation is copy into. The first alternative is move into. The second alternative is to create a link to the file in the directory.

For example, suppose you have two directory windows on the screen and you want to run show differences of a file in one directory with a file in the other directory. You point the mouse cursor at the file in the first directory window. Press the Shift key. Start the drag and drop it on the line for the other file in the other directory window.

In addition to using modifiers to perform alternative operations, modifiers can also be used in drag-and-drop for queueing and showing jobs as they can with Apex menu items and dialog boxes.

Note that the modifier use in Apex drag-and-drop is not consistent with the semantics of modifiers as Motif defines them.

Dialog Boxes vs. Direct Execution

Some of the drop operations directly perform the operation implied by the source object and target site. These include the in-place operations, the button bar manipulation operations and the operations to initialize fields in dialog boxes.

In contrast, many of the object to object drop operations raise a dialog box filled in with the source and target arguments. For operations which destructively change objects having this last chance to prevent an accidental drop operation is of extreme value. For consistency sake, some operations which aren't destructive also raise a dialog, such as show differences or view compare.

To have any of these dialog commands directly execute, there are two things one can do.

There are two ways to change the default for an operation to not raise a dialog box


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