ListView

Table of Contents

• Introduction and Simple Example
• Options and Styles
• View Modes: Report (default), Icon, Tile, Small-Icon, and List.
• Built-in Methods:
  • Row methods (adding, modifying, and deleting rows)
  • Column methods
  • Getting data out of a ListView
  • Setting icons
• Events
• ImageLists (the means by which icons are added to a ListView)
• ListView Remarks
• Examples

Introduction and Simple Example

A List-View is one of the most elaborate controls provided by the operating system. In its most recognizable form, it displays a tabular view of rows and columns, the most common example of which is Explorer's list of files and folders (detail view).

Though it may be elaborate, a ListView's basic features are easy to use. The syntax for creating a ListView is:

LV := Gui.Add("ListView", Options, "ColumnTitle1|ColumnTitle2|...")

Here is a working script that creates and displays a ListView containing a list of files in the user's "My Documents" folder:

; Create the window.
Gui := GuiCreate()

; Create the ListView with two columns, Name and Size:
LV := Gui.Add("ListView", "r20 w700", "Name|Size (KB)")

; Notify the script whenever the user double clicks a row:
LV.OnEvent("DoubleClick", "LV_DoubleClick")

; Gather a list of file names from a folder and put them into the ListView:
Loop Files, A_MyDocuments "\*.*"
  LV.Add(, A_LoopFileName, A_LoopFileSizeKB)

LV.ModifyCol  ; Auto-size each column to fit its contents.
LV.ModifyCol(2, "Integer")  ; For sorting purposes, indicate that column 2 is an integer.

; Display the window.
Gui.Show

LV_DoubleClick(LV, RowNumber)
{
  RowText := LV.GetText(RowNumber)  ; Get the text from the row's first field.
  ToolTip("You double-clicked row number " RowNumber ". Text: '" RowText "'")
}

Options and Styles for the Options parameter

Background: Specify the word Background followed immediately by a color name (see color chart) or RGB value (the 0x prefix is optional). Examples: BackgroundSilver, BackgroundFFDD99. If this option is not present, the ListView initially defaults to the system's default background color. Specifying BackgroundDefault or -Background applies the system's default background color (usually white). For example, a ListView can be restored to the default color via LV.Opt("+BackgroundDefault").

C: Text color. Specify the letter C followed immediately by a color name (see color chart) or RGB value (the 0x prefix is optional). Examples: cRed, cFF2211, c0xFF2211, cDefault.

Checked: Provides a checkbox at the left side of each row. When adding a row, specify the word Check in its options to have the box to start off checked instead of unchecked. The user may either click the checkbox or press the spacebar to check or uncheck a row.

Count: Specify the word Count followed immediately by the total number of rows that the ListView will ultimately contain. This is not a limit: rows beyond the count can still be added. Instead, this option serves as a hint to the control that allows it to allocate memory only once rather than each time a row is added, which greatly improves row-adding performance (it may also improve sorting performance). To improve performance even more, use LV.Opt("-Redraw") prior to adding a large number of rows. Afterward, use LV.Opt("+Redraw") to re-enable redrawing (which also repaints the control).

Grid: Provides horizontal and vertical lines to visually indicate the boundaries between rows and columns.

Hdr: Specify -Hdr (minus Hdr) to omit the special top row that contains column titles. To make it visible later, use LV.Opt("+Hdr").

LV: Specify the string LV followed immediately by the number of an extended ListView style. These styles are entirely separate from generic extended styles. For example, specifying -E0x200 would remove the generic extended style WS_EX_CLIENTEDGE to eliminate the control's default border. By contrast, specifying -LV0x20 would remove LVS_EX_FULLROWSELECT.

LV0x10: Specify -LV0x10 to prevent the user from dragging column headers to the left or right to reorder them. However, it is usually not necessary to do this because the physical reordering of columns does not affect the column order seen by the script. For example, the first column will always be column 1 from the script's point of view, even if the user has physically moved it to the right of other columns.

LV0x20: Specify -LV0x20 to require that a row be clicked at its first field to select it (normally, a click on any field will select it). The advantage of this is that it makes it easier for the user to drag a rectangle around a group of rows to select them.

