Class: Tree

Tree(client, oOptionsopt)

new Tree(client, oOptionsopt)

The ExTree/JS component allows you to display and edit hierarchical-data. Features include:
  • Multiple-Columns
  • Multiple-Views
  • Drag and Drop
  • Group-By
  • Filter-Prompt
  • Conditional-Format
  • Total Fields
  • and much more
The ExTree/JS is a HTML standalone-component, written in JavaScript, that uses no third-party libraries.

Every option of the Tree.Options type has associated a property of the control. For instance, the option:

allowActions {string}, customizes the actions the user can perform once the user clicks or touches the control
is associated with the property:
AllowActions {string}, customizes the actions the user can perform once the user clicks or touches the control
which means that the following statements are equivalent:
oTree.Options = {allowActions: "scroll"}
oTree.SetOptions({allowActions: "scroll"})
oTree.AllowActions = "scroll"
oTree.SetAllowActions("scroll")
where oTree is an object of Tree type
Parameters:
Name Type Attributes Description
client any The client parameter indicates the control's client area as:
  • array of [x,y,width,height] type that specifies the control's client area
  • string, that specifies the identifier of the canvas within the document, so the canvas's client area becomes the control's client area
  • HTMLCanvasElement, that specifies the identifier of the canvas within the document, so the canvas's client area becomes the control's client area
oOptions object <optional>
 An object of Tree.Options type that defines different options to display the control.
Requires:
  • module:exontrol.commmon.min.js
  • module:exontrol.menu.min.js

Requires

  • module:exontrol.commmon.min.js
  • module:exontrol.menu.min.js

Classes

Options

Members

Listeners :exontrol.Lts

The Listeners field defines the events of the control, as an object of exontrol.Lts type. The exontrol.Lts type supports forEach(callback, thisArg) method that helps you to enumerate the events the control supports. The Events section lists the events the component supports.
Type:
  • exontrol.Lts
Example
The following sample shows how you can get all events the component currently supports:

oTree.Listeners.forEach(function(name)
{
 console.log(name);
});

The following sample displays information about the item being clicked:

oTree.Listeners.Add("onclick", function (oEvent)
{
 console.log(oEvent);
});

where oTree is an object of Tree type

Shortcuts :exontrol.Sts

The Shortcuts field defines the shortcuts of the control, as an object of exontrol.Sts type. In order to provide keyboard support for the component, the owner <canvas> element must include the tabIndex attribute, as <canvas ... tabIndex="0">. You can associated a function or a callback to any shortcut.
Type:
  • exontrol.Sts
Example
The following sample removes the selection (calls the RemoveSelection() method) once the user presses the Delete key:

oTree.Shortcuts.Add( "Delete", oTree.RemoveSelection, oTree );

where oTree is an object of Tree type

oTV :TV

The oTV field defines the base tree-view of control. Use the AddTreeView() method to add a new view to the control. Use the RemoveTreeView() method removes a tree-view already created by AddTreeView() method.
Type:

(static, readonly) ColumnsFloatBarVisibleEnum :number

The Tree.ColumnsFloatBarVisibleEnum type indicates the type of columns, the columns floatbar can display
Type:
  • number
Properties:
Name Type Description
exColumnsFloatBarHidden number The columns floatbar is hidden
exColumnsFloatBarVisible number The columns floatbar is visible (inside and anchored to the right-side of the control)
exColumnsFloatBarVisibleIncludeGroupByColumns number The columns floatbar is visible, and it displays dragable (AllowDragging property) and groupable (AllowGroupBy property) columns of the control.
exColumnsFloatBarVisibleIncludeCheckColumns number The columns floatbar is visible, and it displays dragable (AllowDragging property), and a check-box for each Column to update its Visible property.
exColumnsFloatBarVisibleIncludeHiddenColumns number The columns floatbar is visible, and it displays dragable (AllowDragging property) and hidden (Visible property) columns of the control.
exColumnsFloatBarFloat number The columns floatbar is visible (shows as floated)

(static, readonly) FilterBarVisibleEnum :number

The Tree.FilterBarVisibleEnum type defines whether the control's filter-bar is visible or hidden.
Type:
  • number
