Managing TreeView pictures – PB Docs 70

Managing TreeView pictures

PowerBuilder stores TreeView images in three image lists:

  • Picture list (called
    the regular picture list
  • 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 don’t 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 don’t 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 don’t 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. You will usually 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.


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

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:

Document get from Powerbuilder help
Thank you for watching.
Was this article helpful?
Notify of
Inline Feedbacks
View all comments
Would love your thoughts, please comment.x