wListCtrl

    Dark Mode

A list control presents lists in a number of formats: list view, report view, icon view and small icon view.

Appearance:
Superclass:wControl
Styles:
StylesDescription
wLcListMulticolumn list view.
wLcReportSingle or multicolumn report view, with optional header.
wLcIconLarge icon view, with optional labels.
wLcSmallIconSmall icon view, with optional labels.
wLcAlignTopIcons align to the top. Win32 default, Win32 only.
wLcAlignLeftIcons align to the left.
wLcAutoArrangeIcons arrange themselves. Win32 only.
wLcNoSortHeaderColumn headers do not work like buttons.
wLcNoHeaderNo header in report mode.
wLcEditLabelsLabels are editable.
wLcSingleSelSingle selection (default is multiple).
wLcSortAscendingSort in ascending order.
wLcSortDescendingSort in descending order.
Events:wListEvent

Types

wListCtrl_Compare = proc (item1: int; item2: int; data: int): int
Comparing callback function prototype used in sortItems() and sortItemsByIndex()

Consts

wLcList = 0x00000003
wLcReport = 0x00000001
wLcIcon = 0x00000000
wLcSmallIcon = 0x00000002
wLcAlignTop = 0x00000000
wLcAlignLeft = 0x00000800
wLcAutoArrange = 0x00000100
wLcNoSortHeader = 0x00008000
wLcNoHeader = 0x00004000
wLcEditLabels = 0x00000200
wLcSingleSel = 0x00000004
wLcSortAscending = 0x00000010
wLcSortDescending = 0x00000020
wListImageCallback = -1
wListImageNone = -2
wListAutosize = -1
wListAutosizeUseHeader = -2
wListIgnore = -3
wImageListNormal = 0
wImageListSmall = 1
wImageListState = 2
wListFormatLeft = 0x00000000
wListFormatRight = 0x00000001
wListFormatCenter = 0x00000002
wListStateFocused = 0x00000001
wListStateSelected = 0x00000002
wListStateDropHighlighted = 0x00000008
wListStateCut = 0x00000004
wListRectBounds = 0
wListRectIcon = 1
wListRectLabel = 2
wListRectSelectBounds = 3
wListHittestAbove = 0x00000008
wListHittestBelow = 0x00000010
wListHittestToLeft = 0x00000040
wListHittestToRight = 0x00000020
wListHittestNoWhere = 0x00000001
wListHittestOnItemLabel = 0x00000004
wListHittestOnItemIcon = 0x00000002
wListHittestOnItemStateIcon = 0x00000008
wListAlignDefault = 0x00000000
wListAlignLeft = 0x00000001
wListAlignTop = 0x00000002
wListAlignSnapToGrid = 0x00000005
wListNextAll = 0x00000000
wListNextPrevious = 0x00000020
wListNextAbove = 0x00000100
wListNextBelow = 0x00000200
wListNextLeft = 0x00000400
wListNextRight = 0x00000800
wListStateDontCare = 0

Procs

proc setColumnWidth(self: wListCtrl; col: int; width: int) {...}{.raises: [], tags: [].}
Sets the column width. width can be a width in pixels or wListAutosize (-1) or wListAutosizeUseHeader (-2). For wLcList mode, col must be set to 0.
proc insertColumn(self: wListCtrl; col: int; text = ""; format = wListFormatLeft;
                 width = wListAutosize; image = wListImageNone): int {...}{.discardable,
    raises: [], tags: [].}
For report view mode (only), inserts a column. Notice that in case of wListAutosize fixed width is used as there are no items in this column to use for determining its best size yet. If you want to fit the column to its contents, use setColumnWidth() after adding the items with values in this column.
proc appendColumn(self: wListCtrl; text = ""; format = wListFormatLeft;
                 width = wListAutosize; image = wListImageNone): int {...}{.inline,
    discardable, raises: [], tags: [].}
Adds a new column to the list control in report view mode.
proc setColumn(self: wListCtrl; col: int; text = ""; format = wListIgnore;
              width = wListIgnore; image = wListIgnore) {...}{.raises: [], tags: [].}
Sets information about this column.
ParametersDescription
colThe index where the column should be inserted.
textThe string specifying the column heading.
formatThe flags specifying the control heading text alignment. wListFormatLeft, wListFormatRight or wListFormatCenter.
widthIf positive, the width of the column in pixels. Otherwise it can be wListAutosize to choose the default size for the column or wListAutosizeUseHeader to fit the column width to heading or to extend to fill all the remaining space for the last column.
imageZero-based index of the image associated with the item into the image list.
proc setColumnText(self: wListCtrl; col: int; text: string) {...}{.inline, raises: [], tags: [].}
Sets the column text.
proc setColumnFormat(self: wListCtrl; col: int; format: int) {...}{.inline, raises: [],
    tags: [].}
