HomePowerBuilderAppeon Documentation Center

ListView control

A ListView displays list information to the user. Each item of the ListView consists of text and pictures, which can be manipulated during application runtime.

Properties

ListView property

Datatype

Description

Accelerator

Integer

Specifies the ASCII value of the accelerator key assigned for the control.

AccessibleDescription

String

A description of the control and/or its purpose for use by accessibility tools such as readers for visually impaired users.

AccessibleName

String

A label that briefly describes the control, such as the text in a button or the name of a menu item.

AccessibleRole

AccessibleRole (enumerated)

Describes what kind of user interface element the control is.

AutoArrange

Boolean

Specifies whether PowerBuilder arranges icons automatically in large and small icon views.

BackColor

Long

Specifies the numeric value of the background color: -2 to 16,777,215. For more information about color, see the section called “RGB” in PowerScript Reference.

Border

Boolean

Specifies whether the control has a border. Values are:

TRUE -- Control has a border.

FALSE -- Control does not have a border.

BorderStyle

BorderStyle (enumerated)

Specifies the border style of the control. Values are:

StyleBox!

StyleLowered!

StyleRaised!

StyleShadowBox!

BringToTop

Boolean

Specifies whether PowerBuilder moves the control to the top of the front-to-back order.

ButtonHeader

Boolean

Specifies whether the column titles in report view appear as buttons.

CheckBoxes

Boolean

Specifies whether the state images are replaced by check boxes. The check boxes are set to unchecked by default. The ListView control processes mouse and keyboard input to toggle the checked state. Values are:

  • TRUE -- Check boxes are displayed.

  • FALSE -- Check boxes are not displayed.

The state of an item's check box can be determined by checking the state picture index for the item:

Unchecked = 1

Checked = 2

ClassDefinition

PowerObject

An object of type PowerObject containing information about the class definition of the object or control.

DeleteItems

Boolean

Specifies whether the user can delete a ListView item from a ListView control by pressing Delete.

DragAuto

Boolean

Specifies whether PowerBuilder puts the control automatically into Drag mode. Values are:

TRUE -- When the control is clicked, the control is automatically in Drag mode.

FALSE -- When the control is clicked, the control is not automatically in Drag mode. You have to manually put the control into Drag mode by using the Drag function.

DragIcon

String

Specifies the name of the stock icon or the file containing the icon you want to display when the user drags the control (the ICO file). The default icon is a box the size of the control.

When the user drags the control, the icon displays when the control is over an area in which the control can be dropped (a valid drop area). When the control is over an area that is not a valid drop area, the No-Drop icon displays.

EditLabels

Boolean

Specifies whether the user can edit the labels in a control by clicking on a selected item. Note that the item must be selected first, by clicking on it.

Enabled

Boolean

Specifies whether the control is enabled (can be clicked). Values are:

TRUE -- Control can be clicked.

FALSE -- Control cannot be clicked.

ExtendedSelect

Boolean

Specifies whether users can select multiple items in the list box at one time. Values are:

TRUE -- Users can select multiple items by selecting outside all items and dragging to create a rectangle enclosing the desired items; by using Click or Shift+ Click to select a sequential group of items; or by using Ctrl+ Click on multiple items.

FALSE -- Users cannot select multiple items.

FaceName

String

Specifies the name of the typeface in which the text of the control displays (for example, Arial or Courier).

FixedLocations

Boolean

Specifies whether the user cannot drag items to new positions in a control.

FontCharSet

FontCharSet (enumerated)

Specifies the font character set used for the text in the control. The application must be running on an appropriate version of PowerBuilder under an operating system that supports the selected character set. For a complete list of possible values, see the list of properties for the FontCharSet variable on the Enumerated tab page of the Browser.

FontFamily

FontFamily (enumerated)

Specifies the font family (type style) used for the text in the control. Values are:

AnyFont!

Decorative!

Modern!

Roman!

Script!

Swiss!

FontPitch

FontPitch (enumerated)

Specifies the font pitch used for the text in the control. Values are:

Default!

Fixed!

Variable!

FullRowSelect

Boolean

Specifies whether an entire row can be selected in report view. Values are:

  • TRUE -- In report view, an entire row can be selected.

  • FALSE -- In report view, just the item in the first column can be selected.

GridLines

Boolean

Specifies whether the report view displays gridlines:

  • TRUE -- In report view, gridlines are displayed.

  • FALSE -- In report view, gridlines are not displayed.

HeaderDragDrop

Boolean

Specifies whether column headers can be dragged to move columns in report view:

  • TRUE -- In report view, column headers can be dragged.

  • FALSE -- In report view, dragging column headers does not move the columns.

Height

Integer

Specifies the height of the control, in PowerBuilder units.

HideSelection

Boolean