Multi: Specify -Multi (minus Multi) to prevent the user from selecting more than one row at a time.

NoSortHdr: Prevents the header from being clickable. It will take on a flat appearance rather than its normal button-like appearance. Unlike most other ListView styles, this one cannot be changed after the ListView is created.

NoSort: Turns off the automatic sorting that occurs when the user clicks a column header. However, the header will still behave visually like a button (unless NoSortHdr has been specified). In addition, the ColClick event is still raised, so the script can respond with a custom sort or other action.

ReadOnly: Specify -ReadOnly (minus ReadOnly) to allow editing of the text in the first column of each row. To edit a row, select it then press the F2 key. Alternatively, you can click a row once to select it, wait at least half a second, then click the same row again to edit it.

R: Rows of height (upon creation). Specify the letter R followed immediately by the number of rows for which to make room inside the control. For example, R10 would make the control 10 rows tall. If the ListView is created with a view mode other than report view, the control is sized to fit rows of icons instead of rows of text. Note: adding icons to a ListView's rows will increase the height of each row, which will make this option inaccurate.

Sort: The control is kept alphabetically sorted according to the contents of the first column.

SortDesc: Same as above except in descending order.

WantF2: Specify -WantF2 (minus WantF2) to prevent an F2 keystroke from editing the currently focused row. This setting is ignored unless -ReadOnly is also in effect.

(Unnamed numeric styles): Since styles other than the above are rarely used, they do not have names. See the ListView styles table for a list.

View Modes

A ListView has five viewing modes, of which the most common is report view (which is the default). To use one of the other views, specify its name in the options list. The view can also be changed after the control is created; for example: LV.Opt("+IconSmall").

Icon: Shows a large-icon view. In this view and all the others except Report, the text in columns other than the first is not visible. To display icons in this mode, the ListView must have a large-icon ImageList assigned to it.

Tile: Shows a large-icon view but with ergonomic differences such as displaying each item's text to the right of the icon rather than underneath it. Checkboxes do not function in this view. Also, attempting to show this view on operating systems older than Windows XP has no effect.

IconSmall: Shows a small-icon view.

List: Shows a small-icon view in list format, which displays the icons in columns. The number of columns depends on the width of the control and the width of the widest text item in it.

Report: Switches back to report view, which is the initial default. For example: LV.Opt("+Report").

Built-in Methods for ListViews

Additionally to the default methods/properties of a GUI control, the following methods can be specified for a ListView. If the associated GuiControl object does not exist or does not belongs to a ListView, the ListView methods throw an exception.

When the phrase "row number" is used on this page, it refers to a row's current position within the ListView. The top row is 1, the second row is 2, and so on. After a row is added, its row number tends to change due to sorting, deleting, and inserting of other rows. Therefore, to locate specific row(s) based on their contents, it is usually best to use LV.GetText in a loop.

Row Methods

NewRowNumber := LV.Add(Options, Col1, Col2, ...)

NewRowNumber := LV.Insert(RowNumber , Options, Col1, Col2, ...)

LV.Modify(RowNumber , Options, NewCol1, NewCol2, ...)

LV.Delete(RowNumber)

Column Methods

LV.ModifyCol(ColumnNumber, Options, ColumnTitle)

NewColumnNumber := LV.InsertCol(ColumnNumber , Options, ColumnTitle)

LV.DeleteCol(ColumnNumber)

Getting Data Out of a ListView

CountNumber := LV.GetCount(Mode)

Loop LV.GetCount
{
    RetrievedText := LV.GetText(A_Index)
    if InStr(RetrievedText, "some filter text")
        LV.Modify(A_Index, "Select")  ; Select each row whose first field contains the filter-text.
}

Gui.Opt("+LastFound")
Loop LV.GetCount("Column")
{
    ColWidth := SendMessage(4125, A_Index - 1, 0, "SysListView321")  ; 4125 is LVM_GETCOLUMNWIDTH.
    MsgBox("Column " A_Index "'s width is " ColWidth ".")
}

RowNumber := LV.GetNext(StartingRowNumber, RowType)

