Using List View Controls

About list view

A list view control is a window that displays a collection of items, each item consisting of a label. List view controls provide several ways of arranging items and displaying individual items. For example, additional information about each item can be displayed in columns to the right of the label. List view controls can be shown in report mode in which case a selectable header is used. The Windows explorer in 'detail' view is one example of a list view control.

Image lists and icon views are not currently supported directly in Emergence BASIC. This functionality will be added in a future version. You can create image lists with the Windows API and the DLL comctl32.dll.

Creating the control

List view controls are created in the same manner as the standard control types, either through the dialog editor or manually with the CONTROL statement.

List view control styles

The following list view style flags can be specified in the CONTROL statement or by ticking the corresponding check box in the control properties of the dialog editor:

@LVSALIGNLEFT

Specifies that items are left-aligned in icon and small icon view.

@LVSALIGNTOP

Specifies that items are aligned with the top of the control in icon and small icon view.

@LVSAUTOARRANGE

Specifies that icons are automatically kept arranged in icon view and small icon view.

@LVSEDITLABELS

Allows item text to be edited in place. The parent window must process the LVN_ENDLABELEDIT notification message.

@LVSICON

Specifies icon view.

@LVSLIST

Specifies list view.

@LVSNOCOLUMNHEADER

Specifies that a column header is not displayed in report view. By default, columns have headers in report view.

@LVSNOLABELWRAP

Displays item text on a single line in icon view. By default, item text can wrap in icon view.

@LVSNOSCROLL

Disables scrolling. All items must be within the client area.

@LVSNOSORTHEADER

Specifies that column headers do not work like buttons. This style is useful if clicking a column header in report view does not carry out an action, such as sorting.

@LVSREPORT

Specifies report view.

@LVSSHOWSELALWAYS

Always show the selection, if any, even if the control does not have the focus.

@LVSSINGLESEL

Allows only one item at a time to be selected. By default, multiple items can be selected.

@LVSSMALLICON

Specifies small icon view.

@LVSSORTASCENDING

Sorts items based on item text in ascending order.

@LVSSORTDESCENDING

Sorts items based on item text in descending order.

In addition to the list view styles, the following window styles can also be specified:

@TABSTOP

Moves the input focus between controls if controls are in a dialog. This style has no effect for controls created in a window.

@GROUP

Specifies the first control of a group of controls in which the user can move from one control to the next with the arrow keys. All controls defined without the @GROUP style  after the first control belong to the same group. The next control with the @GROUP style starts the next group (that is, one group ends where the next begins)

@HSCROLL

The control has a horizontal scroll bar

@VSCROLL

The control has a vertical scrollbar

Controlling the list view control.

The list view control is accessed through the CONTROLCMD statement/function. CONTROLCMD can be used as a statement or function depending on the command issued.

Statements and Functions

CONTROLCMD window | dialog, ID, @LVDELETEALL

Use this statement to delete all items in the list view control

CONTROLCMD window | dialog, ID, @LVDELETECOLUMN, col

Use this statement to delete a column in the list view control.

col is the zero-based index of the column to delete.

CONTROLCMD window | dialog, ID, @LVDELETEITEM, position

Use this statement to delete a item in the list view.

position is the zero-based index of the item to delete.

CONTROLCMD window | dialog, ID, @LVINSERTITEM, position, item$

Use this statement to insert an item into the list view control.

Position is the zero-based index of the item to insert.

Item$ is the text of the item

CONTROLCMD window | dialog, ID, @LVINSERTCOLUMN, column, text$

Use this statement to insert a column into list control. The control must have been created in report view.

Column is the zero-based index of the new column

Text$ is the text of the column.

CONTROLCMD window | dialog, ID, @LVSETTEXT, item, subitem, text$

Use this statement to set the text of an item or subitem

item is the zero-based index of the item

subitem is the ones-based index of the subitem or 0 to change the item text

text$ is the new text.

CONTROLCMD( window | dialog, ID, @LVGETTEXT, item, subitem, text$, {cchText} )

Use this function to retrieve the text of an item or subitem.

item is the zero-based index of the item

subitem is the ones-based index of the subitem or 0 to retreive the item text

text$ is a variable of type STRING to store retrieved text.

cchText is an optional maximum length of text$. Defaults to 255

count = CONTROLCMD( window | dialog, ID, @LVGETSELCOUNT)

Use this function to retrieve the number of selected items

count = CONTROLCMD( window | dialog, ID, @LVGETCOUNT)

