Using ListView controls

A ListView control allows you to display
items and icons in a variety of arrangements. You can display large
icon or small icon freeform lists, or you can display a vertical
static list. You can also display additional information about each
list item by associating additional columns with each list item:

ListView controls consist of ListView items,
which are stored in an array. Each ListView item consists of a:

• Label The name of the ListView item
• Index The position of the ListView item in the control
• Picture index The number that associates the ListView item with an image
  Depending on the style of the presentation, an item could
  be associated with a large picture index and a small picture index.
• Overlay picture index The number that associates the ListView item with an overlay
  picture.
• State picture index The number that associates the ListView item with a state
  picture.

For more information about ListView items,
picture indexes, and presentation style, see the PowerBuilder User’s
Guide
.

Creating ListView controls

You add ListView controls to windows in the same way you add
other controls: select ListView from the Insert>Control
menu and click the window.

Adding ListView items

In the painter Use the Items property page for the control to add items.

To add items to a ListView:

1. Select the Items tab in the Properties
   view for the control.

2. Enter a name and a picture index number for each
   of the items you want to add to the ListView.

   For more information about adding pictures
   to a ListView control, see “Adding pictures to ListView
   controls”.

In a script Use the AddItem and InsertItem functions to add items to a ListView
dynamically at execution time. There are two levels
of information you supply when you add items to a ListView using
AddItem or InsertItem.

You can add an item by supplying the picture index and label,
as this example shows:

or you can insert an item by supplying the item’s
position in the ListView, label, and picture index:

You can add items by supplying the ListView item itself. This
example in the ListView’s DragDrop event inserts the dragged
object into the ListView:

or you can insert an item by supplying the ListView position
and ListView item:

Adding pictures to ListView
controls

PowerBuilder stores ListView images in four image lists:

• Small picture index
• Large picture index
• State picture index
• Overlay picture index

You can associate a ListView item with these images when you
create a ListView in the painter or use the AddItem and InsertItem
at execution time.

However, before you can use associate pictures with ListView
items, they must be added to the ListView control.

In the painter Use the Pictures and Items property pages for the control
to add pictures.

To add pictures to a ListView control:

1. Select the Large Picture, Small Picture,
   or State tab in the Properties view for the control.

   Overlay images You can only add overlay images to a ListView control in a
   script.

2. Select an image from the stock image list.

   or

   Use the Browse button to select a bitmap, cursor, or
   icon image.

3. Select a color from the PictureMaskColor dropdown
   menu for the image.

   The color selected for the picture mask will appear transparent
   in the ListView.

4. Select a picture height and width for your image.

   This will control the size of the image in the ListView.

   Dynamically changing image size The image size can be changed at execution time by setting
   the PictureHeight and PictureWidth properties before you add any
   pictures when you create a ListView.

   For more information about PictureHeight and
   PictureWidth, see the PowerScript Reference.

5. Repeat the procedure for the:
   • Number of image types
     (large, small, and state) you plan to use in your ListView
   • Number of images for each type you plan to use in
     your ListView

In a script Use the following functions to add pictures to a ListView
image:

Function	Adds a picture to this list
AddLargePicture	Large image
AddSmallPicture	Small image
AddStatePicture	State image

Adding large and small pictures This example sets the height and width for large and small
pictures and adds three images to the large picture image list and
the small picture image list:

Adding overlay pictures Use the SetOverLayPicture function to use a large picture
or small picture as an overlay for an item.

This example adds a large picture to a ListView, and then
uses it for an overlay picture for a ListView item:

Adding state pictures This example uses an item’s state picture index property
to set the state picture for the selected ListView item:

Deleting ListView items and pictures

You can delete items from a ListView one at a time with the
DeleteItem function, or you can use the DeleteItems function to
purge all the items in a ListView. Similarly, you can delete pictures
one at a time with the DeleteLargePicture, DeleteSmallPicture, and
DeleteStatePicture functions, or purge all pictures of a specific
type by using the DeleteLargePictures, DeleteSmallPictures, and
DeleteStatePictures functions.

This example deletes one item and all the small pictures from
a ListView:

Using report view

ListView report view requires more information than the large
icon, small icon, and list view. To enable report view in a ListView
control you must write a script that establishes columns with the
AddColumn and SetColumn functions, and then populate the columns
using the SetItem function.

Populating columns

Use AddColumn to create columns in a ListView. When you use
the AddColumn function, you specify the:

• Column
  label The name that will display in the column header
• Column alignment Whether the text will be left-aligned, right-aligned, or
  centered
• Column size The width of the column in PowerBuilder units

This example creates three columns in a ListView:

Setting columns

Use SetColumn to set the column number, name, alignment, and
size:)

Setting column items

Use SetItem to populate the columns of a ListView:

For more information about adding columns
to a ListView control, see the PowerScript Reference
.

Hot tracking and one- or two-click activation

Hot tracking changes the appearance of items in the Listview
control as the mouse moves over them and, if the mouse pauses, selects
the item under the cursor automatically. You can enable hot tracking
by setting the TrackSelect property to TRUE.

Setting either OneClickActivate or TwoClickActivate to TRUE
also enables hot tracking. When OneClickActivate is TRUE, you can
specify that either selected or unselected items are underlined
by setting the UnderlineHot or UnderlineCold properties. All these
properties can be set on the control’s general properties
page or in a script.

The settings for OneClickActivate and TwoClickActivate affect
when the ItemActivate event is fired:

OneClickActivate	TwoClickActivate	ItemActivate is fired when you
TRUE	TRUE or FALSE	Click any item
FALSE	TRUE	Click a selected item
FALSE	FALSE	Double-click any item

---