TTMSFNCListBox / TTMSFNCCheckedListBox
Properties
Property name | Description |
---|---|
DefaultItem | The default item properties, which are applied when creating a new item. |
Fill | The background fill of the listbox. |
Header | The header of the listbox. |
Interaction | The interaction properties of the listbox. |
ItemIndex | The selected item index. |
Items | The collection of listbox items. |
ItemsAppearance | The general appearance of the listbox items. |
Stroke | The stroke of the background of the listbox. |
VerticalScrollBarVisible | Shows or hides the vertical scrollbar. |
Methods / public properties
Method name | Description |
---|---|
AddItem(AText: string = ’’): TTMSFNCListBoxItem | Adds a new item |
ApplyFilter; | Applies the filter, configured programmatically with the filter property. |
Checked[AItemIndex: Integer]: Boolean; (TTMSFNCCheckedListBox) | Returns the checked state for an item based on the index. |
CheckedItems: TTMSFNCListBoxCheckedItems; (TTMSFNCCheckedListBox) | Returns all the checked items in the listbox. |
CheckedItems[AItem: TTMSFNCCheckedListboxItem]: Boolean; (TTMSFNCCheckedListBox) | Returns the checked state for an item. |
ClearSorting; | Clears all sorting applied to the listbox. |
CopyToClipboard(ATextOnly: Boolean = False); | Copies the selected items to the clipboard. |
CutToClipboard(ATextOnly: Boolean = False); | Cuts the selected items to the clipboard. |
Filter: TTMSFNCListBoxFilter; | The filter, used for programmatic filtering in the listbox. |
GetItemsFromClipboard: TTMSFNCListBoxCopyItems | Gets the items from the clipboard. |
IsItemSelectable(AItem: TTMSFNCListBoxItem): Boolean; | Returns a boolean whether an item is selectable or not. |
LoadFromFile(AFileName: String); | Loads the listbox items from a flie. |
LoadFromStream(AStream: TStream); | Loads the listbox items from a stream. |
LoadFromStrings(AStrings: TStrings); | Loads the listbox items from a TStrings instance. |
LookupItem(ALookupString: String; ACaseSensitive: Boolean = False; AAutoSelect: Boolean = False): TTMSFNCListBoxItem; | Looks up an item, and optionally selects it. |
PasteFromClipboard; | Pastes items from the clipboard. |
RemoveFilter; | Removes the active filter. |
RemoveFilters; | Removes all filters from the listbox. |
RemoveItem(AItem: TTMSFNCListBoxItem); | Removes an item from the listbox. |
SaveToFile(AFileName: String; ATextOnly: Boolean = True); | Saves the listbox to a file, optionally text-only to be compatible with other item loading components such as TTreeView / TListBox. |
SaveToStream(AStream: TStream; ATextOnly: | |
Boolean = True); | Saves the listbox to a stream, optionally textonly to be compatible with other item loading components such as TTreeView / TListBox. |
SaveToStrings(AStrings: TStrings); | Saves the listbox item to a TStrings instance. |
ScrollToItem(AItemIndex: Integer); | Scrolls to the itemindex. |
SelectedItem: TTMSFNCListBoxItem; | Returns the selected item. |
SelectedItemCount: Integer | Returns the selected item count. |
SelectedItems[AIndex: Integer]: TTMSFNCListBoxItem; | Returns the selected item based on the index in the selected items collection. |
SelectItem(AItemIndex: Integer); | Selects an item. |
SelectItems(AItemIndexes: TTMSFNCListBoxItemArray); | Selects an array of items. |
Sort(ACaseSensitive: Boolean = True; ASortingMode: TTMSFNCListBoxItemsSortMode); | Sorts the items. |
XYToItem(X, Y: Single): TTMSFNCListBoxItem; | Returns the item under X and Y coordinate. |
XYToItemIndex(X, Y: Single): Integer; | Returns the item index under X and Y coordinate. |
Events
Event name | Description |
---|---|
OnAfterCopyToClipboard | Event called after a clipboard copy operation is completed. |
OnAfterCutToClipboard | Event called after a clipboard cut operation is completed. |
OnAfterDrawItem | Event called after an item is drawn. |
OnAfterDrawItemCheck (TTMSFNCCheckedListBox) | Event called after an item checkbox is drawn. |
OnAfterDrawItemIcon | Event called after an item icon is drawn. |
OnAfterDrawItemText | Event called after the text of an item is drawn. |
OnAfterDropItem | Event called after an item has been dropped by a drag & drop operation. |
OnAfterPasteFromClipboard | Event called after content has been pasted from the clipboard. |
OnAfterReorderItem | Event called after an item is reordered. |
OnBeforeCopyToClipboard | Event called before a clipboard copy operation is completed. |
OnBeforeCutToClipboard | Event called before a clipboard cut operation is completed. |
OnBeforeDrawItem | Event called before an item is drawn. |
OnBeforeDrawItemCheck (TTMSFNCCheckedListBox) | Event called before an item checkbox is drawn. |
OnBeforeDrawItemIcon | Event called before an item icon is drawn. |
OnBeforeDrawItemText | Event called before the text of an item is drawn. |
OnBeforeDropItem | Event called before an item has been dropped by a drag & drop operation. |
OnBeforePasteFromClipboard | Event called before content has been pasted from the clipboard. |
OnBeforeReorderItem | Event called before an item is reordered. |
OnFilterSelect | Event called when a item from the filter listbox is clicked. |
OnItemAnchorClick | Event called when an anchor inside an item text is clicked. |
OnItemCheckChanged (TTMSFNCCheckedListBox) | Event called when an item check state has changed. |
OnItemClick | Event called when an item is clicked. |
OnItemCompare | Event called when an item is compared with another item when sorting is applied. |
OnItemDblClick | Event called when an item is double-clicked. |
OnItemSelected | Event called when an item is selected. |
OnNeedFilterDropDownData | Event called when the filter request the data that needs to be placed inside the filter box. |
OnVScroll | Event called when the listbox is scrolled. |
Adding new Items
Items can be added at designtime through the items collection, but can also be added programmatically using the AddItem function. Below is a sample using both the collection and the helper function.
Default Item
When adding new item, the values from the DefaultItem property are copied. This way, you can add a default icon, text, text color and many more. Below is a sample that demonstrates this.
var
it: TTMSFNCListBoxItem;
begin
TMSFNCListBox1.BeginUpdate;
TMSFNCListBox1.Items.Clear;
TMSFNCListBox1.DefaultItem.Text := 'Hello';
it := TMSFNCListBox1.Items.Add;
it.Text := it.Text + ' 1';
it := TMSFNCListBox1.Items.Add;
it.Text := it.Text + ' 2';
TMSFNCListBox1.DefaultItem.TextColor := gcRed;
it := TMSFNCListBox1.Items.Add;
it.Text := it.Text + ' 3';
it := TMSFNCListBox1.Items.Add;
it.Text := it.Text + ' 4';
TMSFNCListBox1.EndUpdate;
end;