Properties:
Name Type Description
exFilterBarHidden number No filter bar is shown while there is no filter applied. The control's filter bar is automatically displayed as soon a a filter is applied.
exFilterBarPromptVisible number The exFilterBarPromptVisible flag specifies that the control's filter bar displays the filter prompt. The exFilterBarPromptVisible, exFilterBarVisible, exFilterBarCaptionVisible flag , forces the control's filter-prompt, filter bar or filter bar description ( even empty ) to be shown. If missing, no filter prompt is displayed. The FilterBarPrompt property to specify the HTML caption being displayed in the filter bar when the filter pattern is missing.
exFilterBarVisible number The exFilterBarVisible flag forces the control's filter bar to be shown, no matter if any filter is applied. If missing, no filter bar is displayed while the control has no filter applied.
exFilterBarCaptionVisible number The exFilterBarCaptionVisible flag forces the control's filter bar to display the FilterBarCaption property.
exFilterBarSingleLine number The exFilterBarSingleLine flag specifies that the caption on the control's filter bar is displayed on a single line. The exFilterBarSingleLine flag , specifies that the filter bar's caption is shown on a single line, so
HTML tag or \r\n are not handled. By default, the control's filter description applies word wrapping. Can be combined to exFilterBarCompact to display a single-line filter bar. If missing, the caption on the control's filter bar is displayed on multiple lines. You can change the height of the control's filter bar using the FilterBarHeight property.
exFilterBarToggle number The exFilterBarToggle flag specifies that the user can close the control's filter bar ( resets the control's filter ) by clicking the close button of the filter bar or by pressing the CTRL + F, while the control's filter bar is visible. If no filter bar is displayed, the user can display the control's filter bar by pressing the CTRL + F key. While the control's filter bar is visible the user can navigate though the list or control's filter bar using the ALT + Up/Down keys. The exFilterBarToggle flag must be combined with exFilterBarPromptVisible, exFilterBarVisible or exFilterBarCaptionVisible.
exFilterBarShowCloseIfRequired number The exFilterBarShowCloseIfRequired flag indicates that the close button of the control's filter bar is displayed only if the control has any currently filter applied.
exFilterBarShowCloseOnRight number The exFilterBarShowCloseOnRight flag specifies that the close button of the control's filter bar should be displayed on the right side.
exFilterBarCompact number The exFilterBarCompact flag compacts the control's filter bar, so the filter-prompt will be displayed to the left, while the control's filter bar caption will be displayed to the right. This flag has effect only if combined with the exFilterBarPromptVisible. This flag can be combined with the exFilterBarSingleLine flag, so all filter bar will be displayed compact and on a single line.
exFilterBarShort number The exFilterBarShort flag specifies that the control's filter bar is displayed only on the default-view (has effect if the control displays multiple views)

(static, readonly) FilterIncludeEnum :number

The Tree.FilterIncludeEnum indicates the type of columns, the columns floatbar can display
Type:
  • number
Properties:
Name Type Description
exItemsWithoutChilds number Items (and parent-items) that match the filter are shown (no child-items are included)
exItemsWithChilds number Items (parent and child-items) that match the filter are shown
exRootsWithoutChilds number Only root-items (excludes child-items) that match the filter are displayed
exRootsWithChilds number Root-items (and child-items) that match the filter are displayed
exMatchingItemsOnly number Shows only the items that matches the filter (no parent or child-items are included)
exMatchIncludeParent number The exMatchIncludeParent flag specifies that the item matches the filter if any of its parent-item matches the filter. The exMatchIncludeParent flag can be combined with any other value. For instance, exMatchIncludeParent | exMatchingItemsOnly displays only the items that match the filter including the child-items as well

(static, readonly) FilterListEnum :number

The Tree.FilterListEnum type specifies the type of items being included in the column's drop down list filter.
Type:
  • number
Properties:
Name Type Description
exAllItems number The filter's list includes all items in the column.
exVisibleItems number The filter's list includes only visible (filtered) items from the column. The visible items include child items of collapsed items.
exNoItems number The filter's list includes no item from the column.
exLeafItems number The filter's list includes the leaf items only. A leaf item is an item with no child items.
exRootItems number The filter's list includes the root items only. A root item has no parent item.
exSortItemsDesc number Sorts descending the items of the filter's list. If none of the exSortItemsAsc or exSortItemsDesc is present, the list is built as the items are displayed in the control.
exSortItemsAsc number Sorts ascending the items of the filter's list. If none of the exSortItemsAsc or exSortItemsDesc is present, the list is built as the items are displayed in the control.
exShowCheckBox number Displays a check-box for each item within the filter's list.
exShowExclude number Shows or hides the Exclude field. The exFilterExclude flag excludes programmatically the selected items in the drop down filter panel.
exShowBlanks number The filter's list includes (Blanks) and (NonBlanks) items

(static, readonly) FilterPromptEnum :number

The Tree.FilterPromptEnum type specifies the type of filter-prompt.
Type:
  • number
Properties:
Name Type Description
exFilterPromptContainsAll number The list includes the items that contains all specified sequences in the filter. Can be combined with exFilterPromptCaseSensitive, exFilterPromptStartWords, exFilterPromptEndWords or exFilterPromptWords
exFilterPromptContainsAny number The list includes the items that contains any of specified sequences in the filter. Can be combined with exFilterPromptCaseSensitive, exFilterPromptStartWords, exFilterPromptEndWords or exFilterPromptWords
exFilterPromptStartWith number The list includes the items that starts with any specified sequences in the filter. Can be combined with exFilterPromptCaseSensitive, exFilterPromptStartWords, exFilterPromptEndWords or exFilterPromptWords
exFilterPromptEndWith number The list includes the items that ends with any specified sequences in the filter. Can be combined with exFilterPromptCaseSensitive, exFilterPromptStartWords, exFilterPromptEndWords or exFilterPromptWords
exFilterPromptPattern number The filter indicates a pattern that may include wild characters to be used to filter the items in the list. The FilterBarPromptPattern property may include wild characters as follows: '?' for any single character '*' for zero or more occurrences of any character '#' for any digit character ' ' space delimits the patterns inside the filter The exFilterPromptPattern flag can be combined with exFilterPromptCaseSensitive only
exFilterPromptCaseSensitive number Filtering the list is case sensitive. Can be combined with exFilterPromptContainsAll, exFilterPromptContainsAny, exFilterPromptStartWith, exFilterPromptEndWith or exFilterPromptPattern.
exFilterPromptStartWords number The list includes the items that starts with specified words, in any position. Can be combined with exFilterPromptContainsAll, exFilterPromptContainsAny, exFilterPromptStartWith or exFilterPromptEndWith.
exFilterPromptEndWords number The list includes the items that ends with specified words, in any position. Can be combined with exFilterPromptContainsAll, exFilterPromptContainsAny, exFilterPromptStartWith or exFilterPromptEndWith.
exFilterPromptWords number The filter indicates a list of words. Can be combined with exFilterPromptContainsAll, exFilterPromptContainsAny, exFilterPromptStartWith or exFilterPromptEndWith.

