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 RGB function in the 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 will process 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 listbox 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 may be selected in report view. Values are: TRUE – In report view, an entire row may be selected. FALSE – In report view, just the item in the first column may 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 may be dragged to move columns in report view: TRUE – In report view, column headers may be dragged. FALSE – In report view, dragging column headers will 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 will wrap. FALSE – Labels will 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 only be set 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 name 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 only be set 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 only be set 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 name 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 only be set 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 only be set 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 name 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 only be set 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 initiates 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 non-highlighted items are underlined. FALSE – Non-highlighted 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. Note that 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 will begin 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 will begin 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.