TTreeNode.CustomSort Method

Triggers node sorting.

Pascal

function CustomSort(SortProc: TTVCompare; Data: Longint; ARecurse: Boolean = False): Boolean;

C++

__fastcall Boolean CustomSort(TTVCompare SortProc, Longint Data, Boolean ARecurse = False);

Description

CustomSort triggers node sorting or resorting of the node's child nodes, using a comparison routine indicated by the SortProc parameter.

The Data parameter provides a way to pass information to a customized comparison routine. The CustomSort method and the default comparison routine do not use Data.

The optional ARecurse parameter (default False) specifies that sorting should recursively descend the node tree and sort each subtree in turn.

The Return Value of CustomSort indicates the success status of the sort.

If SortProc is nil (Delphi) or NULL (C++), a default comparison routine is used. The default routine uses the OnCompare event handler for the associated TCustomTreeview object, if defined. If the OnCompare event handler is not defined, the default routine uses a simple case-sensitive comparison of node captions.

The comparison routine is defined like this:

Copy Code

Pascal
         TTVCompare = function(lParam1, lParam2, lParamSort: Longint): Integer;
         
         C++
         typedef int (CALLBACK *TTVCompare)(LPARAM lParam1, LPARAM lParam2, LPARAM lParamSort);

The lParam1 and lParam2 parameters refer to two nodes when cast to TTreeNode.

The lParamSort parameter is the value previously passed in the Data parameter of CustomSort.

The Return Value of the comparison routine indicates the relative sort order of IParam1 and IParam2.

Return Value	Meaning
< 0	IParam1 comes before IParam2.
0	IParam1 and IParam2 are equivalent.
> 0	IParam2 comes before IParam1.

To sort the top-level nodes, use the CustomSort method of TTreeNodes.

Note: The CustomSort does not work if the value of SortType is stNone.

C++ Examples:

Copy Code

/*
This example shows how to use the CustomSort method to order
a subtree in case-insensitive alphabetical order (either
forward or backward). The callback function CompareFunc
below calls the global AnsiStrIComp function to perform the
actual comparison.  This example requires two buttons and a
populated TreeView.
*/
int CALLBACK CompareFunc(long lParam1, long lParam2, long Reverse)
{
  TTreeNode *Node1 = reinterpret_cast<TTreeNode *>(lParam1);
  TTreeNode *Node2 = reinterpret_cast<TTreeNode *>(lParam2);
  if ((Node1 == NULL) || (Node2 == NULL)) return 0;
  int GT = AnsiStrIComp(Node1->Text.c_str(), Node2->Text.c_str());
  if (Reverse)
    return -GT;
  return GT;
}

/*
This procedure can then be used as a parameter to CustomSort
to sort the nodes of the tree view.  To sort in ascending
order, call:
*/

#include <CommCtrl.hpp>

void __fastcall TForm1::Button1Click(TObject *Sender)
{
  TTreeNode *node = TreeView1->Selected;
  node->CustomSort(CompareFunc, 0); // Sorts in ascending order
}

void __fastcall TForm1::Button2Click(TObject *Sender)
{
  TTreeNode *node = TreeView1->Selected;
  node->CustomSort(CompareFunc, 1); // Sorts in descending order
}

Delphi Examples:

Copy Code

{
This example shows how to use the CustomSort method to order
a subtree in case-insensitive alphabetical order (either
forward or backward). The callback function CompareFunc
below calls the global AnsiStrIComp function to perform the
actual comparison.  This example requires two buttons and a
populated TreeView. Customsort only operates on the subtree
of the selected node.
}
function CustomSortProc(Node1, Node2: TTreeNode; Data: Longint): Integer; stdcall;
var val: Integer;
begin
  if Data = 0 then
    val := AnsiStrIComp(Pchar(Node1.Text), PChar(Node2.Text))
  else
    val := -AnsiStrIComp(PChar(Node1.Text), PChar(Node2.Text));
  Exit(val);
end;

{
This procedure can then be used as a parameter to CustomSort
to sort the children of a node:
}

procedure TForm1.Button1Click(Sender: TObject);
var node: TTreeNode;
begin
  node := TreeView1.Selected;
  node.CustomSort(@CustomSortProc, 0);  { Sorts in ascending order }
end;

procedure TForm1.Button2Click(Sender: TObject);
var node: TTreeNode;
begin
  node := TreeView1.Selected;
  node.CustomSort(@CustomSortProc, 1);  { Sorts in descending order }
end;