Specifies whether selected text stays selected (highlighted) even when the control does not have focus. Values are:

TRUE -- Text does not stay highlighted.

FALSE -- Text stays highlighted.

ImeMode

Integer

Specifies the input method editor mode. This property is relevant only to applications running on a Japanese version of PowerBuilder.

Italic

Boolean

Specifies whether the text in the control is italic. Values are:

TRUE -- Text is italic.

FALSE -- Text is not italic.

Item[ ]

String

Specifies the items in the control. Not updated after initialization.

ItemPictureIndex[ ]

Integer

Identifies the picture associated with the item. The picture index itself is associated with a specific icon, bitmap, or cursor. Not updated after initialization.

LabelWrap

Boolean

Specifies whether long labels wrap under the ListView item in a large icon view. Values are:

TRUE -- Labels wrap.

FALSE -- Labels do not wrap.

LabelWrap does not apply to list, report, or small icon views.

LargePictureHeight

Integer

Specifies the size, in pixels, for the height of the picture used in the large icon view.

In a script, this value can be set only before a large picture has been added to the large picture index list.

If the large picture height is 0, PowerBuilder uses the height of the first picture added to the large picture index.

LargePictureMaskColor

Long

Specifies the color to be transparent when used in a large icon view. This color is used when the picture is added at initialization or with the function AddLargePicture.

LargePictureName[ ]

String

Specifies the file path or URL address of the picture used in large icon view. The picture can be an icon, cursor, or bitmap supplied by the user or a stock picture from the PowerBuilder library. Not updated after initialization.

LargePictureWidth

Integer

Specifies the size, in pixels, for the width of the picture used in the large icon view.

In a script, this value can be set only before a large picture has been added to the large picture index list.

If the large picture width is 0, PowerBuilder uses the width of the first picture added to the large picture index.

LayoutRTL

Boolean

Specifies that the layout of the control should be a mirror image of the standard layout. Values are:

TRUE -- Elements in the control are right justified.

FALSE -- Elements in the control are left justified (default).

OneClickActivate

Boolean

Specifies whether one click initiates the ItemActivate event:

  • TRUE -- One click fires the ItemActivate event, causes the item to change color as the mouse moves over it (hot tracking), and causes the mouse to change to a hand cursor when it is over the item.

  • FALSE -- The item does not turn color as the mouse moves over it (assuming that TrackSelect = false) and the mouse does not change to a hand cursor when it is over the item (assuming that TwoClickActivate = false).

However, the ItemActivate event is always initiated when an item is double-clicked, even though OneClickActivate = false and TwoClickActivate = false.

Pointer

String

Specifies the name of the stock pointer or the file containing the pointer used for the control.

RightToLeft

Boolean

Specifies that characters should be displayed in right-to-left order. The application must be running on an operating system that supports right-to-left display. Values are:

TRUE -- Characters display in right-to-left order.

FALSE -- Characters display in left-to-right order (default).

Scrolling

Boolean

Specifies whether the user can scroll vertically when not all of the items in a control are visible. Values are:

TRUE -- Scrolling is enabled.

FALSE -- Scrolling is disabled.

ShowHeader

Boolean

Specifies whether column titles appear in a report view. Values are:

TRUE -- Titles appear in a report view.

FALSE -- Titles do not appear in a report view.

SmallPictureHeight

Integer

Specifies the size, in pixels, for the height of the picture used in the small icon view.

In a script, this value can be set only before a small picture has been added to the small picture index list.

If the small picture height is 0, PowerBuilder uses the height of the first picture added to the small picture index.

SmallPictureMaskColor

Long

Specifies the color to be transparent when used in a small icon view. Used when the picture is added at initialization or with the function AddSmallPicture.

SmallPictureName[ ]

String

Specifies the file path or URL address of the picture used in small icon view. The picture can be an icon, cursor, or bitmap supplied by the user or a stock picture from the PowerBuilder library. Not updated after initialization.

SmallPictureWidth

Integer

Specifies the size, in pixels, for the width of the picture used in the small icon view.

In a script, this value can be set only before a small picture has been added to the small picture index list.

If the small picture width is 0, PowerBuilder uses the width of the first picture added to the small picture index.

SortType

grSortType

Specifies whether items are sorted alphabetically based on the item label. Values are:

Ascending!

Descending!

UserDefinedSort!

Unsorted!

StatePictureHeight

Integer

Specifies the size, in pixels, for the height of the state picture.

In a script, this value can be set only before a state picture has been added to the state picture index list.

If the state picture height is 0, PowerBuilder uses the height of the first picture added to the state picture index list.

StatePictureMaskColor

Long

Specifies the color to be transparent when used in a state picture. Used when the picture is added at initialization or with the function AddStatePicture.

StatePictureName[ ]

String

