UNIFACE 8.1.01 GUI enhancements

[back to index]

Contents

What is

Drag & Drop
Drag & drop in the tree widget
Drag & drop of multiple objects
Extended trigger
Format

How to

Change drag & drop widget properties dynamically
Define a format
Define a glyph as cursor for drag & drop
Define a popup menu for drag & drop
Define the default action for drag & drop
Make an editable tree widget
Update a tree widget without collapsing nodes

What is: Drag & Drop

A visible object (drag source) can be dragged and dropped on another visible object (drop target).
Visible objects which support Drag & Drop are picture widgets and items in a tree widget.

In order to be dragged, a drag source must have one or more supported drag formats. This can be done at development time using the "Drag & drop properties" form or at runtime by modifying the widget property DRAGFORMAT.

In order to be dropped upon, a drop target must have one or more accepted drop formats. This can be done at development time using the "Drag & drop properties" form or at runtime by modifying the widget property DROPFORMAT.
When a user drags an object over a valid drop target, it is checked in which format dropping will take place, as follows: The list of formats specified for the drop target is enumerated. The first format which is also defined for the dragged object will be the format in which the object will be dropped. If no matching format is found, no dropping is allowed.
The glyph for the matching format will be shown together with the mouse pointer.

When the user releases the mouse button over a valid drop target, a drop occurs.
The default and other possible actions to take place on a drop (Move, Copy or Create Shortcut) and contents of the drop popup menu can be specified by setting the DROPACTIONS property of the drop target. This is done by checking the checkbox "Use Field Actions for all Drop Formats" in the "Drag & drop properties" form.
If no DROPACTIONS is specified for the drop target, the popup menu defined for the matching format determines the drop actions and the popup menu.
The drop action can be modified using the Ctrl and Shift keys as is standard on Windows (Shift=Move, Ctrl=Copy, Shift+Ctrl=Create Shortcut), or from the popup menu when the user drags with the right mouse button depressed.
Depending on the selected drop action, the widget calls one or more extended triggers (see Extended triggers for Drag & Drop).
In the Proc code for the extended triggers the appropriate actions should be taken to move or copy the indicated items.

Also see:
What is Format
What is Extended trigger
How to Change drag & drop widget properties dynamically
Reference - Extended triggers for drag & drop

What is: Drag & drop in the tree widget

The tree widget itself does not perform any moving about of items as a result of drag & drop, it merely informs the 4GL (by means of extended triggers) what actions are performed on the GUI.
In the tree widget all extended triggers for drag & drop are relevant, especially MoveWithin.

Usually a tree widget is a representation of some data structure which is stored somewhere else, possibly in an entity on the same form. The extended triggers can be used to modify this data structure (removing, modifying or adding occurrences) and then generating a new valrep for the tree widget.

It is probably easier to use drag & drop with a parent-child tree than with a level tree: an action MoveWithin would in that case mean that the field "parent" of the moved child would have to updated.

Also see:
How to Updating a tree widget without collapsing nodes

What is: Drag & drop of multiple objects

Dragging multiple objects is only possible from the listview part of a tree widget, and only if multiple-select is enabled in the listview (e.g. if the datatype is Special String).

A multiple selection may consist of objects of different formats.

When a multiple selection is dragged over a drop target, format negotiation takes place for each of the dragged objects as described in What is Drag & Drop.
When one or more objects can not be dropped on the drop target (because no valid format is negotiated), a no drop cursor is shown.
When all objects can be dropped in the same format, the cursor glyph for that format is shown.
When all objects can be dropped, but not all with the same format, the cursor glyph for the format U_MULTIPLESELECT is shown.

When a drop action takes place, the relevant extended trigger(s) (e.g. CopyTo) is fired multiple times, once for each object in the multiple selection.
If the Proc in the extended trigger returns -1, that one object will not be dropped. If Proc returns -2, dropping of all objects is aborted.

What is: Extended trigger

An extended trigger is called by an OWI widget when a GUI event takes place. An extended trigger is similar to an operation, but it can not be called from Proc. It is identified by the keyword "trigger".

An example of an extended trigger is Expand in the tree widget, which is called when the user clicks on a + symbol in the tree or otherwise expands a node.

An extended trigger may have parameters, usually only "in" parameters.

The set of extended triggers is different per widget type. Most widgets do not have extended triggers.
The trigger "extended triggers" in the Component Editor is automatically filled by the widget if it has extended triggers.
The default Proc code does nothing, but contains placeholders in which the developer can enter Proc code.

Also see Reference - Extended triggers

What is: Format

A format is a global object.

Formats are used in conjunction with Drag & Drop to define the type of objects which can be dragged and dropped.

The global object contains:

• the format name
• a glyph name
• a popup menu with drag & drop actions

UNIFACE Drag & Drop recognizes two standard formats:

• TEXT
• U_MULTIPLESELECT

By default, no glyphs or popup menus have been defined for these formats.
The format TEXT can be used for drag & drop with other applications, e.g. Wordpad.
The format U_MULTIPLESELECT is used for dragging a multiple selection. You may want to define a glyph for this.

It is possible to define some sort of hierarchy of formats, using the fact that when an object is dragged over a drop target the formats is enumerated in the sequence in which they are defined as accepted drop formats in the "Drag & drop properties" form.
For example, if the accepted drop formats are:

• hammer
• tool
• metal object

and the dragged object supports the formats:

• saw
• tool
• metal object

then "hammer" will not match, but "tool" will become the matching format.
This will be shown visually if you have different glyphs defined for the different formats as soon as you drag the object over the drop target.

Also see:
How to Define a format

How to: Change drag & drop widget properties dynamically

Drag & drop is supported for the picture widget and for items in a tree widget.

On the picture widget properties form and on the "Define tree item types" form is a Drag & Drop button from which you can start the Drag & Drop properties form. This is used to set drag & drop properties at development time.

The drag & drop properties can be changed dynamically.

In the picture widget the relevant widget properties are called DRAGFORMAT, DROPFORMAT and DROPACTIONS.
In the tree widget the properties are called DRAGFORMATn, DROPFORMATn and DROPACTIONSn, where n is the index of the tree item type.

The widget properties DRAGFORMAT and DROPFORMAT both have the same syntax: "format1;format2;...;formatn" where ; indicates the UNIFACE list separator (GOLD ;).

The widget property DROPACTIONS has as syntax "<default action index>;<move string>;<copy string>;<create shortcut string>;<cancel string>" where ; indicates the UNIFACE list separator (GOLD ;).
Example: "1;Move;Copy;;Cancel" means the default action is "Move" and the action "Create shortcut" is disabled.

also see: Form help - Drag & drop properties

How to: Define a format

To define a Drag & Drop format.

Steps

1. Choose Editors -> Library -> Formats and select a library.
The "Define Format" form is displayed.

2. Define a format name and a language (you can set the default language in the General Preference form). You can define different languages for the same format name, which you can use to define the popup menu texts in multiple languages.

3. Specify which drop action is Default using the radiogroup.

4. One or more drop actions should be Enabled.

5. The Option Text may be changed, for example to indicate specific functionality (e.g. "Print" instead of "Copy") or in a different language.

6. A glyph may be defined, which will be shown as a cursor while dragging an object which can be dropped using the format.
Note that you should define a monochrome secondary glyph with white pixels at the places where you want the cursor to shine through.

How to: Define a glyph as cursor for drag & drop

See Define a format.

Note that you should define a secondary glyph with white pixels at the places where you want the cursor to shine through.

How to: Define a popup menu for drag & drop

See Define a format if you want to define the popup menu for a drop format.

See Drag & drop properties if you want to define the popup menu for a drop target.
If you define a popup menu for a drop target, it will be used regardless of the drop format.

How to: Define the default action for drag & drop

See Define a format if you want to define the default action for a drop format.

See Drag & drop properties if you want to define the default action for a drop target.
If you define the default action for a drop target, it will be used regardless of the drop format.

How to: Make an editable tree widget

If you set the tree widget property INLINEEDIT to TRUE, tree and list items become editable:

• when you click on an item twice
• when you press F2 after an item has been selected

When you edit the item's representation and then press Enter, the extended trigger representationChanged is fired.

Then, assuming the tree contains only items with type "TreeType", you can update the tree with a partial valrep update:

Example:

trigger representationChanged
params
  string itemValue: in
  string control: in ; TREE | LIST
  string newRepresentation: in
endparams
  $fieldvalrep(tree)="0=;itemValue=!;TreeType!;newRepresentation"
end ; trigger representationChanged

More probably, you will have a (dummy) entity on your form containing the tree data, in which case you can update that entity and then generate the complete tree valrep.

Also see: How to Update a tree widget without collapsing nodes

How to: Update a tree widget without collapsing nodes

To indicate an incomplete node in a tree widget, it was already possible to insert a '+' in the tree valrep (shown as a + in a square in the tree).
It is now also possible to put a '-' in the tree valrep to indicate that a node should be displayed expanded (shown as a - in a square in the tree).

Example of an expanded valrep:
"1=!;-Node!;Root;2=1!;Node!;Expanded node"

When the tree data is kept in a (dummy) entity on the same form, a field can be used to store the expand/collapse state of each node. This state can be updated using the extended triggers Collapse and Expand.