Columns class (Tree)

Columns(oTree)

new Columns(oTree)

The Columns object holds a collection of Column objects (column of the control). Use the Columns/GetColumns() method to access the control's columns collection.
Parameters:
Name Type Description
oTree Tree Indicates an object of Tree type that owns the collection
Columns

Methods

Add(oColumnOptsopt) → {Column}

The Add() method creates and adds a new column into the control.
Parameters:
Name Type Attributes Description
oColumnOpts object <optional>
 Specifies the options to create the new column as an object of ColumnOptions type. If no object is provided, it specifies the column's caption
Returns:
Returns the newly created column, as an object of Column type
Type
Column
Example
oTree.Columns.Add(), adds a new column with no caption
 oTree.Columns.Add("&lt;b>Info&lt;/b> Col"), adds a new column
 oTree.Columns.Add({caption:"<b>Info</b> Col", width: 64, allowSizing: false}), adds a new non-resizable column of specified width
 oTree.EnsureVisibleClient(oTree.Columns.Add({caption:"<b>Info</b> Col", width: 64, allowSizing: false})), adds a new non-resizable column of specified width, and ensures that the column fits the control's client area
Add

Clear()

The Clear() method removes all columns of the control and inits the control's scroll-bars
Clear

GetCount() → {number}

The GetCount() method returns the number of columns within the collection. The GetVisibleCount() method returns the number of visible-columns only.
Returns:
Returns the number of columns within the collection
Type
number
Example
The following statements are equivalents:

 oTree.Columns.GetCount(), returns the number of columns within the collection
 oTree.Columns.Count, returns the number of columns within the collection

 The following code snippet enumerates all columns:

 for (var i = 0, l = oTree.Columns.Count; i < l; i++)
   console.log(oTree.Columns.Item(i));

where oTree is an object of Tree type
GetCount

GetSorts() → {string}

The GetSorts() method retrieves a list of all columns in the control that are currently being sorted or grouped. This includes columns displayed in the control's sort bar as well as the control's single-sort column. The returned string provides a compact representation of the sort state for each column, including its index and sort direction.

Each sorted column is represented in the format `index:direction`, where:

  • `index` is the zero-based column index within the control
  • `direction` is the sort direction, represented by `A` for ascending or `D` for descending
Columns displayed in the sort bar are listed first, followed by the single-sort column, if applicable. The allowGroupBy property determines whether the control supports grouping by columns or only sorting. The sortBarVisible property controls the visibility of the sort bar in the control.
Returns:
Returns a string-representation that includes all columns being sorted within the control, such as "1:A 2:D, 0:A" as explained:
"1:A", column at index 1, sorted ascending, displayed in the sort bar
"2:D", column at index 2, sorted descending, displayed in the sort bar
"0:A", column at index 0, the single-sort column of the control, sorted ascending
Type
string
Example
The following statements are equivalents:

 oTree.Columns.GetSorts(), returns all columns being sorted within the control (including the single-sort column)
 oTree.Columns.Sorts, returns all columns being sorted within the control (including the single-sort column)

where oTree is an object of Tree type
GetSorts

GetVisibleCount() → {number}

The GetVisibleCount() method returns the number of visible-columns (columns with 'visible' property set to true). The Count property returns the total number of columns within the collection, regardless of their visibility.
Since:
  • 5.1
Returns:
Returns the number of visible-columns
Type
number
Example
The following statements are equivalents:
 
 oTree.Columns.GetVisibleCount(), returns the number of visible-columns
 oTree.Columns.VisibleCount, returns the number of visible-columns
 
where oTree is an object of Tree type
GetVisibleCount

Item(id) → {null|Column}

The Item() method gets the column giving its index, identifier/key/caption or reference. Use the Column(id) method to get the column based on its index or identifier/key.
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 column to request (supports negative indices as well, where -1 returns the most recently added column, -2 returns the column added just before it, and so on @since 5.1)
  • id {string}, specifies a string expression that defines the identifier/key/caption/plain-caption of the column to request
  • id {Column}, specifies the object reference to the column to request for