RowNumber := 0  ; This causes the first loop iteration to start the search at the top of the list.
Loop
{
    RowNumber := LV.GetNext(RowNumber)  ; Resume the search at the row after that found by the previous iteration.
    if not RowNumber  ; The above returned zero, so there are no more selected rows.
        break
    Text := LV.GetText(RowNumber)
    MsgBox('The next selected row is #' RowNumber ', whose first field is "' Text '".')
}

Gui.Opt("+LastFound")
ItemState := SendMessage(4140, RowNumber - 1, 0xF000, "SysListView321")  ; 4140 is LVM_GETITEMSTATE. 0xF000 is LVIS_STATEIMAGEMASK.
IsChecked := (ItemState >> 12) - 1  ; This sets IsChecked to true if RowNumber is checked or false otherwise.

RetrievedText := LV.GetText(RowNumber , ColumnNumber)

Setting Icons

PrevImageListID := LV.SetImageList(ImageListID , IconType)

Events

The following events can be detected by calling OnEvent to register a callback function or method:

Additional (rarely-used) notifications can be detected by using OnNotify. These notifications are documented at MSDN. MSDN does not show the numeric value of each notification code; those can be found in the Windows SDK or by searching the Internet.

ImageList (the means by which icons are added to a ListView)

An Image-List is a group of identically sized icons stored in memory. Upon creation, each ImageList is empty. The script calls IL_Add repeatedly to add icons to the list, and each icon is assigned a sequential number starting at 1. This is the number to which the script refers to display a particular icon in a row or column header. Here is a working example that demonstrates how to put icons into a ListView's rows:

Gui := GuiCreate()  ; Create a GUI window.
LV := Gui.Add("ListView", "h200 w180", "Icon & Number|Description")  ; Create a ListView.
ImageListID := IL_Create(10)  ; Create an ImageList to hold 10 small icons.
LV.SetImageList(ImageListID)  ; Assign the above ImageList to the current ListView.
Loop 10  ; Load the ImageList with a series of icons from the DLL.
    IL_Add(ImageListID, "shell32.dll", A_Index) 
Loop 10  ; Add rows to the ListView (for demonstration purposes, one for each icon).
    LV.Add("Icon" . A_Index, A_Index, "n/a")
LV.ModifyCol("Hdr")  ; Auto-adjust the column widths.
Gui.Show

IL_Create

Creates a new ImageList, initially empty, and returns the unique ID of the ImageList (or 0 upon failure).

UniqueID := IL_Create(InitialCount := 2, GrowCount := 5, LargeIcons := false)

InitialCount

The number of icons you expect to put into the list immediately (if omitted, it defaults to 2).

GrowCount

The number of icons by which the list will grow each time it exceeds the current list capacity (if omitted, it defaults to 5).

LargeIcons

If this parameter is true, the ImageList will contain large icons. If it is false, it will contain small icons (this is the default when omitted). Icons added to the list are scaled automatically to conform to the system's dimensions for small and large icons.

IL_Add

Adds an icon or picture to the specified ImageList, and returns the new icon's index (1 is the first icon, 2 is the second, and so on).

IconIndex := IL_Add(ImageListID, Filename , IconNumber := 1, ResizeNonIcon)

ImageListID

The ID of a ImageList created by IL_Create.

Filename

The name of an icon (.ICO), cursor (.CUR), animated cursor (.ANI) file (animated cursors will not actually be animated when displayed in a ListView), or a bitmap or icon handle like "HBITMAP:" handle. Other sources of icons include the following types of files: EXE, DLL, CPL, SCR, and other types that contain icon resources.

IconNumber

To use an icon group other than the first one in the file, specify its number for IconNumber. If IconNumber is negative, its absolute value is assumed to be the resource ID of an icon within an executable file. In the following example, the default icon from the second icon group would be used: IL_Add(ImageListID, "C:\My Application.exe", 2).

ResizeNonIcon