Sets the column format.
proc setColumnImage(self: wListCtrl; col: int; image: int) {...}{.inline, raises: [], tags: [].}
Sets the column image.
proc getColumnCount(self: wListCtrl): int {...}{.inline, raises: [], tags: [].}
Returns the number of columns.
proc getColumnWidth(self: wListCtrl; col: int): int {...}{.raises: [], tags: [].}
Gets the column width.
proc getColumnFormat(self: wListCtrl; col: int): int {...}{.raises: [], tags: [].}
Gets the column format.
proc getColumnImage(self: wListCtrl; col: int): int {...}{.raises: [], tags: [].}
Gets the column format.
proc getColumnText(self: wListCtrl; col: int): string {...}{.raises: [], tags: [].}
Gets the column text.
proc getItemCount(self: wListCtrl): int {...}{.raises: [], tags: [].}
Returns the number of items in the list control.
proc deleteColumn(self: wListCtrl; col: int) {...}{.raises: [], tags: [].}
Deletes a column.
proc deleteAllColumns(self: wListCtrl) {...}{.raises: [], tags: [].}
Delete all columns in the list control.
proc insertItem(self: wListCtrl; index: int; text = ""; image = wListImageNone;
               data: int = 0): int {...}{.discardable, raises: [], tags: [].}
Inserts an item, returning the index of the new item if successful, -1 otherwise
proc appendItem(self: wListCtrl; text = ""; image = wListImageNone; data: int = 0): int {...}{.
    inline, discardable, raises: [], tags: [].}
Adds an item.
proc setItem(self: wListCtrl; index: int; col: int = 0; text = ""; image = wListIgnore;
            state = 0; flag = true) {...}{.raises: [], tags: [].}
Sets the data of an item.
ParametersDescription
indexZero based item position.
colOne-based index of column, or zero refers to an item rather than a subitem.
textThe label.
imageThe zero based index into an image list.
stateThe state of the item. This is a bitlist of the following flags:
  • wListStateFocused: The item has the focus.
  • wListStateSelected: The item is selected
  • wListStateDropHighlighted: The item is highlighted.
  • wListStateCut: The item is in the cut state
flagSet state to true or false.
proc setItemText(self: wListCtrl; index: int; col: int = 0; text: string) {...}{.inline,
    raises: [], tags: [].}
Sets the text of an item.
proc setItemState(self: wListCtrl; index: int; col: int = 0; state: int; flag = true) {...}{.
    inline, raises: [], tags: [].}
Sets the state of an item.
proc setItemImage(self: wListCtrl; index: int; col: int = 0; image: int) {...}{.inline,
    raises: [], tags: [].}
Sets the image of an item.
proc setItemData(self: wListCtrl; index: int; data: int) {...}{.inline, raises: [], tags: [].}
Associates application-defined data with this item.
proc getItemText(self: wListCtrl; index: int; col: int = 0): string {...}{.raises: [], tags: [].}
Gets the item text.
proc getItemState(self: wListCtrl; index: int; col: int = 0): int {...}{.raises: [], tags: [].}
Gets the item state.
proc getItemImage(self: wListCtrl; index: int; col: int = 0): int {...}{.raises: [], tags: [].}
Gets the item image.
proc getItemData(self: wListCtrl; index: int): int {...}{.raises: [], tags: [].}
Gets the application-defined data associated with this item.
proc insertItem(self: wListCtrl; index: int; texts: openArray[string];
               image = wListImageNone; data: int = 0): int {...}{.discardable, raises: [],
    tags: [].}
Inserts an item, and sets the text of subitems in the mean time.
proc appendItem(self: wListCtrl; texts: openArray[string]; image = wListImageNone;
               data: int = 0): int {...}{.discardable, raises: [], tags: [].}
Adds an item, and sets the text of subitems in the mean time.
proc deleteItem(self: wListCtrl; index: int) {...}{.raises: [], tags: [].}
Deletes the specified item.
proc deleteAllItems(self: wListCtrl) {...}{.raises: [], tags: [].}
Deletes all items in the list control.
proc clearAll(self: wListCtrl) {...}{.inline, raises: [], tags: [].}
Deletes all items and all columns.
proc len(self: wListCtrl): int {...}{.inline, raises: [], tags: [].}
Returns the number of items in the list control. The same as getItemCount().
proc findItem(self: wListCtrl; text: string; start: int = 0; partial = false): int {...}{.
    raises: [], tags: [].}