(static, readonly) FilterTypeEnum :number

The Tree.FilterTypeEnum type defines the type of filter applies to a column.
Type:
  • number
Properties:
Name Type Description
exAll number No filter is applied
exBlanks number Includes only blank/empty items
exNonBlanks number Includes only non blank/empty items
exPattern number Includes only items that match the pattern. The Filter property defines the pattern. A pattern may contain the wild card characters '?' for any single character, '*' for zero or more occurrences of any character, '#' for any digit character, and [chars] indicates a group of characters. If any of the *, ?, # or | characters are preceded by a \ ( escape character ) it masks the character itself. Can be combined with exFilterDoCaseSensitive flag
exDate number Includes only items that fit the date interval. The Filter property of the Column object defines the interval of dates being used to filter items. The interval of dates should be as [dateFrom] to [dateTo]. If the dateFrom value is missing, the control includes only the items before the dateTo date, if the dateTo value is missing, the control includes the items after the dateFrom date. If both dates ( dateFrom and dateTo ) are present, the control includes the items between this interval of dates. For instance, the "2/13/2004 to" includes all items after 2/13/2004 inclusive, or "2/13/2004 to Feb 14 2005" includes all items between 2/13/2004 and 2/14/2004.
exNumeric number Includes only items of numeric type that check the expression. The expression supports operators like <, <=, =, <>, >= or > and numbers to define rules. For instance, the "> 10 < 100" filter indicates all numbers greater than 10 and less than 100.
exCheck number Includes only checked-items, while Filter property is "1" or unchecked-items if Filter is "0"
exImage number Includes only items that match the images within the Filter property.
exFilter number Includes only items that match the Filter property. Can be combined with exFilterDoCaseSensitive flag
exFilterDoCaseSensitive number By default, the column's filter is case-insensitive. Specifies a case-sensitive column's filter. Can be combined with exPattern or exFilter flag
exFilterExclude number The flag indicates that the Exclude field of the column is checked. The flag indicates that the items that match the filter are excluded from the list.

(static, readonly) GridLinesEnum :number

The Tree.GridLinesEnum type defines the control's grid lines
Type:
  • number
Properties:
Name Type Description
exNoLines number The control displays no grid lines.
exAllLines number The control displays vertical and horizontal grid lines.
exRowLines number The control shows grid lines for existing rows only.
exHLines number The control displays only the horizontal grid lines.
exVLines number The control displays only the vertical grid lines.

(static, readonly) HeaderVisibleEnum :number

The Tree.HeaderVisibleEnum type specifies whether the control's header is visible or hidden
Type:
  • number
Properties:
Name Type Description
exHeaderHidden number The control's header is hidden.
exHeaderVisible number The control's header is visible.
exHeaderVisibleExtendLevels number The control's header is visible, and each column's header is extended to cover all levels of the header

(static, readonly) LinesAtRootEnum :number

The Tree.LinesAtRootEnum type defines how the control displays the lines at root. The LinesAtRoot property defines the way the tree lines are shown. The HasLines property defines the type of the line to be shown. The HasButtons shows or hides the expand/collapse glyphs for parent items.
Type:
  • number
Properties:
Name Type Description
exNoLinesAtRoot number No lines at root items
exLinesAtRoot number The control links the root items
exGroupLinesAtRoot number The control shows no links between roots, and divides them as being in the same group
exGroupLines number The lines between root items are no shown, and the links show the items being included in the group
exGroupLinesInside number The lines between root items are no shown, and the links are shown between child only
exGroupLinesInsideLeaf number The lines between root items are no shown, and the links are shown for first and last visible child item
exGroupLinesOutside number The lines between root items are no shown, and the links are shown for first and last visible child item. A parent item that contains flat child items only, does not indent the child part. By a flat child we mean an item that does not contain any child item

(static, readonly) SingleSelEnum :number

The Tree.SingleSelEnum type defines flags the singleSel/SetSingleSel/GetSingleSel method uses.
Type:
  • number
Properties:
Name Type Description
exDisableSel number The exDisableSel value specifies that the control's selection is disabled.
exEnableSel number The exEnableSel flag specifies that the control's selection is enabled (multiple-selection, unless the exSingleSel is set ).
exSingleSel number The exSingleSel flag specifies that the user can select a item only.
exToggleSel number The exToggleSel flag specifies that the item's selection state is toggled once the user clicks a item.
exDisableCtrlSel number The exDisableCtrlSel flag disables toggling the item's selection state when user clicks a item, while CTRL modifier key is pressed.
exDisableShiftSel number The exDisableShiftSel flag disables selecting items using the SHIFT key.
exDisableDrag number The exDisableDrag flag disables selecting items by drag.

(static, readonly) SortOnClickEnum :number

The Tree.SortOnClickEnum type specifies the action that control takes when the user clicks the column's header
Type:
  • number
Properties:
Name Type Description
exNoSort number The column is not sorted when user clicks the column's header.
exDefaultSort number The column gets sorted when user the clicks the column's header.
exUserSort number The control displays the sort icons, but it doesn't sort the column (not supported)

(static, readonly) SortOrderEnum :number

The Tree.SortOrderEnum type specifies the column's sort order.
Type:
  • number