Returns:
Returns null(the column is not found), or an object of Column type, if the columns collection contains the giving id.
Type
null | Column
Example
The following code snippet enumerates all columns:

 for (var i = 0, l = oTree.Columns.Count; i < l; i++)
   console.log(oTree.Columns.Item(i));

where oTree is an object of Tree type
Item

Items(range) → {object}

The Items() method gets a collection of columns giving its index, identifier/key/caption separated by comma character.
Parameters:
Name Type Description
range any The range parameter could be any of the following:
  • range {number}, indicates a numeric value that defines the index of the column to request
  • range {string}, specifies a list of index/identifier/key/caption/plain-caption, separated by comma character
  • range {Column}, specifies the object reference to the column to request for
Returns:
Returns an object of exontrol.Arr([Column]) type.
Type
object
Items

Remove(id)

The Remove() method removes a column from the collection.
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 column to request
  • id {string}, specifies a string expression that defines the identifier/key/caption/plain-caption of the column to request
  • id {Column}, specifies the object reference to the column to request for
Remove

SetSorts(value)

The SetSorts() method sorts or groups multiple-columns at once giving a string-representation such as "1:A 2:D, 0:A".
Parameters:
Name Type Description
value string Specifies a string listing all columns currently sorted in the control, using the format `index:direction` for each column. Columns in the sort bar are separated by spaces, and the single-sort column (if any) is appended after a comma.

Each column to be sorted is represented in the format `index:direction`, where:

  • `index` is the zero-based column index within the control
    • `direction` is the sort direction, represented by `A` for ascending or `D` for descending
Columns displayed in the sort bar should be listed first, followed by the single-sort column, if applicable.

For instance, the string "1:A 2:D, 0:A" indicates:

"1:A", column at index 1, sorted ascending, displayed in the sort bar
"2:D", column at index 2, sorted descending, displayed in the sort bar
"0:A", column at index 0, the single-sort column of the control, sorted ascending
Sorting behavior depending on the allowGroupBy property:
  • When the control's allowGroupBy property is enabled, columns listed in the sort bar are treated as group-by columns and are not shown in the control's header. The single-sort column (after the comma) defines the column being sorted and is displayed in the control's header bar
  • If allowGroupBy is disabled, all listed columns are treated as regular sort columns. In this case, SetSorts() sorts multiple columns simultaneously, and each sorted column shows its index in the Sorted collection as a subscript next to the column caption
The allowGroupBy property determines whether the control supports grouping by columns or only sorting. The sortBarVisible property controls the visibility of the sort bar in the control.
Example
The following statements are equivalents:

 oTree.Columns.SetSorts("1:A 2:D, 0:A"), sorts multiple-columns at once giving a string-representation such as "1:A 2:D, 0:A"
 oTree.Columns.Sorts = "1:A 2:D, 0:A", sorts multiple-columns at once giving a string-representation such as "1:A 2:D, 0:A"

where oTree is an object of Tree type

 "1:A 2:D, 0:A" {string}, sorts multiple-columns at once giving a string-representation such as "1:A 2:D, 0:A"
 "0:D" {string}, sorts or groups the column at index 0 in descending order
SetSorts

VisibleItem(position) → {Column}

The VisibleItem() method gets the visible-column at giving position (for instance, a column with 'visible' property on false is ignored). The Item(index) method gets the column by its index within the collection, regardless of its visibility.
Parameters:
Name Type Description
position number Specifies the position of the visible-column to request (0-based index). It supports negative indices as well, where -1 returns the last visible-column, -2 returns the visible-column just before it, and so on.
Since:
  • 5.1
Returns:
Returns an object of Column type that represents the visible-column at the specified position
Type
Column
Example
oTree.Columns.VisibleItem(0) {Column}, gets the first visible-column
 oTree.Columns.VisibleItem(-1) {Column}, gets the last visible-column

The following code snippet enumerates all visible-columns:

 for (var i = 0, l = oTree.Columns.VisibleCount; i < l; i++)
   console.log(oTree.Columns.VisibleItem(i));
 
where oTree is an object of Tree type
VisibleItem