Find an item whose label matches this string. If partial is true then this method will look for items which begin with text.
proc findItem(self: wListCtrl; data: int; start: int = 0): int {...}{.raises: [], tags: [].}
Find an item whose data matches this data.
proc getItemPosition(self: wListCtrl; index: int): wPoint {...}{.raises: [], tags: [].}
Returns the position of the item, in icon or small icon view.
proc setItemPosition(self: wListCtrl; index: int; pos: wPoint) {...}{.raises: [], tags: [].}
Sets the position of the item, in icon or small icon view.
proc getItemSpacing(self: wListCtrl): wSize {...}{.raises: [], tags: [].}
Retrieves the spacing between icons in pixels
proc setItemSpacing(self: wListCtrl; width: int; height: int) {...}{.raises: [], tags: [].}
Sets the spacing between icons.
proc setItemSpacing(self: wListCtrl; size: wSize) {...}{.inline, raises: [], tags: [].}
Sets the spacing between icons.
proc getTopItem(self: wListCtrl): int {...}{.raises: [], tags: [].}
Gets the index of the topmost visible item when in list or report view.
proc getCountPerPage(self: wListCtrl): int {...}{.raises: [], tags: [].}
Gets the number of items that can fit vertically in the visible area of the list control (list or report view) or the total number of items in the list control (icon or small icon view).
proc getItemRect(self: wListCtrl; index: int; code = wListRectBounds): wRect {...}{.
    raises: [], tags: [].}
Returns the rectangle representing the item's size and position, in physical coordinates. code is one of wListRectBounds, wListRectIcon, wListRectLabel or wListRectSelectBounds.
proc getSubItemRect(self: wListCtrl; index, col: int; code = wListRectBounds): wRect {...}{.
    raises: [], tags: [].}
Returns the rectangle representing the size and position, in physical coordinates, of the given subitem. This method is only meaningful when the wListCtrl is in the report mode. code can be one wListRectBounds, wListRectIcon or wListRectLabel.
proc getViewRect(self: wListCtrl): wRect {...}{.raises: [], tags: [].}
Returns the rectangle taken by all items in the control. Note that this function only works in the icon views, small icon views, and reprot views.
proc getView(self: wListCtrl): int {...}{.raises: [], tags: [].}
Gets the view style of list control. wLcIcon, wLcSmallIcon, wLcList or wLcReport.
proc setView(self: wListCtrl; style: int) {...}{.raises: [], tags: [].}
Sets the view style of list contorl.
proc setImageList(self: wListCtrl; imageList: wImageList; which = wImageListSmall) {...}{.
    raises: [wNilAccess], tags: [].}
Sets the image list associated with the control. which is one of wImageListNormal, wImageListSmall, wImageListState.
proc getImageList(self: wListCtrl; which = wImageListNormal): wImageList {...}{.raises: [],
    tags: [].}
Returns the specified image list. which is one of wImageListNormal, wImageListSmall, wImageListState.
proc setTextColor(self: wListCtrl; color: wColor) {...}{.raises: [], tags: [].}
Sets the text color of the list control.
proc getTextColor(self: wListCtrl): wColor {...}{.raises: [], tags: [].}
Gets the text color of the list control.
proc setAlternateRowColor(self: wListCtrl; color: wColor) {...}{.inline, raises: [], tags: [].}
Sets alternating row background colors. Use a negative color vlaue to start from first row.
proc getAlternateRowColor(self: wListCtrl): wColor {...}{.inline, raises: [], tags: [].}
Gets alternating row background colors.
proc disableAlternateRowColors(self: wListCtrl) {...}{.inline, raises: [], tags: [].}
Disable alternating row background colors.
proc enableAlternateRowColors(self: wListCtrl; flag = true) {...}{.raises: [], tags: [].}
Enable alternating row background colors. The appropriate color for the even rows is chosen automatically.
proc getSelectedItemCount(self: wListCtrl): int {...}{.raises: [], tags: [].}
Returns the number of selected items in the list control.
proc getColumnsOrder(self: wListCtrl): seq[int] {...}{.raises: [], tags: [].}
Returns the seq containing the orders of all columns.
proc setColumnsOrder(self: wListCtrl; orders: openArray[int]) {...}{.raises: [], tags: [].}
Changes the order in which the columns are shown.
proc ensureVisible(self: wListCtrl; index: int) {...}{.raises: [], tags: [].}
Ensures this item is visible.
proc hitTest(self: wListCtrl; x: int; y: int): tuple[index, col, flag: int] {...}{.raises: [],
    tags: [].}
Determines which item (if any) is at the specified point, giving details in flags. flag will be a combination of the following flags:
FlagDescription
wListHittestAboveAbove the control's client area.
wListHittestBelowBelow the control's client area.
wListHittestToLeftTo the left of the control's client area.
wListHittestToRightTo the right of the control's client area.
wListHittestNoWhereInside the control's client area but not over an item.
wListHittestOnItemLabelOver an item's text.
wListHittestOnItemIconOver an item's icon.
wListHittestOnItemStateIconOver the checkbox of an item.
proc hitTest(self: wListCtrl; pos: wPoint): tuple[index, col, flag: int] {...}{.inline,
    raises: [], tags: [].}