Non-icon images such as BMP, GIF and JPG may also be loaded. However, in this case the last two parameters should be specified to ensure correct behavior: IconNumber should be the mask/transparency color number (0xFFFFFF [the color white] might be best for most pictures); and ResizeNonIcon should be non-zero to cause the picture to be scaled to become a single icon, or zero to divide up the image into however many icons can fit into its actual width.

All operating systems support GIF, JPG, BMP, ICO, CUR, and ANI images. On Windows XP or later, additional image formats such as PNG, TIF, Exif, WMF, and EMF are supported. Operating systems older than XP can be given support by copying Microsoft's free GDI+ DLL into the AutoHotkey.exe folder (but in the case of a compiled script, copy the DLL into the script's folder). To download the DLL, search for the following phrase at www.microsoft.com: gdi redistributable

IL_Destroy

Deletes the specified ImageList, and returns 1 upon success and 0 upon failure.

Success := IL_Destroy(ImageListID)

ImageListID

The ID of a ImageList created by IL_Create.

Note: It is normally not necessary to destroy ImageLists because once attached to a ListView, they are destroyed automatically when the ListView or its parent window is destroyed. However, if the ListView shares ImageLists with other ListViews (by having 0x40 in its options), the script should explicitly destroy the ImageList after destroying all the ListViews that use it. Similarly, if the script replaces one of a ListView's old ImageLists with a new one, it should explicitly destroy the old one.

ListView Remarks

Gui.Submit has no effect on a ListView control.

After a column is sorted -- either by means of the user clicking its header or the script calling LV.ModifyCol(1, "Sort") -- any subsequently added rows will appear at the bottom of the list rather than obeying the sort order. The exception to this is the Sort and SortDesc styles, which move newly added rows into the correct positions.

To detect when the user has pressed Enter while a ListView has focus, use a default button (which can be hidden if desired). For example:

Gui.Add("Button", "Hidden Default", "OK").OnEvent("Click", "LV_Enter")
...
LV_Enter() {
  global
  if Gui.FocusedCtrl != LV
    return
  MsgBox("Enter was pressed. The focused row number is " LV.GetNext(0, "Focused"))
}

In addition to navigating from row to row with the keyboard, the user may also perform incremental search by typing the first few characters of an item in the first column. This causes the selection to jump to the nearest matching row.

Although any length of text can be stored in each field of a ListView, only the first 260 characters are displayed.

Although the maximum number of rows in a ListView is limited only by available system memory, row-adding performance can be greatly improved as described in the Count option.

A picture may be used as a background around a ListView (that is, to frame the ListView). To do this, create the picture control after the ListView and include 0x4000000 (which is WS_CLIPSIBLINGS) in the picture's Options.

A script may create more than one ListView per window.

It is best not to insert or delete columns directly with SendMessage. This is because the program maintains a collection of sorting preferences for each column, which would then get out of sync. Instead, use the built-in column methods.

To perform actions such as resizing, hiding, or changing the font of a ListView, see GuiControl object.

To extract text from external ListViews (those not owned by the script), use ControlGetList.

Related

TreeView, Other Control Types, GuiCreate, ContextMenu event, Gui object, GuiControl object, ListView styles table

Examples

; Select or de-select all rows by specifying 0 as the row number:
LV.Modify(0, "Select")   ; Select all.
LV.Modify(0, "-Select")  ; De-select all.
LV.Modify(0, "-Check")  ; Uncheck all the checkboxes.

; Auto-size all columns to fit their contents:
LV.ModifyCol  ; There are no parameters in this mode.

; MAIN EXAMPLE
; The following is a working script that is more elaborate than the one near the top of this page.
; It displays the files in a folder chosen by the user, with each file assigned the icon associated with
; its type. The user can double-click a file, or right-click one or more files to display a context menu.

; Create a GUI window:
Gui := GuiCreate("+Resize")  ; Allow the user to maximize or drag-resize the window.

; Create some buttons:
B_1 := Gui.Add("Button", "Default", "Load a folder")
B_2 := Gui.Add("Button", "x+20", "Clear List")
B_3 := Gui.Add("Button", "x+20", "Switch View")

