Control : Tree

Page Status: Beta

Jump to: Neue Coins 2023, navigation, search

The Tree control displays data in a hierarchical way.

Examples

The following examples are intended to be used with sample code that you can import into your Bungee Builder workspace from the Start Page. Each example is intended to build upon the previous example to provide you with a complete understanding of how to use this control.

Example 1: Various Objects in a Tree Control (Ex1_Industry)

You can have various types of objects represented in a tree control. This example shows several types (Company, Department, Employee, and Industry) and how each one implements an element connection on the Tree control. This controls how each element is displayed. Because the Tree control is bound to the this field of the Ex1_Industry class, it is required to implement its own tree element connection as well (see its class definition).

Click for larger image

Example 2: Editing in a Tree Control (Ex2_EditIndustry)

You can add the ability to edit within the Tree control. This example adds buttons for removing, adding, and showing elements in the tree. All the elements inherit from Item, which defines the common operations. However, completely different and unrelated types can exist in a tree, in which case, each item would need to handle its own operations, like remove, inspect, new, etc.

Click for larger image

Example Helper Classes

Reference

Supported Types (Control Adapter)

Type

Summary

Object

Any object defined in Bungee Connect can be tied to the Tree control. A common way to "kick off" the tree is to bind the Tree control within a form to the this field of the Object the form is associated with. The Show Root property is useful to control whether or not the top node in the Tree control or just its children are visible initially. Most of the customization and control's power is derived from the element connection adapter that every object's type needs to implement in order for that object to be represented in the Tree control display. There are many control mechanisms that allow you to greatly customize this interaction, as shown in examples as well as the Element connection adapter documentation details found below.

Property Adapters

Name	Summary
Tooltip	Displays the Tooltip as the user moves the mouse within the Tree control area.

Connection Adapters

Name	Default	Summary
Selection	TreeAdapter	Selection control for the Tree. You can respond to selection by end-users as well as set initial selection when bound to an application object.
Element	TreeElementAdapter	Used to control the text to be produced for each item in the Tree as it is associated with the item within the application object.

Connection Adapter: Selection

(Description of how the Connection Adapter works for this control.)

Field Type	Field Name	Description
string	selectedName	The collection type can manage multiple selected sets where each selection is identified with a string name. You can set selectedName to a specific selection that is desired. If selectedName is not set, then default is the selected set name used by the Tree control when setting selection on the collection. Typically, you do not need to set this value; if it is not associated with a value then the default selected set is used.
Object	selected	selected is the currently selected object in the Tree control. This field can be associated (assigned) to a field of your choice in the parent object that contains the root to which the Tree control is connected. This object is a node in the Tree that an end user has just selected; because it can be any node in the tree, it can also be a parent or a child.
Object	selectedParent	selectedParent is the parent object that owns the selected field (described above). This allows you to control the selected item from its parent context when application workflow or logic requires knowing what the parent of the selected item is.
string	selectedPath	selectedPath gives the delimited path to the selected element in the tree. The delimiter is determined by the Delimiter property on the tree editor (its default is "."). The string used at each level in the path is determined by TreeElementConnection properties. First, the path property on the connection is retrieved. If the value return from path is an empty string, and the Label As Path property on the control is set to true, then the label property on the connection is used. For example a path could look like: TopNode.Child2.Leaf4. The selected path can be used to force selection in the tree. For example, if the property is linked to model code, then you can set the path and then the Tree control uses that string to select an element in the tree, expanding out to that element. Note that, when the selectedPath is used by model code to select in the tree, the selectedPathObject is updated as well.
Collection<Object>	selectedPathObjects	selectedPathObject is a collection object that provides the object path to the selected element in the tree. You can also us selectedPathObjects to select into the tree as with the selectedPath property. Note that the selectedPath property is updated when the selectedPathObject is set from model code.

Connection Adapter: Element