The same as hitTest().
proc arrange(self: wListCtrl; flag = wListAlignDefault) {...}{.raises: [], tags: [].}
Arranges the items in icon or small icon view. flag is one of: wListAlignDefault, wListAlignLeft, wListAlignTop, wListAlignSnapToGrid
proc getNextItem(self: wListCtrl; start: int; geometry: int; state: int): int {...}{.
    raises: [], tags: [].}
Searches for an item with the given geometry or state, starting from start. geometry can be one of wListNextAll, wListNextPrevious, wListNextAbove, wListNextBelow, wListNextLeft, wListNextRight. state can be a bitlist of wListStateDontCare, wListStateDropHighlighted, wListStateFocused, wListStateSelected, wListStateCut.
proc refreshItem(self: wListCtrl; item: int; itemTo = -1) {...}{.raises: [], tags: [].}
Redraws the given item or items between item and itemTo.
proc scrollList(self: wListCtrl; dx: int; dy: int) {...}{.raises: [], tags: [].}
Scrolls the list control.
proc sortItems(self: wListCtrl; callback: wListCtrl_Compare; data: int = 0) {...}{.raises: [],
    tags: [].}
Sorts the items in the list control. The value passed into callback function is the data associated with the item. You can use setItemData() to set it. The extra parameter data is the value passed into callback funtion as third parameter.
proc sortItemsByIndex(self: wListCtrl; callback: wListCtrl_Compare; data: int = 0) {...}{.
    raises: [], tags: [].}
Sorts the items in the list control. The value passed into callback function is the item index. You can use getItemText() to retrieve more information on an item if needed.
proc setExtendedStyle(self: wListCtrl; exStyle: DWORD; flag = true) {...}{.raises: [], tags: [].}
Sets extended styles in the list controls. See MSDN about "Extended List-View Styles" for more information.
proc getExtendedStyle(self: wListCtrl): DWORD {...}{.raises: [], tags: [].}
Gets the extended styles that are currently in use for the list control.
proc enableCheckBoxes(self: wListCtrl; enable = true) {...}{.inline, raises: [], tags: [].}
Enable or disable checkboxes for list items.
proc hasCheckBoxes(self: wListCtrl): bool {...}{.raises: [], tags: [].}
Returns true if checkboxes are enabled for list items.
proc checkItem(self: wListCtrl; index: int; state = true) {...}{.raises: [], tags: [].}
Check or uncheck a item in a control using checkboxes.
proc isItemChecked(self: wListCtrl; index: int): bool {...}{.raises: [], tags: [].}
Return true if the checkbox for the given index is checked.
proc getEditControl(self: wListCtrl): wTextCtrl {...}{.raises: [], tags: [].}
Returns the edit control being currently used to edit a label. Returns nil if no label is being edited.
proc editLabel(self: wListCtrl; index: int): wTextCtrl {...}{.discardable, raises: [],
    tags: [].}
Starts editing the label of the given item.
proc endEditLabel(self: wListCtrl; cancel = false) {...}{.raises: [], tags: [].}
Finish editing the label.
proc init(self: wListCtrl; parent: wWindow; id: wCommandID = wDefaultID;
         pos = wDefaultPoint; size = wDefaultSize; style: wStyle = wLcIcon) {...}{.raises: [
    wNilAccess, wWindowError, wCursorError, wBrushError, Exception, IndexDefect,
    wFontError], tags: [RootEffect].}
Initializes a list control.
proc ListCtrl(parent: wWindow; id: wCommandID = wDefaultID; pos = wDefaultPoint;
             size = wDefaultSize; style: wStyle = wLcIcon): wListCtrl {...}{.inline,
    discardable, raises: [wNilAccess, wWindowError, wCursorError, wBrushError,
                        Exception, IndexDefect, wFontError], tags: [RootEffect].}
Constructor.

Methods

method setBackgroundColor(self: wListCtrl; color: wColor) {...}{.raises: [Exception],
    tags: [RootEffect].}
Sets the background color of the control.
method setForegroundColor(self: wListCtrl; color: wColor) {...}{.raises: [Exception],
    tags: [RootEffect].}
Sets the foreground color of the control.
method getBestSize(self: wListCtrl): wSize {...}{.raises: [], tags: [].}
Returns the best acceptable minimal size for the control.
method release(self: wListCtrl) {...}{.raises: [], tags: [].}
Release all the resources during destroying. Used internally.

Iterators

iterator items(self: wListCtrl): string {...}{.raises: [], tags: [].}
Iterate each item in this list control.
iterator pairs(self: wListCtrl): (int, string) {...}{.raises: [], tags: [].}
Iterates over each item in list control. Yields (index, [index]) pairs.