Specifies the file path or URL address of the picture used as the state picture. The picture can be an icon, cursor, or bitmap supplied by the user or a stock picture from the PowerBuilder library. Not updated after initialization.

StatePictureWidth

Integer

Specifies the size, in pixels, for the width of the state picture.

In a script, this value can be set only before a state picture has been added to the state picture index list.

If the state picture width is 0, PowerBuilder uses the width of the first picture added to the state picture index list.

TabOrder

Integer

Specifies the tab value of the control within the window (0 means the user cannot tab to the control).

Tag

String

Specifies the tag value assigned to the control.

TextColor

Long

Specifies the numeric value of the color used for text: -2 to 16,777,215.

TextSize

Integer

Specifies the size of the text in the control, in points.

For backward compatibility, the size is stored as a negative number; for example, 10-point text size is stored as -10.

TrackSelect

Boolean

Specifies whether items appear in a different color when the mouse moves over them (hot tracking) and whether an item is selected if the mouse pauses over it. Values are:

TRUE -- An item changes color when the mouse moves over it, and an item is selected if the mouse pauses over it.

FALSE -- An item does not change color nor is it selected when the mouse moves over or pauses on it.

TwoClickActivate

Boolean

Specifies whether two clicks initiate the ItemActivate event:

TRUE -- Clicking twice (one click to select the item, one click to activate) fires the ItemActivate event, causes the item to change color as the mouse moves over it (hot tracking), and causes the mouse to change to a hand cursor when it is over the item.

FALSE -- The item does not turn color as the mouse moves over it (assuming that TrackSelect = false) and the mouse does not change to a hand cursor when it is over the item (assuming that OneClickActivate = false).

However, the ItemActivate event is always initiated when an item is double-clicked, even though TwoClickActivate = false.

Underline

Boolean

Specifies whether the text in the control is underlined. Values are:

TRUE -- Text is underlined.

FALSE -- Text is not underlined.

UnderlineCold

Boolean

When the OneClickActivate property is true, this property specifies whether hot tracking (color of items changes when mouse moves over them) is turned on and items not highlighted are underlined.

TRUE -- Hot tracking is turned on and nonhighlighted items are underlined.

FALSE -- Nonhighlighted items are not underlined.

UnderlineHot

Boolean

When either the OneClickActivate or TwoClickActivate property is true, this property specifies whether hot tracking (color of items changes when mouse moves over them) is turned on and items that are highlighted are underlined.

TRUE -- Hot tracking is turned on and highlighted items are underlined.

FALSE -- Highlighted items are not underlined.

View

ListViewView

Specifies the layout of the ListBox. Valid values are:

ListViewLargeIcon! -- Items are arranged from left to right. Uses large pictures.

ListViewSmallIcon! -- Items are arranged from left to right. Uses small pictures.

ListViewList! -- Items are arranged from top to bottom. Uses small pictures.

ListViewReport! -- Items are arranged from top to bottom. Uses small pictures. Additional columns of information can be associated with each item. At least one column must be created to view data in this view.

Visible

Boolean

Specifies whether the control is visible. Values are:

TRUE -- Control is visible.

FALSE -- Control is not visible.

Weight

Integer

Specifies the stroke weight of the text in the control; for example, 400 for normal or 700 for bold.

Width

Integer

Specifies the width of the control, in PowerBuilder units.

X

Integer

Specifies the X position (the distance from the left edge of the window), in PowerBuilder units.

Y

Integer

Specifies the Y position (the distance from the top of the window), in PowerBuilder units.


Events

ListView event

Occurs

BeginDrag

When the user begins a drag operation with the left mouse button. If the DragAuto property is set to true, the drag begins automatically. If the DragAuto property is set to false, the drag operation must be done programmatically.

BeginLabelEdit

When the user starts to edit a ListView item label. Return 1 to prevent setting to the new text. Return 0 to accept the new text.

BeginRightDrag

When the user begins a drag operation with the right mouse button. If the DragAuto property is set to true, the drag begins automatically. If the DragAuto property is set to false, the drag operation must be done programmatically.

Clicked

When the control is clicked.

ColumnClick

When the column is clicked

Constructor

When the object is created, immediately before the Open event occurs in the window.

DeleteAllItems

When all items in a ListView are deleted.

DeleteItem

When a ListView item is deleted.

Destructor

When the object is destroyed, immediately after the Close event occurs in the window.

DoubleClicked

When the control is double-clicked.

DragDrop

When a dragged control is dropped on the ListView control.

DragEnter

When a dragged control enters the control, including entering the narrow border around the display area.

DragLeave

When a dragged control leaves the control, including leaving by crossing into the tab page display area.

DragWithin

When a dragged control is within the control but not on a ListView item.

EndLabelEdit

When the user finishes editing a ListView item label. Return 1 to prevent setting to the new text. Return 0 to accept the new text.