Field Type	Field Name	Description
boolean	encodeLabel	encodeLabel indicates to the Tree control that the content of the label needs to be encoded so that it displays properly in the tree. In general, you need to set this to true if you know HTML or characters that need to be encoded for HTML are to be displayed in the label.
string	expand	expand works the same as selectedPath (see above) in the TreeConnection, however it is used more like a command to expand the tree nodes to expose a particular path. The difference is that it is never updated by the control and it does not select the leaf node on the path. To expand all children at a particular level on a node, use a star character as the leaf in the path like this: "MySubNode.*". Note the string begins with the name of the current node (see path below).
boolean	hasChildren	hasChildren is a quick optimization that the element connection implementation can set and that the Tree control checks before traversing into the collection list field that is mapped in this same connection (see list below). Sometimes it can be "expensive" to traverse into the collection list (child list of the current element context) just to see if the Tree control needs to display a (+) expand icon next to the tree node at runtime. For example, the collection on first access may make a Web service call to compute its children and you only intend to perform that function if the end user directly clicks on the (+) to look at those children on-demand. By default (if you do not set this field for this element), the Tree control assumes the node has children, therefore, the first time expand is clicked by the end user, it tries to access the association to the list field (see below). If the list results in an empty collection, then the expand icon hint is removed from the node (unless an item is added to the list during the life of the element connection on the control).
Data	icon	icon represents the image to display to the left of the label text for the node. icon can obtain its value from many sources as per the intrinsic capability of the connection machinery. Some examples are, 1) you can set the value to a static reference to an image, 2) the image could be computed at runtime by defining model/view logic to set this field, and 3) the image could be a reference found on the object to which this node is tied. The value of this field could also could be a ValueImageSet, which defines a set of image mappings to values. If this is the case, then the iconValue property is used to determine what image mapping to use for the elements icon.
Data	iconValue	iconValue is used to determine what icon/image to pick out of an icon property if its type is a ValueImageSet.
string	label	label is the value used by the Tree control for displaying each item from the primitive or Object collection types. The element connection adapter comes into play only when the control adapter detects a collection type on the model side (the application object collection member tied to the Tree control). For complex Object collections, each element in the collection is “connected” through the element connection adapter in order to extract the correct association to the label field. For example, many different subclasses of Object can implement custom connections of the same adapter type.
Collection<Object>	list	list is the list the Tree control uses to access the children objects for the node during an expand in the Tree. The easiest way to use this field is to associate it with a collection field of the object this element represents. In addition, this collection can actually be computed and/or created on the fly and set without any collection representation on the object at all. You can use the list to represent a collection on the element object and use the list to modify the order of the elements or even filter out items. You could then set the modified collection on this field.
string	path	path is used by the selectedPath property on TreeConnection to build the delimited path that is set on selectedPath. NOTE: if the path is not specified and the Tree control property Label as Path is set to true, than the label is used instead of path.
boolean	showContextMenu	showContextMenu allows the user to have ability for right-clicking on a particular element in a tree turned off or on.
string	toolTip	toolTip displays a Tooltip text for every node in the Tree control that sets this value in its respective element connection implementation.

Function Adapters

Name	Default	Summary
Double Click On Element	<not set>	The Double Click function adapter on the application object is called when a user double-clicks an item in the Tree control. No attempt is made to call the Double Click function adapter on the model object if the adapter is <not set> for this property.
Double Click On Root	<not set>	The Double Click function adapter on the application object is called when a user double-clicks the root for the Tree control. No attempt is made to call the Double Click function adapter on the model object if the adapter is <not set> for this property.
Drag Function	<not set>	The Drag Function function adapter on the application object is called when an end user drags an item into the Tree. No attempt is made to call the Drag Function function adapter on the model object if the adapter is <not set> for this property. See the DragDrop API docs for more details on the single argument passed into this function as well as Understanding Drag-and-Drop.
Expand State	<not set>	The Expand function adapter on the application object is called when an element in the tree is expanded.
Remove	<not set>	The Remove function adapter on the application object is called when a user presses the Delete key on a selected item in the Tree control. Unless the specified function adapter is defined on that element, it tries to call it on the root object in the tree.

Function Adapter: Double Click On Element

Field Type	Field Name	Description
No arguments		The Double Click function is called on the object node that was double-clicked, so there are no arguments.

Function Adapter: Double Click On Root

Field Type	Field Name	Description
Data	parent	parent is the parent of the element that was double-clicked. Note: For the root, the parent is NULL.
Data	item	item is the item that was double clicked.
int	index	index is the index of the item in the parent child collection.

Function Adapter: Drag Function

Field Type	Field Name	Description
DragDrop	data	You can use the Tree control’s space to allow drag-and-drop interactions. See DragDropAdapter API and Understanding Drag-and-Drop for more details.

Function Adapter: Expand State

Field Type	Field Name	Description
boolean	isExpanded	isExpaned indicates whether or not the element has just been expanded.

Function Adapter: Remove

Field Type	Field Name	Description
string	selectedName	selectedName is the name of the selected set involved in this item removal. selectedName allows the function to differentiate between selected sets when deciding to remove an item from the Model side of the connection (the application object collection).
boolean	shiftKeyDown	shiftKeyDown indicates to the function that the user intends to permanently remove the item, not just remove it from the current collection. It is up to you (as the implementer of the function adapter of the application object) to decide whether to remove the item from the selectedName set from the collection. You can query the collection (with the selectedName) for the item(s) involved in that selected set (see Collection).

Associated Properties

Common Properties Index

Specialized Properties

Unique Properties

None

Retrieved from "http://docs.bungeeconnect.com/wiki/index.php/Control_:_Tree"

Control : Tree

Contents