; Create the ListView and its columns:
LV := Gui.Add("ListView", "xm r20 w700", "Name|In Folder|Size (KB)|Type")
LV.ModifyCol(3, "Integer")  ; For sorting, indicate that the Size column is an integer.

; Apply ListView events:
LV.OnEvent("DoubleClick", "RunFile")
LV.OnEvent("ContextMenu", "ShowContextMenu")

; Create an ImageList so that the ListView can display some icons:
ImageListID1 := IL_Create(10)
ImageListID2 := IL_Create(10, 10, true)  ; A list of large icons to go with the small ones.

; Attach the ImageLists to the ListView so that it can later display the icons:
LV.SetImageList(ImageListID1)
LV.SetImageList(ImageListID2)

; Apply control events:
LV.OnEvent("DoubleClick", "RunFile")
LV.OnEvent("ContextMenu", "ShowContextMenu")
B_1.OnEvent("Click", Func("LoadFolder").bind(Gui, LV, ImageListID1, ImageListID2))
B_2.OnEvent("Click", Func("ClearList").bind(LV))
B_3.OnEvent("Click", Func("SwitchView").bind(LV))

; Apply window events:
Gui.OnEvent("Size", Func("Gui_Size").bind(LV))

; Display the window:
Gui.Show

LoadFolder(Gui, LV, ImageListID1, ImageListID2)
{
  static IconArray := []
  Gui.Opt("+OwnDialogs")  ; Forces user to dismiss the following dialog before using main window.
  Folder := DirSelect(, 3, "Select a folder to read:")
  if not Folder  ; The user canceled the dialog.
    return

  ; Check if the last character of the folder name is a backslash, which happens for root
  ; directories such as C:\. If it is, remove it to prevent a double-backslash later on.
  if SubStr(Folder, -1, 1) = "\"
    Folder := SubStr(Folder, 1, -1)  ; Remove the trailing backslash.

  ; Calculate buffer size required for SHFILEINFO structure.
  sfi_size := A_PtrSize + 688
  VarSetCapacity(sfi, sfi_size)

  ; Gather a list of file names from the selected folder and append them to the ListView:
  LV.Opt("-Redraw")  ; Improve performance by disabling redrawing during load.
  Loop Files, Folder "\*.*"
  {
    FileName := A_LoopFilePath  ; Must save it to a writable variable for use below.

    ; Build a unique extension ID to avoid characters that are illegal in variable names,
    ; such as dashes. This unique ID method also performs better because finding an item
    ; in the array does not require search-loop.
    SplitPath(FileName,,, FileExt)  ; Get the file's extension.
    if FileExt ~= "^(EXE|ICO|ANI|CUR)$"
    {
      ExtID := FileExt  ; Special ID as a placeholder.
      IconNumber := 0  ; Flag it as not found so that these types can each have a unique icon.
    }
    else  ; Some other extension/file-type, so calculate its unique ID.
    {
      ExtID := 0  ; Initialize to handle extensions that are shorter than others.
      Loop(7)     ; Limit the extension to 7 characters so that it fits in a 64-bit value.
      {
        ExtChar := SubStr(FileExt, A_Index, 1)
        if not ExtChar  ; No more characters.
          break
        ; Derive a Unique ID by assigning a different bit position to each character:
        ExtID := ExtID | (Ord(ExtChar) << (8 * (A_Index - 1)))
      }
      ; Check if this file extension already has an icon in the ImageLists. If it does,
      ; several calls can be avoided and loading performance is greatly improved,
      ; especially for a folder containing hundreds of files:
      IconNumber := IconArray[ExtID]
    }
    if not IconNumber  ; There is not yet any icon for this extension, so load it.
    {
      ; Get the high-quality small-icon associated with this file extension:
      if not DllCall("Shell32\SHGetFileInfoW", "str", FileName
      , "uint", 0, "ptr", &sfi, "uint", sfi_size, "uint", 0x101)  ; 0x101 is SHGFI_ICON+SHGFI_SMALLICON
        IconNumber := 9999999  ; Set it out of bounds to display a blank icon.
      else ; Icon successfully loaded.
      {
        ; Extract the hIcon member from the structure:
        hIcon := NumGet(sfi, 0)
        ; Add the HICON directly to the small-icon and large-icon lists.
        ; Below uses +1 to convert the returned index from zero-based to one-based:
        IconNumber := DllCall("ImageList_ReplaceIcon", "ptr", ImageListID1, "int", -1, "ptr", hIcon) + 1
        DllCall("ImageList_ReplaceIcon", "ptr", ImageListID2, "int", -1, "ptr", hIcon)
        ; Now that it's been copied into the ImageLists, the original should be destroyed:
        DllCall("DestroyIcon", "ptr", hIcon)
        ; Cache the icon to save memory and improve loading performance:
        IconArray[ExtID] := IconNumber
      }
    }

    ; Create the new row in the ListView and assign it the icon number determined above:
    LV.Add("Icon" . IconNumber, A_LoopFileName, A_LoopFileDir, A_LoopFileSizeKB, FileExt)
  }
  LV.Opt("+Redraw")  ; Re-enable redrawing (it was disabled above).
  LV.ModifyCol  ; Auto-size each column to fit its contents.
  LV.ModifyCol(3, 60) ; Make the Size column at little wider to reveal its header.
}