Use this function to retrieve the total number of items in the list view control

CONTROLCMD window | dialog, ID, @LVSETCOLUMNTEXT, column, text$

Use this statement to change the text of a column in report view.

column is the zero-based index of the column to change.

text$ is the new column text

CONTROLCMD( window | dialog, ID, @LVGETCOLUMNTEXT, column, text$ {,cchText} )

Use this function to retrieve the text of a column.

column is the zero-based index of the column to retrieve

text$ is a variable of type STRING to store retrieved text.

cchText is an optional maximum length of text$. Defaults to 255.

CONTROLCMD window | dialog, ID, @LVSETCOLWIDTH, column, width

Use this function to set a columns width

column is the zero-based index of the column to change.

width is the new width of the column in pixels

width = CONTROLCMD( window | dialog, ID, @LVGETCOLWIDTH, column)

Use this function to retreive a columns width

column is the zero-based index of the column to change.

CONTROLCMD window | dialog, ID, @LVSETSELECTED, item

selected = CONTROLCMD( window | dialog, ID, @LVGETSELECTED, item)

Use this function to determine the selected state of the item.

item is the zero-based index of the item.

position = CONTROLCMD( window | dialog, ID, @LVFINDITEM, text$)

Searches for an item. Returns the zero-based index of the item or -1 if the item could not be found.

text$ is the case sensitive string to search for.

position = CONTROLCMD( window | dialog, ID, @LVGETTOPINDEX)

Use this function to retrieve the zero-based index of the first item visible in the control

Notification messages

A list view control sends notification messages to the parent window or dialog in the @NOTIFYCODE variable. The ID of the control is found in @CONTROLID the same as standard controls. The following notification messages are supported:

@NMCLICK

User has left clicked in the control

@NMDBLCLK

User has double clicked in the control

@NMKILLFOCUS

The control has lost the input focus

@NMSETFOCUS

The control has received the input focus

@NMRCLICK

User has right clicked in the control

@LVNCOLUMNCLICK

Indicates that the user clicked a column header in report view.

@QUAL contains a memory handle to a NMLISTVIEW data type.

@LVNKEYDOWN

Signals a keyboard event

@QUAL contains a memory handle to a LVKEYDOWN data type

@LVNBEGINLABELEDIT

Signals the start of in-place label editing

@LVNENDLABELEDIT

Signals the end of label editing

@LVNITEMCHANGED

Indicates that an item has changed.

@QUAL contains a memory handle to a NMLISTVIEW data type.

@LVNITEMCHANGING

Indicates that an item is in the process of changing

@QUAL contains a memory handle to a NMLISTVIEW data type.

@LVNINSERTITEM

Signals the insertion of a new list view item.

@QUAL contains a memory handle to a NMLISTVIEW data type.

@LVNDELETEITEM

Signals the deletion of a specific item

@QUAL contains a memory handle to a NMLISTVIEW data type.

Data types

Some notification messages set @LPARAM to a UDT pointer. The following UDT's are commonly used with list view notifications.

TYPE NMLISTVIEW

  def hwndFrom:UINT

  def idFrom:INT

  def code:INT

  def iItem:INT

  def iSubItem:INT

  def uNewState:UINT

  def uOldState:UINT

  def uChanged:UINT

  def ptActionx:INT

  def ptActiony:INT

  def lParam:INT

ENDTYPE

TYPE LVKEYDOWN

  def hwndFrom:UINT

  def idFrom:INT

  def code:INT

  def vkey:WORD

  def flags: INT

ENDTYPE

Reading data types

To read the UDT pointer stored in @LPARAM use pointer dereferencing and type casting

Example fragment:

'standard NM_LISTVIEW
TYPE NMLISTVIEW
    def hwndFrom:UINT
    def idFrom:INT
    def code:INT
    def iItem:INT
    def iSubItem:INT
    def uNewState:UINT
    def uOldState:UINT
    def uChanged:UINT
    def ptActionx:INT
    def ptActiony:INT
    def lParam:INT
ENDTYPE
 
...
SUB Handler
SELECT @MESSAGE
    CASE @IDCONTROL
        IF(@NOTIFYCODE = @LVNCOLUMNCLICK)
            CONTROLCMD d1,1,@LVSETCOLUMNTEXT,*<NMLISTVIEW>@LPARAM.iSubItem,"Clicked!
        ENDIF
ENDSELECT
RETURN
ENDSUB

See the sample file listview.eba for a demonstration of reading a UDT handle from @LPARAM