Skip to content

TTMSFNCListBox / TTMSFNCCheckedListBox

TTMSFNCUIPack74

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.

TMSFNCListBox1.AddItem(‘Hello’);
it := TMSFNCListBox1.Items.Add;
it.Text := ‘Hello’;

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;
TTMSFNCUIPack75

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;
TTMSFNCUIPack76

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.

TTMSFNCUIPack77

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.

TTMSFNCUIPack78

After filtering, the node that matches the chosen filter is shown.

TTMSFNCUIPack79

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;
TTMSFNCUIPack80

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.

TMSFNCListBox1.Interaction.Sorting := lcsNormal;

TTMSFNCUIPack81

Sorting can also be done programmatically, with the following code, which will show the same result as the screenshot above.

TMSFNCListBox1.Sort(False, ismAscending);

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;

TTMSFNCUIPack82