ClearList(LV)
{
  LV.Delete  ; Clear the ListView, but keep icon cache intact for simplicity.
}

SwitchView(LV)
{
  static IconView
  if not IconView
    LV.Opt("+Icon")         ; Switch to icon view.
  else
    LV.Opt("+Report")       ; Switch back to details view.
  IconView := not IconView  ; Invert in preparation for next time.
}

RunFile(LV, RowNumber, Verb := "")
{
  FileName := LV.GetText(RowNumber, 1) ; Get the text of the first field.
  FileDir := LV.GetText(RowNumber, 2)  ; Get the text of the second field.
  FilePath := FileDir "\" FileName
  Verb .= Verb ? " " : ""
  try
    Run(Verb FilePath)
  catch Error
    MsgBox(Error.Extra "`n" FilePath)
}

ShowContextMenu(LV, Item, IsRightClick, X, Y)  ; In response to right-click or Apps key.
{
  ; Create function references for the menu events:
  ContextOpen := Func("ContextOpen").bind(LV, Item)
  ContextProperties := Func("ContextProperties").bind(LV, Item)
  ContextClearRows := Func("ContextClearRows").bind(LV)
 
  ; Create the popup menu to be used as the context menu:
  ContextMenu := MenuCreate()
  ContextMenu.Add("Open", ContextOpen)
  ContextMenu.Add("Properties", ContextProperties)
  ContextMenu.Add("Clear from ListView", ContextClearRows)
  ContextMenu.Default := "Open"  ; Make "Open" a bold font to indicate that double-click does the same thing.
  ; Show the menu at the provided coordinates, X and Y.  These should be used
  ; because they provide correct coordinates even if the user pressed the Apps key:
  ContextMenu.Show(X, Y)
}

ContextOpen(LV, RowNumber)  ; The user selected "Open" in the context menu.
{
  RunFile(LV, RowNumber)
}

ContextProperties(LV, RowNumber)  ; The user selected "Properties" in the context menu.
{
  RunFile(LV, RowNumber, "properties")
}

ContextClearRows(LV)  ; The user selected "Clear" in the context menu.
{
  RowNumber := 0  ; This causes the first iteration to start the search at the top.
  Loop
  {
    ; Since deleting a row reduces the RowNumber of all other rows beneath it,
    ; subtract 1 so that the search includes the same row number that was previously
    ; found (in case adjacent rows are selected):
    RowNumber := LV.GetNext(RowNumber - 1)
    if not RowNumber  ; The above returned zero, so there are no more selected rows.
      break
    LV.Delete(RowNumber)  ; Clear the row from the ListView.
  }
}

Gui_Size(LV, Gui, MinMax, Width, Height)  ; Expand/Shrink ListView in response to the user's resizing.
{
  if MinMax = -1  ; The window has been minimized. No action needed.
    return
  ; Otherwise, the window has been resized or maximized. Resize the ListView to match.
  LV.Move("W" Width-20 " H" Height-40)
}