Managing TreeView pictures

PowerBuilder stores TreeView images in three image lists:

• Picture list (called
  the regular picture list
  here)
• State picture list
• Overlay picture list

You add pictures to these lists and associate them with items
in the TreeView.

Pictures for items

There are several ways to use pictures in a TreeView. You
associate a picture in one of the picture lists with an item by
setting one of the item’s picture properties:

Property	Purpose
PictureIndex	The primary picture associated with the item is displayed just to the left of the item’s label
StatePictureIndex	A state picture is displayed to the left of the regular picture. The item moves to the right to make room for the state picture. If the Checkboxes property is true, the state picture is replaced by a pair of checkboxesBecause a state picture takes up room, items without state pictures will not align with items that have pictures. So that all items have a state picture and stay aligned, you could use a blank state picture for items that do not have a state to be displayedA use for state pictures might be to display a checkmark beside items the user has chosen
OverlayPictureIndex	An overlay picture is displayed on top of an item’s regular pictureYou set up the overlay picture list in a script by designating a picture in the regular picture list for the overlay picture list An overlay picture is the same size as a regular picture, but it often uses a small portion of the image space so that it only partially covers the regular picture. A typical use of overlay pictures is the arrow marking shortcut items in the Windows Explorer
SelectedPictureIndex	A picture from the regular picture list that is displayed instead of the regular picture when the item is the current item. When the user selects another item, the first item gets its regular picture and the new item displays its selected pictureIf you do not want a different picture when an item is current, set SelectedPictureIndex to the same value as PictureIndex

How to set pictures You can change the pictures for all items at a particular level
with the SetLevelPictures function, or you can set the picture properties for
an individual item.

If you do not want pictures Your TreeView does not have to use pictures for items. If
an item’s picture indexes are 0, no pictures are displayed.
However, the TreeView always leaves room for the regular picture.
You can set the PictureWidth property to 0 to eliminate that space:

Setting up picture lists

You can add pictures to the regular and state picture lists
in the painter or during execution. During execution, you can assign
pictures in the regular picture list to the overlay list.

Mask color

The mask color is a color used in the picture that becomes
transparent when the picture is displayed. Usually you should pick
the picture’s background color so that the picture blends
with the color of the TreeView.

Before you add a picture, in the painter or in a script, you
can set the mask color to a color appropriate for that picture.
This statement sets the mask color to white, which is right for
a picture with a white background:

Each picture can have its own mask color. A picture uses the
color that is in effect when the picture is inserted. To change
a picture’s mask color, you have to delete the picture
and add it again.

Image size

In the painter you can change the image size at any time by
setting the Height and Width properties on each picture tab. All
the pictures in the list are scaled to the specified size.

During execution, you can change the image size for a picture
list only when that list is empty. The DeletePictures and DeleteStatePictures
functions let you clear the lists.

Example

This sample code illustrates how to change properties and
add pictures to the regular picture list during execution. Use similar
code for state pictures:

Deleting pictures and how it affects existing items

Deleting pictures from the picture lists can have an unintended
effect on item pictures being displayed. When you delete pictures,
the remaining pictures in the list are shifted to remove gaps in
the list. The remaining pictures get a different index value. This
means items that use these indexes get new images.

Deleting pictures from the regular picture list also affects
the overlay list, since the overlay list is not a separate list
but points to the regular pictures.

To avoid unintentional changes to item pictures, it is best
to avoid deleting pictures after you have begun using picture indexes
for items.

Using overlay pictures

The pictures in the overlay list come from the regular picture
list. First you must add pictures to the regular list, either in
the painter or during execution. Then during execution you specify
pictures for the overlay picture list. After that you can assign
an overlay picture to items, individually or with the SetLevelPictures
function.

This code adds a picture to the regular picture list and then
assigns it to the overlay list:

This code for the Clicked event turns the overlay picture
on or off each time the user clicks an item:

---