ClientData Attribute
Data Type: Object
4GL Access: RW
The ClientData attribute of the Object class provides a way to associate data with an object. The ClientData attribute has many potential uses.
For example, suppose that you have a frame containing a TreeviewField and that you want to associate an instance of a userclass, NodeInfo, with each node of the underlying Tree object.
The following example illustrates use of the ClientData attribute. The procedure add_node_to_tree shows how you can attach a NodeInfo object to a tree node. The procedure get_node_info shows how you can retrieve data stored in the ClientData attribute.
declare
add_node_to_tree = procedure returning TreeNode;
get_node_info = procedure returning NodeInfo;
enddeclare
...
procedure add_node_to_tree
(
t = Tree,
node_name = varchar(256) not null, /* Name of new node */
relative_node = TreeNode, /* Relative in tree */
relation = integer not null, /* Relation to relative */
info = NodeInfo /* A NodeInfo object */
) =
declare
node = TreeNode
enddeclare
{
node = t.AddNode
(
name = node_name,
relative = relative_node,
relation = relation
);
if (node is not null) then
node.ClientData = info;
endif;
return node;
}
procedure get_node_info
(
node = TreeNode
) =
{
/*
** Since node.ClientData is an Object, it must
** be cast to a NodeInfo object.
*/
return NodeInfo(node.ClientData);
}
Note: When you duplicate an object using the
Duplicate Method, OpenROAD does not duplicate the object that the ClientData attribute points to. Instead, the ClientData attribute of the new object points to the ClientData object that is attached to the original object. If this is acceptable, then nothing further needs to be done. However, if you need to change the ClientData object of the new object without affecting the ClientData object of the original object, you must duplicate the ClientData object.
The following example illustrates the difference:
Procedure copy_node
(
old_node = TreeNode
) =
declare
new_node = TreeNode;
enddeclare
{
new_node = old_node.Duplicate();
/*
** The ClientData attribute of new-node
** points to the ClientData attribute of
** old_node.
*/
new_node.ClientData = old_node.ClientData.Duplicate();
/*
** new_node now has its own ClientData object.
*/
return new_node;
}