GetFocus

Just before the control receives focus (before it is selected and becomes active).

Help

When the user presses the F1 key or drags the context help button (question mark) from the title bar to a menu item or control.

InsertItem

When an item is being inserted.

ItemActivate

When an item is double-clicked, or when the item is single-clicked if the property OneClickActivate = true, or when the item is clicked twice if the property TwoClickActivate = true.

ItemChanged

When an item has changed.

ItemChanging

When an item is changing. Return 1 to prevent the change, or 0 to accept the change.

Key

When the user presses a key.

LoseFocus

When the control loses focus (becomes inactive).

Other

When a Windows message occurs that is not a PowerBuilder event.

RightClicked

When the control is right-clicked.

RightDoubleClicked

When the control is right-double-clicked.

Sort

When two items are compared.

Return codes:

1 -- if item 1 > item 2.

0 -- if item 1 = item 2.

-1 -- if item 1 < item 2.


Functions

ListView function

Datatype returned

Description

AddColumn

Integer

Adds a column to a ListView control report view.

AddItem

Integer

Adds an item to a ListView control.

AddLargePicture

Integer

Adds an icon, cursor, or bitmap to the large image list.

AddSmallPicture

Integer

Adds an icon, cursor, or bitmap to the small image list.

AddStatePicture

Integer

Adds an icon, cursor, or bitmap to the state image list.

Arrange

Integer

Arranges the items in a ListView control large or small icon view.

ClassName

String

Returns the name of the control.

DeleteColumn

Integer

Deletes a column from a ListView control.

DeleteColumns

Integer

Deletes all columns from a ListView control.

DeleteItem

Integer

Deletes an item from a ListView control.

DeleteItems

Integer

Deletes all items from a ListView control.

DeleteLargePicture

Integer

Deletes a specified icon, cursor, or bitmap from the large image list.

DeleteLargePictures

Integer

Deletes all icons, cursors, and bitmaps from the large image list.

DeleteSmallPicture

Integer

Deletes a specified icon, cursor, or bitmap from the small image list.

DeleteSmallPictures

Integer

Deletes all icons, cursors, and bitmaps from the small image list.

DeleteStatePicture

Integer

Deletes a specified icon, cursor, or bitmap from the state image list.

DeleteStatePictures

Integer

Deletes all icons, cursors, and bitmaps from the large state list.

Drag

Integer

Starts or ends the dragging of a ListView item.

EditLabel

Integer

Starts editing a specific ListView item label.

FindItem

Integer

Searches for the next item that satisfies the specified search criteria.

GetColumn

Integer

Syntax 1: Does not apply to a ListView control.

Syntax 2: Returns the properties of a specified column in a ListView control report view.

GetContextService

Integer

Creates a reference to a context-specific instance of the specified service.

GetItem

Integer

Retrieves information for a specified item.

GetOrigin

Integer

Finds the X and Y coordinates of the upper-left corner of the ListView item.

GetParent

PowerObject

Returns a reference to the name of the parent object.

Hide

Integer

Hides the specified ListView item.

InsertColumn

Integer

Inserts a column into a ListView control report view.

InsertItem

Integer

Inserts an item into a ListView control.

Move

Integer

Moves a control or object to a specified location.

PointerX

Integer

Determines the distance from the left edge of an object to the pointer location.

PointerY

Integer

Determines the distance from the top edge of an object to the pointer location.

PostEvent

Boolean

Adds the event to the end of the event queue of an object.

Print

Integer

Includes this object in a print job. Only the part visible on the screen is printed.

Resize

Integer

Resizes a control to the specified dimensions.

SelectedIndex

Integer

Returns the number of the selected item in a ListView control.

SetColumn

Integer

Syntax 1: Does not apply to a ListView control.

Syntax 2: Sets the properties of a particular column in a ListView control report view.

SetFocus

Integer

Sets focus for a specified object or control.

SetItem

Integer

Sets the values for a given ListView item.

SetOverlayPicture

Integer

Maps a picture index to an overlay picture index. Only four overlay picture indexes are available.

SetPosition

Integer

Sets the position of the ListView control in the front-to-back order within a window.

SetRedraw

Integer

Controls the automatic redraw of an object after its properties have changed.

Show

Integer

Makes an object or control visible if it is hidden. If the object is already visible, Show brings it to the top.

Sort

Integer

Sorts the items in a ListView control.

TotalColumns

Integer

Returns the number of columns in a ListView control report view.

TotalItems

Integer

Returns the number of items in a ListView control.

TotalSelected

Integer

Returns the number of selected items in a ListView control.

TriggerEvent

Integer

Triggers a specified event in the control and executes the script for the event.

TypeOf

Object

Returns the type of the control.

Prev  Up  Next
ListBox control  Home  ListViewItem object