{
* This Source Code Form is subject to the terms of the Mozilla Public License,
* v. 2.0. If a copy of the MPL was not distributed with this file, You can
* obtain one at http://mozilla.org/MPL/2.0/
*
* Copyright (C) 2006-2012, Peter Johnson (www.delphidabbler.com).
*
* $Rev$
* $Date$
*
* Implements a frame containing a treeview that has check boxes associated with
* tree nodes and updates parent check boxes according to state of child nodes.
}
unit FrCheckedTV;
interface
uses
// Delphi
ImgList, Controls, Classes, ComCtrls, StdCtrls, Forms,
// Project
UKeysHelper, UTVCheckBoxes;
type
{
TCheckedTreeNode:
Custom tree node class that has an associated check box that can appear
checked, unchecked and greyed in either hot or normal state.
}
TCheckedTreeNode = class(TTreeNode)
strict private
fHot: Boolean; // Value of Hot property
procedure SetImage(const ImgIdx: Integer);
{Sets node's image. ImageIndex and SelectedImageIndex properties are set
to same value.
@param ImgIdx [in] Required image index.
}
function GetCheck: TCheckBoxState;
{Read accessor for Check property. Calculates value from ImageIndex.
@return Current property value.
}
procedure SetCheck(const Value: TCheckBoxState);
{Write accessor for Check property. Updates node's image.
@param Value [in] New property value.
}
procedure SetHot(const Value: Boolean);
{Write accessor for Hot property. Updates node's image.
@param Value [in] New value of property.
}
function GetParent: TCheckedTreeNode;
{Read accessor for Parent property.
@return Value of Parent property.
}
function GetTopLevelParent: TCheckedTreeNode;
{Read accessor for TopLevelParent property.
@return Reference to top level parent node or Self if node has no parent.
}
public
function IsChecked: Boolean;
{Checks if node is checked.
@return True if node is checked.
}
function IsUnchecked: Boolean;
{Checks if node is unchecked.
@return True if node is unchecked.
}
function HasParent: Boolean;
{Checks if node has a parent node.
@return True if node has parent.
}
function GetNextSibling: TCheckedTreeNode;
{Gets reference to node's next sibling.
@return Reference to next sibling or nil if no more siblings.
}
function GetFirstChild: TCheckedTreeNode;
{Gets reference to a node's first child node.
@return Reference to child node or nil if no child nodes.
}
procedure ToggleCheck;
{Toggles node's check box off if currently checked or greyed or on if
currently unchecked.
}
property Parent: TCheckedTreeNode read GetParent;
{Node's parent or nil if node has no parent. This is a re-implementation
of inherited property}
property TopLevelParent: TCheckedTreeNode read GetTopLevelParent;
{Top level parent of node. Self if node is a top level node}
property Check: TCheckBoxState read GetCheck write SetCheck;
{State of node's associated checkbox image}
property Hot: Boolean read fHot write SetHot;
{Whether node's associated checkbox is "hot" or not}
end;
{
TCheckedTVFrame:
Abstract frame base class containing a treeview that has check boxes
associated with tree nodes and updates parent check boxes according to state
of child nodes.
}
TCheckedTVFrame = class(TFrame)
ilChecks: TImageList;
tvChecked: TTreeView;
procedure FrameEnter(Sender: TObject);
procedure tvCheckedCollapsing(Sender: TObject; Node: TTreeNode;
var AllowCollapse: Boolean);
procedure tvCheckedKeyPress(Sender: TObject; var Key: Char);
procedure tvCheckedMouseDown(Sender: TObject; Button: TMouseButton;
Shift: TShiftState; X, Y: Integer);
procedure tvCheckedMouseMove(Sender: TObject; Shift: TShiftState; X,
Y: Integer);
procedure tvCheckedCreateNodeClass(Sender: TCustomTreeView;
var NodeClass: TTreeNodeClass);
strict private
fOnChange: TNotifyEvent; // Event handler for OnChange event
fCanCollapse: Boolean; // Value of CanCollapse property
fTVChecks: TTVCheckBoxes; // Object that manages check box image lists
fHotNode: TCheckedTreeNode; // Tree node currently under mouse cursor
procedure SetCanCollapse(Flag: Boolean);
{Write access method for CanCollapse property.
@param Flag [in] New property value.
}
procedure MakeHotNode(const Node: TCheckedTreeNode);
{Makes a node's check box appear "hot". Sets any previous hot check box
back to normal state.
@param Node [in] Node whose check box to appear hot.
}
procedure SetParentStatesFromChildren(Node: TCheckedTreeNode);
{Sets state of a node parent, grandparent etc nodes according to state of
node and its siblings. Parent nodes are checked if all children are
checked, unchecked if all children unchecked and greyed if children have
mixed states.
@param Node [in] Node whose parent states are to be updated.
}
procedure SetParentStates;
{Sets state of all parent nodes according to state of their child nodes.
Parent nodes are checked if all children are checked, unchecked if all
children unchecked and greyed if children have mixed states.
}
procedure CopyParentStateToChildren(ParentNode: TCheckedTreeNode);
{Copies state of check box of parent node to all its child nodes and
children's child nodes.
@param ParentNode [in] Parent node whose state is to be copied.
}
procedure PopulateTreeView;
{Populates treeview with required nodes.
}
procedure ToggleNode(const Node: TCheckedTreeNode);
{Toggles checked state of a node and updates parent or child nodes
accordingly. Changed are recorded and OnChange event triggered.
@param Node [in] Node whose check state is to be toggled.
}
procedure CheckBoxChangeHandler(Sender: TObject);
{Handles TTVCheckBoxes.OnChange event triggered when appearance of check
boxes changes. Refreshes tree view.
@param Sender [in] Not used.
}
strict protected
procedure AddNodes; virtual; abstract;
{Called when tree view is to be populated with nodes.
}
procedure SetLeafNodeState(const Node: TCheckedTreeNode); virtual; abstract;
{Called to get checked state of a leaf node when tree view's underlying
data changes. Implementor should set node's check state.
@param Node [in] Node to have check state set.
}
procedure RecordChanges; virtual; abstract;
{Called when state of treeview changes to enable tree view's underlying
data to be changed.
}
function AddNode(const Parent: TCheckedTreeNode; const Text: string;
const Data: Pointer): TCheckedTreeNode;
{Adds new unchecked tree node. This method can be called from descendant
classes to add new nodes to tree from their implementation of the AddNodes
method.
@param Parent [in] Parent of new node or nil if new node is top level.
@param Text [in] Text to display in new node.
@param Data [in] User defined data assoicated with new node.
@return Reference to new node.
}
function FirstNode: TCheckedTreeNode;
{Gets reference to first top level node in tree view.
@return Node reference.
}
procedure UpdateTreeViewState;
{Updates check boxes of each node in treeview. Child nodes state is
requested and parent node are set according to state of child nodes.
}
procedure DataChanged;
{Notifies that state of tree view's underlying data has changed. Leaf node
state is requested and parent node states are set accroding to state of
child nodes.
}
procedure DoChanged;
{Triggers OnChange event.
}
public
constructor Create(AOwner: TComponent); override;
{Class constructor. Sets up object and populates tree view.
@param AOwner [in] Component that owns this frame.
}
destructor Destroy; override;
{Class destructor. Tears down object.
}
procedure ExpandTree;
procedure CollapseTree;
property CanCollapse: Boolean
read fCanCollapse write SetCanCollapse default False;
{Determines whether tree nodes can be collapsed. Also switches on buttons
for user to use to make nodes expand and collapse}
property OnChange: TNotifyEvent
read fOnChange write fOnChange;
{Event triggered when state of a tree node changes}
end;
implementation
uses
// Delphi
SysUtils;
{$R *.dfm}
{ TCheckedTVFrame }
function TCheckedTVFrame.AddNode(const Parent: TCheckedTreeNode;
const Text: string; const Data: Pointer): TCheckedTreeNode;
{Adds new unchecked tree node. This method can be called from descendant
classes to add new nodes to tree from their implementation of the AddNodes
method.
@param Parent [in] Parent of new node or nil if new node is top level.
@param Text [in] Text to display in new node.
@param Data [in] User defined data assoicated with new node.
@return Reference to new node.
}
begin
Result := tvChecked.Items.AddChild(Parent, Text) as TCheckedTreeNode;
Result.Data := Data;
Result.Check := cbUnchecked;
end;
procedure TCheckedTVFrame.CheckBoxChangeHandler(Sender: TObject);
{Handles TTVCheckBoxes.OnChange event triggered when appearance of check boxes
changes. Refreshes tree view.
@param Sender [in] Not used.
}
begin
tvChecked.Refresh;
end;
procedure TCheckedTVFrame.CollapseTree;
begin
if not fCanCollapse then
Exit;
tvChecked.Items.BeginUpdate;
try
tvChecked.FullCollapse;
if Assigned(tvChecked.Selected) then
tvChecked.Selected.MakeVisible;
finally
tvChecked.Items.EndUpdate;
end;
end;
procedure TCheckedTVFrame.CopyParentStateToChildren(
ParentNode: TCheckedTreeNode);
{Copies state of check box of parent node to all its child nodes and
children's child nodes.
@param ParentNode [in] Parent node whose state is to be copied.
}
var
ChildNode: TCheckedTreeNode; // reference to each of parent's child nodes
begin
ChildNode := ParentNode.GetFirstChild;
while Assigned(ChildNode) do
begin
ChildNode.Check := ParentNode.Check;
CopyParentStateToChildren(ChildNode);
ChildNode := ChildNode.GetNextSibling;
end;
end;
constructor TCheckedTVFrame.Create(AOwner: TComponent);
{Class constructor. Sets up object and populates tree view.
@param AOwner [in] Component that owns this frame.
}
begin
inherited;
fTVChecks := TTVCheckBoxes.Create(ilChecks);
fTVChecks.OnChange := CheckBoxChangeHandler;
PopulateTreeView;
end;
procedure TCheckedTVFrame.DataChanged;
{Notifies that state of tree view's underlying data has changed. Leaf node
state is requested and parent node states are set accroding to state of child
nodes.
}
// ---------------------------------------------------------------------------
procedure SetLeafNodeStates(const Node: TCheckedTreeNode);
{Recursively sets state of leaf nodes.
@param Node [in] Node to process. If Node is leaf node its state is
requested. If Node is a parent we set state of its child nodes
recursively.
}
var
ChildNode: TCheckedTreeNode; // reference to each child of node
begin
if Node.HasChildren then
begin
ChildNode := Node.GetFirstChild;
while Assigned(ChildNode) do
begin
SetLeafNodeStates(ChildNode);
ChildNode := ChildNode.GetNextSibling;
end;
end
else
SetLeafNodeState(Node);
end;
// ---------------------------------------------------------------------------
var
Node: TCheckedTreeNode; // reference to each top level node
begin
// Loop through all top level nodes setting their leaf node states
Node := FirstNode;
while Assigned(Node) do
begin
SetLeafNodeStates(Node);
Node := Node.GetNextSibling;
end;
// Set state of parent nodes based on state of leaf node
SetParentStates;
// Notify that tree view has (may have) changed
DoChanged;
end;
destructor TCheckedTVFrame.Destroy;
{Class destructor. Tears down object.
}
begin
FreeAndNil(fTVChecks);
inherited;
end;
procedure TCheckedTVFrame.DoChanged;
{Triggers OnChange event.
}
begin
if Assigned(fOnChange) then
fOnChange(Self);
end;
procedure TCheckedTVFrame.ExpandTree;
begin
if not fCanCollapse then
Exit;
tvChecked.Items.BeginUpdate;
try
tvChecked.FullExpand;
if Assigned(tvChecked.Selected) then
tvChecked.Selected.MakeVisible;
finally
tvChecked.Items.EndUpdate;
end;
end;
function TCheckedTVFrame.FirstNode: TCheckedTreeNode;
{Gets reference to first top level node in tree view.
@return Node reference.
}
begin
Result := tvChecked.Items.GetFirstNode as TCheckedTreeNode;
end;
procedure TCheckedTVFrame.FrameEnter(Sender: TObject);
{Handles event triggered when frame is entered. Moves focus to contained tree
view.
@param Sender [in] Not used.
}
begin
if Assigned(tvChecked) then
tvChecked.SetFocus;
end;
procedure TCheckedTVFrame.MakeHotNode(const Node: TCheckedTreeNode);
{Makes a node's check box appear "hot". Sets any previous hot check box back
to normal state.
@param Node [in] Node whose check box to appear hot.
}
begin
if Node <> fHotNode then
begin
if Assigned(fHotNode) then
fHotNode.Hot := False;
if Assigned(Node) then
Node.Hot := True;
fHotNode := Node;
end;
end;
procedure TCheckedTVFrame.PopulateTreeView;
{Populates treeview with required nodes.
}
begin
// Get descendant to add nodes to tree view
AddNodes;
// Expand treeview and display top of tree
tvChecked.FullExpand;
if FirstNode <> nil then
FirstNode.MakeVisible;
end;
procedure TCheckedTVFrame.SetCanCollapse(Flag: Boolean);
begin
if fCanCollapse = Flag then
Exit;
tvChecked.ShowRoot := Flag;
tvChecked.ShowButtons := Flag;
fCanCollapse := Flag;
end;
procedure TCheckedTVFrame.SetParentStates;
{Sets state of all parent nodes according to state of their child nodes.
Parent nodes are checked if all children are checked, unchecked if all
children unchecked and greyed if children have mixed states.
}
var
Node: TCheckedTreeNode; // references each of top level tree nodes
begin
Node := FirstNode;
while Assigned(Node) do
begin
SetParentStatesFromChildren(Node);
Node := Node.GetNextSibling;
end;
end;
procedure TCheckedTVFrame.SetParentStatesFromChildren(
Node: TCheckedTreeNode);
{Sets state of a node parent, grandparent etc nodes according to state of node
and its siblings. Parent nodes are checked if all children are checked,
unchecked if all children unchecked and greyed if children have mixed states.
@param Node [in] Node whose parent states are to be updated.
}
var
ChildNode: TCheckedTreeNode; // references child nodes of node
CheckedChildCount: Integer; // count of checked child nodes
UnCheckedChildCount: Integer; // count of unchecked child nodes
begin
// If child node do nothing
if not Node.HasChildren then
Exit;
// We have parent node
// count nodes checked and unchecked children (some may be grey)
CheckedChildCount := 0;
UnCheckedChildCount := 0;
ChildNode := Node.GetFirstChild;
while Assigned(ChildNode) do
begin
if ChildNode.HasChildren then
// child is itself a parent: update its check state recursively
SetParentStatesFromChildren(ChildNode);
if ChildNode.IsChecked then
Inc(CheckedChildCount)
else if ChildNode.IsUnchecked then
Inc(UncheckedChildCount);
ChildNode := ChildNode.GetNextSibling;
end;
// Set state of node according to checked / unchecked count
if UncheckedChildCount = Node.Count then
Node.Check := cbUnchecked
else if CheckedChildCount = Node.Count then
Node.Check := cbChecked
else
Node.Check := cbGrayed;
end;
procedure TCheckedTVFrame.ToggleNode(const Node: TCheckedTreeNode);
{Toggles checked state of a node and updates parent or child nodes
accordingly. Changed are recorded and OnChange event triggered.
@param Node [in] Node whose check state is to be toggled.
}
begin
Assert(Assigned(Node), ClassName + '.ToggleNode: Node is nil');
Node.ToggleCheck;
if Node.HasChildren then
CopyParentStateToChildren(Node);
if Node.HasParent then
SetParentStatesFromChildren(Node.TopLevelParent);
// Refresh tree view display to display revised glyphs
tvChecked.Refresh;
// Update data from selections
RecordChanges;
// Trigger OnChange event
DoChanged;
end;
procedure TCheckedTVFrame.tvCheckedCollapsing(Sender: TObject;
Node: TTreeNode; var AllowCollapse: Boolean);
{Handler for tree view's OnCollapsing event. Prevents tree from being
collapsed.
@param Sender [in] Not used.
@param Node [in] Not used.
@param AllowCollapse [in/out] Whether collapsing allowed. Set to false.
}
begin
AllowCollapse := fCanCollapse;
end;
procedure TCheckedTVFrame.tvCheckedCreateNodeClass(
Sender: TCustomTreeView; var NodeClass: TTreeNodeClass);
{Handler for tree view's OnCreateNodeClass event. Passes back custom tree node
class to use when creating tree nodes.
@param Sender [in] Not used.
@param NodeClass [in/out] Set to required tree node class type.
}
begin
NodeClass := TCheckedTreeNode;
end;
procedure TCheckedTVFrame.tvCheckedKeyPress(Sender: TObject;
var Key: Char);
{Handles key presses on tree view. If space is pressed check state of selected
node is toggled. All other keypressed are inhibited to prevent initial
characters from changing selection.
@param Sender [in] Not used.
@param Key [in/out] Stores pressed key when called. Set to #0 to inhibit
further processing.
}
begin
if (Key = ' ') and Assigned(tvChecked.Selected) then
ToggleNode(tvChecked.Selected as TCheckedTreeNode);
Key := #0; // inhibits selection of entries when intial letter pressed
end;
procedure TCheckedTVFrame.tvCheckedMouseDown(Sender: TObject;
Button: TMouseButton; Shift: TShiftState; X, Y: Integer);
{Handles mouse clicks on treeview. Unmodified mouse down events are used to
toggle check state of tree nodes. Clicks outside nodes are ignored.
@param Sender [in] Not used.
@param Button [in] Mouse button pressed. We only accept left button.
@param Shift [in] Shift and button state. We only accept unmodified clicks.
@param X [in] X co-ordinate of mouse click.
@param Y [in] Y co-ordinate of mouse click.
}
var
SelNode: TCheckedTreeNode; // reference to currently selected tree node
HitTestInfo: THitTests; // info about where in treeview mouse pressed
begin
SelNode := tvChecked.GetNodeAt(X, Y) as TCheckedTreeNode;
HitTestInfo := tvChecked.GetHitTestInfoAt(X, Y);
if (htOnIcon in HitTestInfo) and (Button = mbLeft)
and not HasShiftKeys(Shift) and Assigned(SelNode) then
ToggleNode(SelNode);
end;
procedure TCheckedTVFrame.tvCheckedMouseMove(Sender: TObject;
Shift: TShiftState; X, Y: Integer);
{Handler for tree view's OnMouseMove event. Sets check box of any node under
the mouse to hot state.
@param Sender [in] Not used.
@param Shift [in] Not used.
@param X [in] X coordinate of mouse.
@param Y [in] Y coordinate of mouse.
}
var
SelNode: TCheckedTreeNode; // reference to currently selected tree node
HitTestInfo: THitTests; // info about where in treeview mouse pressed
begin
HitTestInfo := tvChecked.GetHitTestInfoAt(X, Y);
if (htOnItem in HitTestInfo) then
SelNode := tvChecked.GetNodeAt(X, Y) as TCheckedTreeNode
else
SelNode := nil;
MakeHotNode(SelNode);
end;
procedure TCheckedTVFrame.UpdateTreeViewState;
{Updates check boxes of each node in treeview. Child nodes state is requested
and parent node are set according to state of child nodes. Should be called
when state of data represented in tree view changes.
}
procedure SetLeafNodeStates(const Node: TCheckedTreeNode);
{Recursively sets state of leaf nodes.
@param Node [in] Node to process. If Node is leaf node its state is
requested. If Node is a parent we set state of its child nodes
recursively.
}
var
ChildNode: TCheckedTreeNode; // reference to each child of node
begin
if Node.HasChildren then
begin
ChildNode := Node.GetFirstChild;
while Assigned(ChildNode) do
begin
SetLeafNodeStates(ChildNode);
ChildNode := ChildNode.GetNextSibling;
end;
end
else
SetLeafNodeState(Node);
end;
var
Node: TCheckedTreeNode; // reference to each top level node
begin
// Loop through all top level nodes setting their leaf node states
Node := FirstNode;
while Assigned(Node) do
begin
SetLeafNodeStates(Node);
Node := Node.GetNextSibling as TCheckedTreeNode;
end;
// Set state of parent nodes based on state of leaf node
SetParentStates;
// Notify that tree view has (may have) changed
DoChanged;
end;
{ TCheckedTreeNode }
function TCheckedTreeNode.GetCheck: TCheckBoxState;
{Read accessor for Check property. Calculates value from ImageIndex.
@return Current property value.
}
begin
Result := TTVCheckBoxes.ImageIdxToCheckState(Self.ImageIndex);
end;
function TCheckedTreeNode.GetFirstChild: TCheckedTreeNode;
{Gets reference to a node's first child node.
@return Reference to child node or nil if no child nodes.
}
begin
// This method simply casts first child from TTreeNode to TCheckedTreeNode
Result := inherited GetFirstChild as TCheckedTreeNode;
end;
function TCheckedTreeNode.GetNextSibling: TCheckedTreeNode;
{Gets reference to node's next sibling.
@return Reference to next sibling or nil if no more siblings.
}
begin
// This method simply casts next sibling from TTreeNode to TCheckedTreeNode
Result := inherited GetNextSibling as TCheckedTreeNode;
end;
function TCheckedTreeNode.GetParent: TCheckedTreeNode;
{Read accessor for Parent property.
@return Value of parent property.
}
begin
// This method simply converts Parent from TTreeNode to TCheckedTreeNode
Result := inherited Parent as TCheckedTreeNode;
end;
function TCheckedTreeNode.GetTopLevelParent: TCheckedTreeNode;
{Read accessor for TopLevelParent property.
@return Reference to top level parent node or Self if node has no parent.
}
begin
if not HasParent then
Result := Self
else
Result := Parent.TopLevelParent;
end;
function TCheckedTreeNode.HasParent: Boolean;
{Checks if node has a parent node.
@return True if node has parent.
}
begin
Result := Assigned(Parent);
end;
function TCheckedTreeNode.IsChecked: Boolean;
{Checks if node is checked.
@return True if node is checked.
}
begin
Result := Check = cbChecked;
end;
function TCheckedTreeNode.IsUnchecked: Boolean;
{Checks if node is unchecked.
@return True if node is unchecked.
}
begin
Result := Check = cbUnchecked;
end;
procedure TCheckedTreeNode.SetCheck(const Value: TCheckBoxState);
{Write accessor for Check property. Updates node's image.
@param Value [in] New property value.
}
begin
SetImage(TTVCheckBoxes.CheckImageIdx(Value, Hot));
end;
procedure TCheckedTreeNode.SetHot(const Value: Boolean);
{Write accessor for Hot property. Updates node's image.
@param Value [in] New value of property.
}
begin
if fHot <> Value then
begin
fHot := Value;
SetImage(TTVCheckBoxes.CheckImageIdx(GetCheck, Value));
end;
end;
procedure TCheckedTreeNode.SetImage(const ImgIdx: Integer);
{Sets node's image. ImageIndex and SelectedImageIndex properties are set to
same value.
@param ImgIdx [in] Required image index.
}
begin
ImageIndex := ImgIdx;
SelectedIndex := ImgIdx;
end;
procedure TCheckedTreeNode.ToggleCheck;
{Toggles node's check box off if currently checked or greyed or on if
currently unchecked.
}
begin
case Check of
cbChecked, cbGrayed: Check := cbUnchecked;
cbUnchecked: Check := cbChecked;
end;
end;
end.