Properties:
Name Type Description
exSortNone number The column is not sorted.
exSortAscending number The column is sorted ascending.
exSortDescending number The column is sorted descending.

(static, readonly) SortTypeEnum :number

The Tree.SortTypeEnum type specifies the types of sort-as the column supports
Type:
  • number
Properties:
Name Type Description
exSortString number The column's content is sorted as string (by default).
exSortNumeric number The column's content is sorted as numbers.
exSortDate number The column's content is sorted as dates.
exSortByValue number The column gets sorted by cell's value rather than cell's caption (the cell's caption include formatting)
exSortByState number The column gets sorted by cell's state (checked, unchecked) rather than cell's caption (the cell's caption include formatting)
exSortByImage number The column gets sorted by cell's image rather than cell's caption (the cell's caption include formatting)

(static) type :string

The type field defines the full-name of the object (the constructor.name does not give the same name for minimized forms)
Type:
  • string
Since:
  • 1.8

(static) version :string

The version field defines the version of the control
Type:
  • string

Methods

AddTreeView(name, attributesopt) → {TV}

The AddTreeView() method creates a new view to display the columns/items. Use the RemoveTreeView() method removes a tree-view already created by AddTreeView() method.
Parameters:
Name Type Attributes Description
name string defines the name of the tree-view to be created. It must be an unique name. The "tree" defines the control's default-tree view, and it is reserved. If missing, the "tree.split" is used instead
attributes exontrol.W.Options <optional>
 A exontrol.W.Options that defines the attributes of the window
Properties
Name Type Description
Visible boolean The Visible field indicates whether the window is visible or hidden.
VisibleExtends string The VisibleExtends field specifies the list of windows the current window depends to be visible or hidden. A string expression that specifies the list of windows the current window's visibility depends on as explained:
  • if the VisibleExtends property includes the window itself, the window is visible if any window in VisibleExtends is visible, else
  • if the VisibleExtends property does NOT includes the window itself, the window is hidden if any window in VisibleExtends is hidden (or the window is visible if all VisibleExtends windows are visible)
AllowKeys boolean The AllowKeys field specifies whether the window can receive the Keys events. By default, only the canvas window receives all the keys.
Enabled boolean The Enabled field specifies whether the window is enabled or disabled (the window is protected and shown in gray).
Resizable boolean The Resizable field indicates whether the window is resizable or fixed.
Locked boolean The Locked field specifies that the window is locked (the window is protected).
Dock exontrol.WDT The Dock field specifies how the control borders are docked to its parent control and determines how a control is resized with its parent. The exontrol.WDT type supports the following values:
  • N(0), the window is not docked (none)
  • T(1), the window's top edge is docked to the top of its containing window (top)
  • B(2), the window's bottom edge is docked to the bottom of its containing window (bottom)
  • L(3), the window's left edge is docked to the left edge of its containing window (left)
  • R(4), the window's right edge is docked to the right edge of its containing window (right)
  • F(5), all the window's edges are docked to all edges of its containing window and sized appropriately (fill)
Size number The Size field defines the width/height of the window when it is docked.
SizeExtends string The SizeExtends field specifies the list of windows that shares the same size. Once a window is resized, all its SizeExtends windows are sized the same as the current one.
Client Array.<number> The Client field specifies position of the window relative to the parent window, as an array of [x,y,width,heigh] type.
Background string The Background field defines the window's background color ( CSS Color ) or null/undefined if not provided.
Foreground string The Foreground field defines the window's foreground color ( CSS Color ) or null/undefined if not provided.
Opacity number The Opacity field indicates the window's opacity, as a number between 0 and 1 (1 is not transparent at all, 0.5 is 50% see-through, and 0 is completely transparent)
HoverBackground string The HoverBackground field, defines the window's background color while the cursor hovers it ( CSS Color ) or null/undefined if not provided
HoverForeground string The HoverForeground field defines the window's foreground color while the cursor hovers it( CSS Color ) or null/undefined if not provided
HoverOpacity number The HoverOpacity field indicates the window's opacity, as a number between 0 and 1 (1 is not transparent at all, 0.5 is 50% see-through, and 0 is completely transparent), when the cursor hovers it
DrawWindowFrame boolean The DrawWindowFrame field indicates whether the window draws its frame.
Extends string The Extends field indicates a list of windows separated by comma character to extend the current's client area to. The windows(child windows) must have the z-order greater than the z-order of the current window, else they will be ignored. The Extends field changes the z-order of the windows as well.
HoverExtends string The HoverExtends field specifies the list of windows separated by comma character that receives the hover-events once the cursor hovers the current window.
AllowXChg boolean The AllowXChg field specifies whether the window can exchange its UI position with another window. Only windows with AllowXChg field set can be exchanged.
XChgID string The XChgID field specifies the general expression, whose evaluated result defines the caption to be displayed on the window's anchor-exchange part. The expression supports keywords like index, name and shortname, that indicates the window's index, a value starting from 0, the window's name and short-name. The evaluated result can include exontrol's HTML tags that will be applied on the window's anchor-exchange element. If the expression is not valid, the XChgID value is used as it is.
Control object The Control field defines the control associated with the window (for internal use only).
HScroll string The HScroll field defines window's horizontal scroll bar. A string expression that indicates the name of the window that hosts an exontrol.SB control or an object of exontrol.SB type that defines the window's horizontal scroll bar (for internal use only).
VScroll string The VScroll field defines window's vertical scroll bar. A string expression that indicates the name of the window that hosts an exontrol.SB control or an object of exontrol.SB type that defines the window's vertical scroll bar (for internal use only).
Layout string The Layout field defines the properties (separated by comma) the GetLayout/SetLayout methods of CW saves/restores (for internal use only).
Returns:
Returns the newly created view as an object of TV type. Returns null, in case there is already a window with specified name.
Type
TV
Example
oTree.AddTreeView("2nd",{Background: "black", Foreground: "white", Dock: 3}), adds a new tree-view panel, docked to the left-size, with a black-background and a white-foreground

ApplyFilter()

The ApplyFilter() method (re-)applies the control's filter (if any)

BeginUpdate()

The BeginUpdate() method suspends the control's render until the EndUpdate() method is called. It maintains performance, while multiple changes occurs within the control. You can use the Update() method to perform multiple changes at once.

Cell(item, column) → {Cell}

The Cell() method returns the cell based on the item and column.
Parameters:
Name Type Description
item any The item parameter could be any of the following:
  • item {number}, indicates a numeric value that defines the index of the item to request
  • item {string}, specifies a string expression that defines the identifier/key of the item to request
  • item {Item}, specifies the object reference to the item to request for
column any The column parameter could be any of the following:
  • column {number}, indicates a numeric value that defines the index of the column to request
  • column {string}, specifies a string expression that defines the identifier/key/caption/plain-caption of the column to request
  • column {Column}, specifies the object reference to the column to request for
Returns:
Returns null or an object of Cell type
Type
Cell

ChooseFile(error) → {object}

The ChooseFile() method clears the control's data and adds an input-file element to let user choose a local file (CSV or XML format) to import data from
Parameters:
Name Type Description
error object Specifies a string (message) or an object of DOMException (or any other) type that holds defines the error to display
Returns:
Returns an object of {i,s} type that holds:
  • i {HTMLInputElement}, specifies the "input-file" element to let user selects a local file to import into the control
  • s {HTMLSpanElement}, indicates the "span" element that displays the error
Once the control's layout is changed, the "input-file" and "span" elements are automatically removed.
Type
object

Clear()

The Clear() method clears the control's data (columns, items and filter)

ClearFilter()

The ClearFilter() method clears the control's filter (if any)

CollapseAll()

The CollapseAll() method collapses all items

Column(column) → {Column}

The Column() method returns the column based on its index or identifier/key. The Column(id) method is equivalent with Item(id) method of the Column object.
Parameters:
Name Type Description
column any The column parameter could be any of the following:
  • column {number}, indicates a numeric value that defines the index of the column to request
  • column {string}, specifies a string expression that defines the identifier/key/caption/plain-caption of the column to request
  • column {Column}, specifies the object reference to the column to request for
Returns:
Returns null or an object of Column type
Type
Column

ConditionalFormat(id) → {ConditionalFormat}

The ConditionalFormat() method gets the conditional format by index, key or reference
Parameters:
Name Type Description
id any The id parameter could be any of the following:
  • id {number}, indicates a numeric value that defines the index of the conditional format to request
  • id {string}, specifies a string expression that defines the identifier/key of the conditional format to request
  • id {ConditionalFormat}, specifies the object reference to the conditional format to request for
Returns:
Returns null(the conditional format is not found), or an object of ConditionalFormat type, if the conditional formats collection contains the giving id.
Type
ConditionalFormat

EndUpdate()

The EndUpdate() method resumes the control's render, after it is suspended by the BeginUpdate() method.

ExpandAll(bExpand)

The ExpandAll() method expands all items
Parameters:
Name Type Description
bExpand boolean Specifies whether all items are expanded or collapsed (true if missing/empty/undefined)

Export(exportOptsopt) → {any}

The Export() method exports the control's data as an array or CSV format. The GetData() method is equivalent with Export() method.
Parameters:
Name Type Attributes Description
exportOpts object <optional>
 Indicates the options to export control's data. The exportOpts object can include any of the following fields:
  • items {string}, specifies the items to export as one of the following values:
    • "all", exports all items, including the hidden or collapsed items
    • "vis", exports only visible items ( child items of a collapsed item, or not-visible items ( item's height is 0 ) are not exported )
    • "sel", exports only selected items
    • "chk", exports only checked items (within the first column of columns field, else column with the index 0)
  • columns {any}, specifies a list of columns to export as explained bellow:
    • columns {null}, exports all columns of the control
    • columns {number}, indicates a numeric value that defines the index of the column to export
    • columns {string}, specifies a list of index/identifier/key/caption/plain-caption, separated by comma character
    • columns {Column}, specifies the object reference to the column to export
  • rtrim {boolean}, specifies whether undefined values on the right of each row/item are excluded from the export data (specifies whether the number of fields within the lines is constant or variable)
  • format {string}, determines the type of data the Export() method returns
  • eor {string}, specifies the characters the row/item/line ends (has effect only if format field is "CSV")
  • eof {string}, specifies the character to separate fields within the row/item/line (has effect only if format field is "CSV")
  • quote {string}, specifies the character to quote values (has effect only if format field is "CSV")
  • hdr {boolean}, specifies whether the method exports the header of the columns (first line)
  • data {string}, indicates the name of the method to export data of the cell (by default it is "v" which defines the cell's value). You can use "pc" to get the plain-caption of the cell, or any other method of the cell
Returns:
Returns an array of [[value]] type or the control's data as as string in CSV format (only if the exportOpts.format field is "CSV")
Type
any

GetColumns() → {Columns}

The GetColumns() method returns the control's columns.
Returns:
Returns an object of Columns type
Type
Columns
Example
The following statements are equivalents:

 oTree.GetColumns(), returns the control's columns
 oTree.Columns, returns the control's columns

where oTree is an object of Tree type

GetConditionalFormats() → {ConditionalFormats}

The GetConditionalFormats() method returns the control's conditional formats.
Returns:
Returns an object of ConditionalFormats type.
Type
ConditionalFormats
Example
The following statements are equivalents:

 oTree.GetConditionalFormats(), returns the control's conditional formats
 oTree.ConditionalFormats, returns the  control's conditional formats

where oTree is an object of Tree type

GetData() → {any}

The GetData() method exports the control's data as an array or CSV format. The GetData() method is equivalent with Export() method. The ExportOptions type defines the default options to export data.
Returns:
Returns an array of [[value]] type or the control's data as as string in CSV format (only if the ExportOptions.format field is "CSV")
Type
any

GetItems() → {Items}

The GetItems() method returns the control's items.
Returns:
Returns an object of Items type.
Type
Items
Example
The following statements are equivalents:

 oTree.GetItems(), returns the control's items
 oTree.Items, returns the control's items

where oTree is an object of Tree type

GetLayout(oOptsopt) → {string}

The GetLayout() method saves the UI layout of the object to an encoded string. The layout can be restored using the SetLayout() method. Currently, the control's Layout property serializes the following:
  • layout of windows (size, dock, parent)
  • pattern of the control's filter-prompt
  • view's horizontal and vertical scroll position
  • column's width, visibility, position, expand/collapse state, sort-order, sort-position, filter, filter-type
  • selected, expanded/collapsed items
  • control's zoom
Parameters:
Name Type Attributes Description
oOpts object <optional>
 An object of {iMask,eMask,base64,equal,eol} type that defines options to serialize the properties of the container as explained bellow:
  • iMask {string}, specifies the mask (can include ? or * wild-characters) of properties to save
  • eMask {string}, specifies the mask (can include ? or * wild-characters) of properties to exclude from save
  • base64 {boolean}, Encodes the result to BASE 64
  • equal {string}, Indicates the separator between the name and the value. If missing, the = character is used
  • eol {string}, A character that separates the properties. By default it is "\n"
Returns:
Returns a string that encodes the current UI layout for the entire object
Type
string
Example
The following statements are equivalents:

 oTree.GetLayout(), gets the control's layout
 oTree.Layout, gets the control's layout

where oTree is an object of Tree type

GetSelection() → {array}

The GetSelection() method gets the control's selection.
Returns:
The GetSelection can return one of the following:
  • null, indicates that the control has no selected-items
  • {Item}, indicates a single-selected item (while the control support single-selection only)
  • {Item[]}, defines a collection of selected-items within the control
Type
array
Example
The following statements are equivalents:

 oTree.GetSelection(), gets the control's selection
 oTree.Selection, gets the control's selection

where oTree is an object of Tree type

GetSingleSel() → {Tree.SingleSelEnum}

The GetSingleSel() method specifies whether the control supports single, multiple, toggle selection.
Returns:
Returns an OR combination of Tree.SingleSelEnum flags that specifies how to select items
Type
Tree.SingleSelEnum

GetStatistics() → {string}

The GetStatistics() method gives statistics data of objects being hold by the control
Returns:
Returns statistics data of objects being hold by the control such as:
Size: 1,536x754
Zoom: 100%
Column: 4/4
Item: 32/55
Cell: 128/220
Sel: 1
Type
string
Example
The following statements are equivalents:

 oTree.GetStatistics(), gives statistics data of objects being hold by the control
 oTree.Statistics, gives statistics data of objects being hold by the control

where oTree is an object of Tree type

Import(source, importOptsopt)

The Import() method imports data from CSV/XML format. The SetData(value) method is equivalent with Import(value) method.
Parameters:
Name Type Attributes Description
source any The source parameter may be one of the following:
  • A String expression that specifies the URL to a CSV or XML file (contains no eof, eor or str)
  • A String expression in CSV format
  • An object that includes the "files" member of FileList type (a local file)
  • An array of data to load
importOpts object <optional>
 The importOpts parameter specifies options to import data into the control as object of ImportOptions type.
Properties
Name Type Description
columnCaption string defines an expression that generates captions for new columns.
clear boolean specifies whether previously data of the control is cleared
parent any defines the parent item to insert data to
limit number specifies the maximum number of rows/items/lines to import
format string determines the format of source to import data from
eor string specifies the characters the row/item/line ends (has effect only if format field is "CSV")
eof string specifies the character to separate fields within the row/item/line (has effect only if format field is "CSV")
str string specifies the character to quote values (has effect only if format field is "CSV")
hdr boolean indicates whether the first line in data represents the control's header (has effect only if format field is "CSV")
ignoreXML boolean specifies whether the file is loaded as CSV even for .xml files (files of XML type)

Item(item) → {Item}

The Item() method returns the item based on its index or identifier/key. The Item(id) method is equivalent with Item(id) method of the Items object
Parameters:
Name Type Description
item any The item parameter could be any of the following:
  • item {number}, indicates a numeric value that defines the index of the item to request
  • item {string}, specifies a string expression that defines the identifier/key of the item to request
  • item {Item}, specifies the object reference to the item to request for
Returns:
Returns null or an object of Item type
Type
Item

LoadXML(source)

The LoadXML() method loads an XML document (previously saved by an exontrol component)
Parameters:
Name Type Description
source any The source parameter may be one of the following:
  • A String expression that specifies the URL to a XML file (contains no < or > characters)
  • A String expression in XML format
  • An object that includes the "files" member of FileList type (a local file)
  • A XMLDocument, as a result of parsing the XML source code from a string

Refresh()

The Refresh() method refreshes the control

RemoveSelection() → {number}

The RemoveSelection() method deletes the selected-items.
Returns:
Returns the number of the items being deleted
Type
number

RemoveTreeView(name)

The RemoveTreeView() method removes the view already created by the AddTreeView() method
Parameters:
Name Type Description
name string defines the name of the tree-view to be removed. The "tree" defines the control's default-tree view, and it can not be removed.

Select(key)

The Select() method selects items based on the key.
Parameters:
Name Type Description
key string Specifies a key which determines what Select method does:
  • "Home" {string}, selects the first item
  • "End" {string}, selects the last item
  • "Prior" or "PageUp"{string}, selects the item from the prior page
  • "Next" or "PageDown" {string}, selects the item from the next page
  • "Up" or "ArrowUp" {string}, selects the previously item
  • "Down" or "ArrowDown" {string}, selects the next item
The Select() method selects only visible and selectable items.
Since:
  • 1.6

SelectAll(toSelect)

The SelectAll(toSelect) method selects all items within the control.
Parameters:
Name Type Description
toSelect any Specifies the items to select within the control as one of the following values:
  • null {null}, unselects any item within the control
  • undefined or "all" {string}, selects all items within the control
  • "vis" {string}, selects just the visible-items within the control (for instance, it does not select items that does not match the filter)
  • "leaf" {string}, selects just the visible leaf-items within the control (a leaf item has no child items)
Example
SelectAll("vis"), selects the visible items only (for instance, it does not select items that does not match the filter)

SetData(value)

Imports data from CSV or XML files. The SetData(value) method is equivalent with Import(value) method. The ImportOptions type defines default options to import data.
Parameters:
Name Type Description
value any Indicates the source of the data, as one of the following:
  • A String expression that specifies the URL to a CSV or XML file (contains no eof, eor or str)
  • A String expression in CSV format
  • An object that includes the "files" member of FileList type (a local file)
  • An array of data to load
Example
"xml/datasource.xml" {string}, imports data from datasource.xml file

SetLayout(layout, oOptsopt)

The SetLayout() method restores the UI layout of the object from an encoded string, previously returned by the GetLayout() method. Currently, the control's Layout property serializes the following:
  • layout of windows (size, dock, parent)
  • pattern of the control's filter-prompt
  • view's horizontal and vertical scroll position
  • column's width, visibility, position, expand/collapse state, sort-order, sort-position, filter, filter-type
  • selected, expanded/collapsed items
  • control's zoom
Parameters:
Name Type Attributes Description
layout string A string expression that defines the UI layout to apply
oOpts object <optional>
 An object of {iMask,eMask,base64,equal,eol} type that defines options to serialize the UI layout as explained bellow:
  • iMask {string}, specifies the mask (can include ? or * wild-characters) of properties to load
  • eMask {string}, specifies the mask (can include ? or * wild-characters) of properties to exclude from load
  • base64 {boolean}, Decodes the layout from BASE 64
  • equal {string}, Indicates the separator between the name and the value. If missing, the = character is used
  • eol {string}, A sequence of characters that can separate the properties. By default, any of \n, \r or ; separates the properties

SetSelection(value)

The SetSelection() method sets the control's selection.
Parameters:
Name Type Description
value any The value can be any of the following:
  • value {null}, clears the entire selection (unselect all)
  • value {number}, selects an item giving index within the items collection
  • value {string}, selects an item giving its identifier/key
  • value {Item}, selects an item giving its reference
  • value {Items}, selects all items within the control
  • value {array}, specifies an array of [type] type, where type could be any number, string or Item type.

SetSingleSel(value)

The SetSingleSel() method changes the control's selection to single, multiple or toggle
Parameters:
Name Type Description
value Tree.SingleSelEnum An OR combination of Tree.SingleSelEnum flags to specify how user can select items
Example
0 or exontrol.Tree.SingleSelEnum.exDisableSel {number}, disables selecting any item
 3 or exontrol.Tree.SingleSelEnum.exSingleSel | exontrol.Tree.SingleSelEnum.exEnableSel {number}, enables control's single selection, so only a single item can be selected
 6 or exontrol.Tree.SingleSelEnum.exToggleSel | exontrol.Tree.SingleSelEnum.exSingleSel {number}, enables control's single and toggle selection, which means that once a item is selected it gets unselected once it is clicked, or reverse, and only a single-item can be selected at once.

TreeView(name) → {TV}

The TreeView() method gets the tree-view by name (which was previously created by the AddTreeView() method)
Parameters:
Name Type Description
name string defines the name of the tree-view to request ("tree" defines the control's default-tree view)
Since:
  • 1.1
Returns:
Returns null or the an object of TV type associated with the name
Type
TV

UnselectAll()

The UnselectAll() method clears the control's selection.

Update(callback, thisArgopt)

The Update() method locks the control's paint during the callback, and invalidates the control once the method ends.
Parameters:
Name Type Attributes Description
callback callback Indicates a callback to perform changes within the control
thisArg any <optional>
 Specifies the value of "this" keyword during the callback. If missing/empty/undefined the thisArg points to the control itself, as an object of Tree type

feI(callback, thisArgopt)

The feI/forEachItem() method invokes the callback for each item of the control (unscrolled(top,bottom items) and scrolled items as well)
Parameters:
Name Type Attributes Description
callback callback A function of callback(oItem) type that's called for every item, where oItem is:
  • oItem {Item}, specifies an item of Item type
thisArg any <optional>
 Indicates the value of "this" keyword during the callback. If missing/empty/undefined the thisArg points to the control itself, as an object of Tree type.

feIU(callback, thisArgopt) → {any}

The feIU/forEachItemUnit() method invokes the callback for each item of the control (unscrolled(top,bottom items) and scrolled items as well), until the callback returns a not-empty value
Parameters:
Name Type Attributes Description
callback callback A function of callback(oItem) {any} type that's called for every item, where oItem is
  • oItem {Item}, specifies an item of Item type
thisArg any <optional>
 Indicates the value of "this" keyword during the callback. If missing/empty/undefined the thisArg points to the control itself, as an object of Tree type.
Returns:
Returns the last-value of the callback
Type
any

Events

onaddcolumn

The onaddcolumn() method occurs once a new column has been added to the control
Parameters:
Name Type Description
oEvent Column Indicates an object of Column type being added
Example
The following samples display the column being added:

oTree.onaddcolumn = function (oEvent)
{
 console.log(oEvent);
}

or

oTree.Listeners.Add("onaddcolumn", function (oEvent)
{
 console.log(oEvent);
})

where oTree is an object of Tree type

onaddgroupitem

The onaddgroupitem() method notifies the control once a group-item is added. The GroupItem/GetGroupItem() method indicates a group-item if zero or positive (specifies the index of the column that has been grouped by)
Parameters:
Name Type Description
oEvent Item Indicates the new group-item being created and added, as an object of Item type.
Example
The following samples display the group-item being added:

oTree.onaddgroupitem = function (oEvent)
{
 console.log(oEvent);
}

or

oTree.Listeners.Add("onaddgroupitem", function (oEvent)
{
 console.log(oEvent);
})

where oTree is an object of Tree type

onadditem

The onadditem() method notifies your application that a new item has been added to the control
Parameters:
Name Type Description
oEvent Item Indicates an object of Item type being added
Example
The following samples display the item being added:

oTree.onadditem = function (oEvent)
{
 console.log(oEvent);
}

or

oTree.Listeners.Add("onadditem", function (oEvent)
{
 console.log(oEvent);
})

where oTree is an object of Tree type

onerror

The onerror() method occurs once the control encountered an error.
Parameters:
Name Type Description
oEvent object Specifies an object of DOMException (or any other) type that holds information about the error
Example
The following samples display the error once it occurs:

oTree.onerror = function (oEvent)
{
 console.log(oEvent);
}

or

oTree.Listeners.Add("onerror", function (oEvent)
{
 console.log(oEvent);
})

where oTree is an object of Tree type

onfilter

The onfilter() method notifies your application once the control's filter has been changed
Example
The following samples display a message once a filter is applied or cleared:

oTree.onfilter = function ()
{
 console.log("onfilter");
}

or

oTree.Listeners.Add("onfilter", function ()
{
 console.log("onfilter");
})

where oTree is an object of Tree type

onload

The onload() method occurs once the control loads or imports data
Example
The following samples display a message once the control loads or imports new data (for instance, the user drags and drops a file into the control):

oTree.onload = function ()
{
 alert("onload");
}

or

oTree.Listeners.Add("onload", function ()
{
 alert("onload");
})

where oTree is an object of Tree type

onremovecolumn

The onremovecolumn() method notifies your application that a column has been removed from the control
Parameters:
Name Type Description
oEvent Column Indicates an object of Column type being removed
Example
The following samples display the column being removed:

oTree.onremovecolumn = function (oEvent)
{
 console.log(oEvent);
}

or

oTree.Listeners.Add("onremovecolumn", function (oEvent)
{
 console.log(oEvent);
})

where oTree is an object of Tree type

onremoveitem

The onremoveitem() method occurs once an item has been removed from the Items collection
Parameters:
Name Type Description
oEvent Item Indicates an object of Item type being removed
Example
The following samples display the item being removed:

oTree.onremoveitem = function (oEvent)
{
 console.log(oEvent);
}

or

oTree.Listeners.Add("onremoveitem", function (oEvent)
{
 console.log(oEvent);
})

where oTree is an object of Tree type

onselchange

The onselchange() method notifies that the control's selection has been changed (items).
Parameters:
Name Type Description
oEvent object holds the control's selection, as explained:
  • oEvent {null}, indicates that the control has no selected items
  • oEvent {Item}, indicates an object of Item type that defines the control's single-item selected
  • oEvent {array}, specifies an array of [Item] type that holds all selected items within the control
Example
The following samples display the control's selection once it changes:

oTree.onselchange = function (oEvent)
{
 console.log(oEvent);
}

or

oTree.Listeners.Add("onselchange", function (oEvent)
{
 console.log(oEvent);
})

where oTree is an object of Tree type

onsort

The onsort() method notifies your application once a column gets sorted or grouped by.
Parameters:
Name Type Description
oEvent number defines the sort-operation it occured as a combination of one or more flags:
  • 1 {number}, indicates sort operation
  • 2 {number}, indicates a group-by operation
Example
The following samples display the sort-operation once the user sorts or group-by a column:

oTree.onsort = function (oEvent)
{
 console.log(oEvent);
}

or

oTree.Listeners.Add("onsort", function (oEvent)
{
 console.log(oEvent);
})

where oTree is an object of Tree type