Appearance
The listbox exposes a set of properties for overall item appearance. The background of an item can be customized for various states such as normal, selected, disabled. Below is a sample that demonstrates how to customize the selection color of an item.
TMSFNCListBox1.ItemsAppearance.SelectedFill.Color := gcRed;
TMSFNCListBox1.ItemsAppearance.SelectedStroke.Color := gcRed;

Interaction
The Listbox supports interaction through mouse and keyboard. When clicking on an item that is selectable, the item is selected. When navigating with the keys up, down, home, end, page up or page down the selected item will be changed. Disabled items are not selectable.
When the property MultiSelect is true, multiple items can be selected with the CTRL and SHIFT key with either the mouse or keyboard. The selected items can be retrieved with the SelectedItemCount function and SelectedItems property. Selection of items can be done with the SelectItem or SelectItems method. The SelectItems method takes an array of items.
Clipboard
Cut, Copy and Paste is supported when setting the Interaction.ClipboardMode property to tcmTextOnly or tcmFull. The tcmTextOnly value only copies the text and does not copy along other attributes such as the check state or the item icon. The tcmFull clipboard mode copies all attributes of the item. Cut will first copy the item and then remove it from the listbox. There are additional events that are triggered when performing a cut, copy or paste action.
Reordering / Drag & Drop
When setting Interaction.Reorder to True, clicking on an already selected item will duplicate the item and attach it while dragging. When releasing the item over another item it will reorder the item to the new location. Please note that touch scrolling is disabled when reordering is true on the selected item part. On the non-selected item parts, touch scrolling is still active.
When setting Interaction.DragDropMode to ldmMove or ldmCopy the same approach can be used as reordering, and will allow you to drop the item to a different location. Drag & drop takes precedence over reordering, and with drag & drop you cannot only move or copy items in the same listbox but also move items to another listbox.
Filtering
When setting Interaction.Filtering.Enabled := True; a filter dropdown button appears at the right side of the header. Clicking on the filter button will show a filter dropdown list with unique values. After clicking a value, the listbox shows a filtered list.
After filtering, the node that matches the chosen filter is shown.
To clear filtering, click the ‘(All)’ entry in the filter list. Note that filtering is also available programmatically. Below is a sample that filtes the items with an O:
var
f: TTMSFNCListBoxFilterData;
begin
TMSFNCListBox1.Filter.Clear;
f := TMSFNCListBox1.Filter.Add;
f.Condition := '*P*';
TMSFNCListBox1.ApplyFilter;
end;

To clear all filtering programmatically, you can use the following code: TMSFNCListBox1.RemoveFilters;
Sorting
When clicking on the header, the items are sorted and the listbox is updated. Below is a sample that demonstrates this.
Sorting can also be done programmatically, with the following code, which will show the same result as the screenshot above.
Customization
The listbox supports various kinds of customization, such as custom drawing, custom filtering and sorting. Below is a sample that demonstrates how to draw a rating icon for each item through the OnAfterDrawItem event.
procedure TForm1.FormCreate(Sender: TObject);
var
I: Integer;
begin
for I := 0 to TMSFNCListBox1.Items.Count - 1 do
TMSFNCListBox1.Items[I].DataInteger := RandomRange(1, 6)
end;
procedure TForm1.TMSFNCListBox1AfterDrawItem(Sender: TObject;
AGraphics: TTMSFNCGraphics; ARect: TRectF; AItem: TTMSFNCListBoxItem);
var
r: Integer;
I: Integer;
bmp: TBitmap;
rrt: TRectF;
begin
r := AItem.DataInteger;
bmp := TMSFNCBitmapContainer1.FindBitmap('rating');
for I := 0 to r - 1 do
begin
rrt := RectF(Round(ARect.Right - ((bmp.Width + 4) * (I + 1))), Round(ARect.Top + (ARect.Height -
bmp.Height) / 2),
Round(ARect.Right - ((bmp.Width + 4) * I)), Round(ARect.Top + (ARect.Height - bmp.Height) / 2
+ bmp.Height));
AGraphics.DrawBitmap(rrt, bmp);
end;
end;