Difference between revisions of "TListView"

From Free Pascal wiki
Jump to navigationJump to search
(18 intermediate revisions by the same user not shown)
Line 6: Line 6:
 
* '''GetNextItem'''() requires StartItem to be provided. This is incompatible with Delphi's GetNextItem(), where startItem is allowed to be '''nil''', which will perform the search from the relative (direction driven) start.
 
* '''GetNextItem'''() requires StartItem to be provided. This is incompatible with Delphi's GetNextItem(), where startItem is allowed to be '''nil''', which will perform the search from the relative (direction driven) start.
 
==Sorting==
 
==Sorting==
Sorting is (typically?) applied when using '''vsReport''' ViewStyle. Sorting might be a time consuming process or a larger data scale (when comparison of items takes a considerable time).
+
TODO: add description on how OwnerData affects the sorting
 +
 
 +
Sorting is (typically?) applied when using '''vsReport''' ViewStyle, as it's column driven (with Sortcolumn index required). Sorting might be a time consuming for a larger data scale (when comparison of items takes a considerable time).  
  
 
'''SortType''' is the key property in order to perform any sorting in TListView.  
 
'''SortType''' is the key property in order to perform any sorting in TListView.  
The default value is '''stNone''', that suggests that no sorting should be for the control.
+
:'''stNone''' - (the default value) that no sorting should be for the control.
 +
:'''stText''' - the text of a cells would be used for item comparison. The actual text entry is controlled by '''SortColumn''' property. Note the default sorting comparison is actually treats the text as Ansi, rather than UTF8. Thus the result might be undesired for the non-English texts
 +
:'''stData''' - the default sorting comparison treats '''Data''' property as an integer value (by casting pointer to an integer) and sorts the according to value. (in most cases such sorting is useless, unless "Data" is an actual integer casted to the pointer)
 +
:'''stBoth''' - treated as '''stText''' for in the default sorting comparison.
 +
 
 +
Unless using text sorting, the default comparison method is not the best approach, instead a custom comparison could be used. The custom comparison is assigned with '''OnCompare''' event of TListView. The following parameters are passed:
 +
: '''Sender''' - TListview that's being sorted
 +
: '''Item1''' - one TListItem being compared
 +
: '''Item2''' - another TListItem being compared to the one
 +
: '''Data''' - is not used and is always passed as zero. (provided for Delphi compatibility)
 +
: '''Compare''' - the result of the comparison, that must be populated by the event. The following values should be assigned to the '''Compare''' argument.
 +
::-1 - if Item1 should show up "earlier" in Ascending order, than Item2. (Item1 is less than Item2)
 +
::0 - if two items are equal
 +
::1 - if Item2 should show up "earlier" in Ascending order, than Item1. (Item2 is less than Item1)
 +
::It's a normal practice to reverse the comparison result value, if SortDirection is descending. I.e.:
 +
<source lang="delphi">
 +
procedure TForm1.ListView1OnCompare(Sender: TObject; Item1, Item2: TListItem;
 +
  Data: Integer; var Compare: Integer)
 +
begin
 +
  ... do the comparison...
 +
 
 +
  if TListView(Sender).SortDirection = sdDescending then
 +
    Compare := -Compare;
 +
end;
 +
</source>
 +
 
 +
The OnCompare event should check for '''SortType''', '''SortColumn''' and  '''SortDirection''' properties of TListView, and do adjust the comparison result respectively of those properties.
 +
 
 +
 
 +
Method '''Sort''' performs of items, if '''SortType''' is other than '''stNone''' and SortColumn is assigned to a valid column index.
  
 +
Method '''CustomSort''' performs a one-time sorting using a provided sorting function.
 +
:ASortProc: TLVCompare - sorting function
 +
:AOptionalParam: PtrInt - sorting parameter
 +
Sorting parameter is ignored (provided for the Delphi compatibility). If '''ASortProc''' is passed as nil, then the either sorting OnCompare is used or default sorting.
  
 
Typically the sorting can be requested by a user. Whenever a user clicks on a column header, that requires to either sort (initially ascendancy) or to switch to the opposite sorting order (either from ascendant to descendant, or back). It's not a rule, but a common expectation. For some data sets selecting sorting might not make any sense. '''AutoSort''' (default value is true)the property of TListview controls, if the listview should be sorted automatically, as soon as user clicks on a column header. '''AutoSort''' will have no effect, while '''SortType''' is set to '''stNone'''.
 
Typically the sorting can be requested by a user. Whenever a user clicks on a column header, that requires to either sort (initially ascendancy) or to switch to the opposite sorting order (either from ascendant to descendant, or back). It's not a rule, but a common expectation. For some data sets selecting sorting might not make any sense. '''AutoSort''' (default value is true)the property of TListview controls, if the listview should be sorted automatically, as soon as user clicks on a column header. '''AutoSort''' will have no effect, while '''SortType''' is set to '''stNone'''.
  
'''AlphaSort''' is a convenience method, that performs ascending sort based on the text of the first column (index 0)
+
'''AlphaSort''' is a convenience method, that changes the settings to ascending sort (SortDirection=sdAscending) based on the text (SortType=stText) of the first column (SortColumn=0). Note that the actual properties are changed.
 +
 
 +
===Sort Indicator===
 +
Originating from: https://bugs.freepascal.org/view.php?id=36281
 +
 
 +
In trunk since r62567
 +
 
 +
1) Add a new property '''SortIndicator''' to TListViewColumn. The property controls system native sort indicator.
 +
 
 +
The indicator is acting solely as a decorative feature. (Doesn't have any effect on the sorting).
 +
The indicator has 3 possible values
 +
:'''siNone''' - no sort indicator should be shown
 +
:'''siAscending''' - ascending indicator should be shown
 +
:'''siDescending''' - descending indicator should be shown
 +
The property can work independently of other TListview sorting properties.
 +
 
 +
[[File:autosort0.gif]]
 +
 
 +
2) Add new property '''AutoSortIndicator''' to TListView. The property is intended to be used as a compliment to '''AutoSort''' property.
 +
If both are enabled, LCL code controls the current selection of the column sortindicator according to '''AutoSort''' rules.
 +
 
 +
[[File:autosort2.gif]]
 +
 
 +
==Widgetset Implementation==
 +
ListView is implemented via TWSCustomListViewClassinterface.
 +
{|class="wikitable"
 +
!Method
 +
!Description
 +
|-
 +
|SelectAll
 +
|The method provides a parameter '''AIsSet'''.
 +
 
 +
If the parameter is set to '''true''' then all items should selected in the view.
 +
If it's '''false''' then, all parameters should deselected.
 +
 
 +
It's important that the event shouldn't trigger any events, as LCL will call SelectChange event by itself.
 +
|}
  
 
== See also==
 
== See also==

Revision as of 15:15, 18 May 2020

English (en) français (fr) polski (pl) русский (ru)

TListView tlistview.png is a visible component on the Common Controls tab of the Component Palette that provides a list view of its associated Items. Items can be represented by an icon from each of the associated TImageLists: SmallImages, LargeImages and StateImages.

Notes

  • GetNextItem() requires StartItem to be provided. This is incompatible with Delphi's GetNextItem(), where startItem is allowed to be nil, which will perform the search from the relative (direction driven) start.

Sorting

TODO: add description on how OwnerData affects the sorting

Sorting is (typically?) applied when using vsReport ViewStyle, as it's column driven (with Sortcolumn index required). Sorting might be a time consuming for a larger data scale (when comparison of items takes a considerable time).

SortType is the key property in order to perform any sorting in TListView.

stNone - (the default value) that no sorting should be for the control.
stText - the text of a cells would be used for item comparison. The actual text entry is controlled by SortColumn property. Note the default sorting comparison is actually treats the text as Ansi, rather than UTF8. Thus the result might be undesired for the non-English texts
stData - the default sorting comparison treats Data property as an integer value (by casting pointer to an integer) and sorts the according to value. (in most cases such sorting is useless, unless "Data" is an actual integer casted to the pointer)
stBoth - treated as stText for in the default sorting comparison.

Unless using text sorting, the default comparison method is not the best approach, instead a custom comparison could be used. The custom comparison is assigned with OnCompare event of TListView. The following parameters are passed:

Sender - TListview that's being sorted
Item1 - one TListItem being compared
Item2 - another TListItem being compared to the one
Data - is not used and is always passed as zero. (provided for Delphi compatibility)
Compare - the result of the comparison, that must be populated by the event. The following values should be assigned to the Compare argument.
-1 - if Item1 should show up "earlier" in Ascending order, than Item2. (Item1 is less than Item2)
0 - if two items are equal
1 - if Item2 should show up "earlier" in Ascending order, than Item1. (Item2 is less than Item1)
It's a normal practice to reverse the comparison result value, if SortDirection is descending. I.e.:
procedure TForm1.ListView1OnCompare(Sender: TObject; Item1, Item2: TListItem;
  Data: Integer; var Compare: Integer)
begin
  ... do the comparison...

  if TListView(Sender).SortDirection = sdDescending then
    Compare := -Compare;
end;

The OnCompare event should check for SortType, SortColumn and SortDirection properties of TListView, and do adjust the comparison result respectively of those properties.


Method Sort performs of items, if SortType is other than stNone and SortColumn is assigned to a valid column index.

Method CustomSort performs a one-time sorting using a provided sorting function.

ASortProc: TLVCompare - sorting function
AOptionalParam: PtrInt - sorting parameter

Sorting parameter is ignored (provided for the Delphi compatibility). If ASortProc is passed as nil, then the either sorting OnCompare is used or default sorting.

Typically the sorting can be requested by a user. Whenever a user clicks on a column header, that requires to either sort (initially ascendancy) or to switch to the opposite sorting order (either from ascendant to descendant, or back). It's not a rule, but a common expectation. For some data sets selecting sorting might not make any sense. AutoSort (default value is true)the property of TListview controls, if the listview should be sorted automatically, as soon as user clicks on a column header. AutoSort will have no effect, while SortType is set to stNone.

AlphaSort is a convenience method, that changes the settings to ascending sort (SortDirection=sdAscending) based on the text (SortType=stText) of the first column (SortColumn=0). Note that the actual properties are changed.

Sort Indicator

Originating from: https://bugs.freepascal.org/view.php?id=36281

In trunk since r62567

1) Add a new property SortIndicator to TListViewColumn. The property controls system native sort indicator.

The indicator is acting solely as a decorative feature. (Doesn't have any effect on the sorting). The indicator has 3 possible values

siNone - no sort indicator should be shown
siAscending - ascending indicator should be shown
siDescending - descending indicator should be shown

The property can work independently of other TListview sorting properties.

autosort0.gif

2) Add new property AutoSortIndicator to TListView. The property is intended to be used as a compliment to AutoSort property. If both are enabled, LCL code controls the current selection of the column sortindicator according to AutoSort rules.

autosort2.gif

Widgetset Implementation

ListView is implemented via TWSCustomListViewClassinterface.

Method Description
SelectAll The method provides a parameter AIsSet.

If the parameter is set to true then all items should selected in the view. If it's false then, all parameters should deselected.

It's important that the event shouldn't trigger any events, as LCL will call SelectChange event by itself.

See also


LCL Components
Component Tab Components
Standard TMainMenu • TPopupMenu • TButton • TLabel • TEdit • TMemo • TToggleBox • TCheckBox • TRadioButton • TListBox • TComboBox • TScrollBar • TGroupBox • TRadioGroup • TCheckGroup • TPanel • TFrame • TActionList
Additional TBitBtn • TSpeedButton • TStaticText • TImage • TShape • TBevel • TPaintBox • TNotebook • TLabeledEdit • TSplitter • TTrayIcon • TControlBar • TFlowPanel • TMaskEdit • TCheckListBox • TScrollBox • TApplicationProperties • TStringGrid • TDrawGrid • TPairSplitter • TColorBox • TColorListBox • TValueListEditor
Common Controls TTrackBar • TProgressBar • TTreeView • TListView • TStatusBar • TToolBar • TCoolBar • TUpDown • TPageControl • TTabControl • THeaderControl • TImageList • TPopupNotifier • TDateTimePicker
Dialogs TOpenDialog • TSaveDialog • TSelectDirectoryDialog • TColorDialog • TFontDialog • TFindDialog • TReplaceDialog • TTaskDialog • TOpenPictureDialog • TSavePictureDialog • TCalendarDialog • TCalculatorDialog • TPrinterSetupDialog • TPrintDialog • TPageSetupDialog
Data Controls TDBNavigator • TDBText • TDBEdit • TDBMemo • TDBImage • TDBListBox • TDBLookupListBox • TDBComboBox • TDBLookupComboBox • TDBCheckBox • TDBRadioGroup • TDBCalendar • TDBGroupBox • TDBGrid • TDBDateTimePicker
Data Access TDataSource • TCSVDataSet • TSdfDataSet • TBufDataset • TFixedFormatDataSet • TDbf • TMemDataset
System TTimer • TIdleTimer • TLazComponentQueue • THTMLHelpDatabase • THTMLBrowserHelpViewer • TAsyncProcess • TProcessUTF8 • TProcess • TSimpleIPCClient • TSimpleIPCServer • TXMLConfig • TEventLog • TServiceManager • TCHMHelpDatabase • TLHelpConnector
Misc TColorButton • TSpinEdit • TFloatSpinEdit • TArrow • TCalendar • TEditButton • TFileNameEdit • TDirectoryEdit • TDateEdit • TTimeEdit • TCalcEdit • TFileListBox • TFilterComboBox • TComboBoxEx • TCheckComboBox • TButtonPanel • TShellTreeView • TShellListView • TXMLPropStorage • TINIPropStorage • TJSONPropStorage • TIDEDialogLayoutStorage • TMRUManager • TStrHolder
LazControls TCheckBoxThemed • TDividerBevel • TExtendedNotebook • TListFilterEdit • TListViewFilterEdit • TLvlGraphControl • TShortPathEdit • TSpinEditEx • TFloatSpinEditEx • TTreeFilterEdit • TExtendedTabControl •
RTTI TTIEdit • TTIComboBox • TTIButton • TTICheckBox • TTILabel • TTIGroupBox • TTIRadioGroup • TTICheckGroup • TTICheckListBox • TTIListBox • TTIMemo • TTICalendar • TTIImage • TTIFloatSpinEdit • TTISpinEdit • TTITrackBar • TTIProgressBar • TTIMaskEdit • TTIColorButton • TMultiPropertyLink • TTIPropertyGrid • TTIGrid
SQLdb TSQLQuery • TSQLTransaction • TSQLScript • TSQLConnector • TMSSQLConnection • TSybaseConnection • TPQConnection • TPQTEventMonitor • TOracleConnection • TODBCConnection • TMySQL40Connection • TMySQL41Connection • TMySQL50Connection • TMySQL51Connection • TMySQL55Connection • TMySQL56Connection • TMySQL57Connection • TSQLite3Connection • TIBConnection • TFBAdmin • TFBEventMonitor • TSQLDBLibraryLoader
Pascal Script TPSScript • TPSScriptDebugger • TPSDllPlugin • TPSImport_Classes • TPSImport_DateUtils • TPSImport_ComObj • TPSImport_DB • TPSImport_Forms • TPSImport_Controls • TPSImport_StdCtrls • TPSCustomPlugin
SynEdit TSynEdit • TSynCompletion • TSynAutoComplete • TSynMacroRecorder • TSynExporterHTML • TSynPluginSyncroEdit • TSynPasSyn • TSynFreePascalSyn • TSynCppSyn • TSynJavaSyn • TSynPerlSyn • TSynHTMLSyn • TSynXMLSyn • TSynLFMSyn • TSynDiffSyn • TSynUNIXShellScriptSyn • TSynCssSyn • TSynPHPSyn • TSynTeXSyn • TSynSQLSyn • TSynPythonSyn • TSynVBSyn • TSynAnySyn • TSynMultiSyn • TSynBatSyn • TSynIniSyn • TSynPoSyn
Chart TChart • TListChartSource • TRandomChartSource • TUserDefinedChartSource • TCalculatedChartSource • TDbChartSource • TChartToolset • TChartAxisTransformations • TChartStyles • TChartLegendPanel • TChartNavScrollBar • TChartNavPanel • TIntervalChartSource • TDateTimeIntervalChartSource • TChartListBox • TChartExtentLink • TChartImageList
IPro TIpFileDataProvider • TIpHtmlDataProvider • TIpHttpDataProvider • TIpHtmlPanel
Virtual Controls TVirtualDrawTree • TVirtualStringTree • TVTHeaderPopupMenu