Managing TreeView items

An item in a TreeView is a TreeViewItem structure. The preceding
section described how to set the item’s properties in the
structure and then insert it into the TreeView.

This code declares a TreeViewItem structure and sets several
properties:

For information about Picture properties,
see “Managing TreeView pictures”.

When you insert an item, the inserting function returns a
handle to that item. The TreeViewItem structure is copied to the
TreeView control, and you no longer have access to the item’s
properties:

Procedure for items: get, change, and set

If you want to change the properties of an item in the TreeView,
you:

1. Get
   the
   item, which assigns it to a TreeViewItem structure.
2. Make the changes
   , by setting
   TreeViewItem properties.
3. Set
   the item, which copies
   it back into the TreeView.

When you work with items that have been inserted in the TreeView,
you work with item handles. Most TreeView events pass one or two
handles as arguments. The handles identify the items the user is
interacting with.

This code for the Clicked event uses the handle of the clicked
item to copy it into a TreeViewItem structure whose property values
you can change:

Important Remember to call the SetItem function after you change an
item’s property value. Otherwise, nothing happens in the
TreeView.

Items and the hierarchy

You can use item handles with the FindItem function to navigate
the TreeView and uncover its structure. The item’s properties
tell you what its level is, but not which item is its parent. The
FindItem function does:

You can use FindItem to find the children of an item or to
navigate through visible items regardless of level.

For more information, see the FindItem function
in the PowerScript Reference
.

Enabling TreeView functionality in scripts

By setting TreeView properties, you can enable or disable
user actions like deleting or renaming items without writing any
scripts. You can also enable these actions by calling functions.
You can:

• Delete items
• Rename items
• Move items via drag and drop
• Sort items

Deleting items

To allow the user to delete items, enable the TreeView’s
DeleteItems property. When the user presses the delete key,
the selected item is deleted and the DeleteItem event is triggered.
Any children are deleted too.

If you want more control over deleting, such as allowing deleting
of detail items only, you can call the DeleteItem function instead
of setting the property. The function also triggers the DeleteItem
event.

Example

This script is for a TreeView user event. Its event ID is
pbm_keydown and is triggered by key presses when the TreeView
has focus. The script checks whether the delete key
is pressed and whether the selected item is at the detail level.
If both are TRUE, it deletes it.

The value of the TreeView’s DeleteItems property
is FALSE. Otherwise, the user could delete any item, despite this
code:

Renaming items

If you enable the TreeView’s EditLabels property,
the user can edit an item label by clicking twice on the text.

Events

There are two events associated with editing labels.

The BeginLabelEdit event occurs after the second click when
the EditLabels property is set or when the EditLabel function is
called. You can disallow editing with a return value of 1.

This script for BeginLabelEdit prevents changes to labels
of level 2 items:

The EndLabelEdit event occurs when the user finishes editing
by pressing enter, clicking on another item,
or clicking in the text entry area of another control. A script
you write for the EndLabelEdit event might validate the user’s changes–for
example, it could invoke a spelling checker.

EditLabel function

For control over label editing, the BeginLabelEdit event can
prohibit editing of a label, as shown above. Or you can set the
EditLabels property to FALSE and call the EditLabel function when
you want to allow a label to be edited.

When you call the EditLabel function, the BeginLabelEdit event
occurs when editing begins and the EndLabelEdit event occurs when
the user presses enter or the user clicks another item.

This code for a CommandButton puts the current item into editing

mode:

Moving items via drag and drop

At the window level, PowerBuilder provides functions and properties
for dragging controls onto other controls. Within the TreeView,
you can also let the user drag items onto other items. Users might
drag items to sort them, move them to another branch, or put child
items under a parent.

When you implement drag and drop as a way to move items, you
decide whether the dragged item becomes a sibling or child of the
target, whether the dragged item is moved or copied, and whether
its children get moved with it.

There are several properties and events that you need to coordinate
to implement drag and drop for items:

Property or event	Setting or purpose
DragAuto property	TRUE or FALSE. If FALSE, you must call the Drag function in the BeginDrag event
DisableDragDrop property	FALSE
DragIcon property	An appropriate icon or None!, which means the user drags an image of the item
BeginDrag event	Script for saving the handle of the dragged item and optionally preventing particular items from being dragged
DragWithin event	Script for highlighting drop targets
DragDrop event	Script for implementing the result of the drag operation

Example

The key to a successful drag-and-drop implementation is in
the details. This section illustrates one way of moving items. In
the example, the dragged item becomes a sibling of the drop target,
inserted after it. All children of the item are moved with it and
the original item is deleted.

A function called recursively moves the children, regardless
of the number of levels. To prevent an endless loop, an item cannot
become a child of itself. This means a drop target that is a child
of the dragged item is not allowed.

BeginDrag event The script saves the handle of the dragged item in an instance
variable:

If you want to prevent some items from being dragged–such
as items at a particular level–that code goes here too:

DragWithin event The script highlights the item under the cursor so the user can
see each potential drop target. If only some items are drop targets,
your script should check an item’s characteristics before
highlighting it. In this example, you could check whether an item
is a parent of the dragged item and highlight it only if it is not:

DragDrop event This script does all the work. It checks whether the item
can be inserted at the selected location and inserts the dragged
item in its new position–a sibling after the drop target.
Then it calls a function that moves the children of the dragged
item too:

The DragDrop event script shown above calls the function uf_movechildren. The
function calls itself recursively so that all the levels of children
below the dragged item are moved:

Sorting items

A TreeView can sort items automatically, or you can control
sorting manually. Manual sorting can be alphabetic by label text,
or you can implement a user-defined sort to define your own criteria.
The SortType property controls the way items are sorted. Its values
are of the enumerated data type grSortType.

Automatic alphabetic sorting To enable sorting by the text label, set the SortType property
to Ascending! or Descending!. Inserted items are sorted automatically.

Manual alphabetic sorting For more control over sorting, you can set SortType to Unsorted!
and sort by calling functions:

Use this function	To do this
InsertItemSort	Insert an item at the correct alphabetic position if possible
Sort	Sort the immediate children of an item
SortAll	Sort the whole branch below an item

If users will drag items to organize the list, you should
disable sorting.

Sorting by other criteria To sort items by criteria other than their labels, implement
a user-defined sort by setting the SortType property to UserDefinedSort!
and writing a script for the Sort event. The script specifies how
to sort items.

PowerBuilder triggers the Sort event for each pair of items
it tries to reorder. The Sort script returns a value reporting which
item is greater than the other. The script can have different rules
for sorting based on the type of item. For example, level 2 items
can be sorted differently from level 3. The TreeView is sorted whenever
you insert an item.

Example of Sort event

This sample script for the Sort event sorts the first level
by the value of the Data property and other levels alphabetically
by their labels. The first level displays composers chronologically,
and the Data property contains an integer identifying a composer’s
century:

---