Search this site

    gnocl::tree

    Contents

    1. 1 Synopsis
    2. 2 Screenshot
    3. 3 Options
    4. 4 Description
    5. 5 Commands
    6. 6 Example
    A widget which displays text or other items arranged in a tree.

    Synopsis

    gnocl::tree [-option value...]

    Screenshot

    Options

    -children list (default: "")
    List of rows. Each row consists of a list of cell entries.
    -columns integer
    Number of columns
    -enableSearch boolean
    TO BE COMPLETED
    -expanders boolean
    TO BE COMPLETED
    -fixedHeight boolean
    TO BE COMPLETED
    -hasFocus 1
    This sets the focus to the widget. To unset the focus it must be set to another widget.
    -headersClickable boolean (default: true)
    Whether the headers are clickable.
    -headersVisible boolean (default: true)
    Whether to show the headers.
    -heightGroup string (default: "")
    The -heightGroup option can be an arbitrary string. All widgets with the same heightGroup request the same height. If packed with the fill flag set, they will have nevertheless different heights.
    -heightRequest int
    Height which is requested in the parent widget. The actual height can be larger.
    -hoverExpand boolean
    TO BE COMPLETED
    -hoverSelection boolean
    TO BE COMPLETED
    -name string
    Name of the widget, can be used to set options in an rc file.
    -onButtonPress string (default: "")
    Tcl command which is executed if a mouse button is press inside the widget. Before evaluation the following percent strings are substituted:

    %w    widget name
    %t    type of event: one of buttonPress, button2Press or button3Press
    %x    x coordinate
    %y    y coordinate
    %b    button number
    %s    state of the buttons and modifiers (bitmask)
    -onButtonRelease string (default: "")
    Tcl command which is executed if a mouse button is released inside the widget. Before evaluation the following percent strings are substituted:

    %w    widget name
    %t    type of event: always buttonRelease
    %x    x coordinate
    %y    y coordinate
    %b    button number
    %s    state of the buttons and modifiers (bitmask)
    -onPopupMenu string (default: "")
    Tcl command which is executed if the "popup-menu" signal is received, which is normally the case if the user presses Shift-F10. Before evaluation the following percent strings are substituted:

    %w    widget name
    -onRowCollapsed string (default: "")
    Command to execute in the global scope if a row is collapsed. Before evaluation the following percent strings are substituted:

    %w    widget name
    %p    list of paths of the collapsed row
    -onRowExpanded string (default: "")
    Command to execute in the global scope if a row is expanded. Before evaluation the following percent strings are substituted:

    %w    widget name
    %p    list of paths of the expanded row
    -onSelectionChanged string (default: "")
    Command to execute in the global scope if the selection could be changed. Occasionally it is executed, if the selection has not changed. Therefore the "%p" parameter can also be the empty string, which is not a valid path. Before evaluation the following percent strings are substituted:

    %w    widget name
    %p    list of paths of the selection
    -reorderable boolean
    TO BE COMPLETED
    -rubberband boolean
    TO BE COMPLETED
    -ruleHint boolean
    TO BE COMPLETED
    -selectionMode one of single, browse, multiple or extended
    none
    No selection is possible.

    single 
    None or one element may be selected.

    browse 
    Only one element is selected. Certain operations such as widget initialization or a search operation, may result in no element being selected. The user cannot deselect a currently selected element except by selecting another element.

    multiple
    Any number of elements may be selected. Clicks toggle the state of an item. Any number of elements may be selected. The Ctrl key may be used to enlarge the selection, and Shift key to select between the focus and the child pointed to. Some widgets may also allow Click-drag to select a range of elements.

    extended
    Deprecated, behaves identical to multiple.
    -sizeGroup string (default: "")
    The -sizeGroup option can be an arbitrary string. All widgets with the same sizeGroup request the same size. If packed with the fill flag set, they will have nevertheless different sizes.
    -titles string (default: "")
    Titles of the columns
    -treeLines boolean
    TO BE COMPLETED
    -types one of boolean, integer, float, string, markup or  image (default: string)
    Types of column entries. If type is markup the cell content is interpreted as markup-string. For special formatting of the other types the -onCellData callback can be used.
    -scrollbar always, never, automatic (default: automatic)
    When to show scrollbars. If the value is a list of two elements, the first value is for the horizontal scrollbar and the second value for the vertical scrollbar.
    -visible boolean (default: 1)
    Whether or not the item is visible.
    -widthGroup string (default: "")
    The -widthGroup option can be an arbitrary string. All widgets with the same widthGroup request the same width. If packed with the fill flag set, they will have nevertheless different widths.
    -widthRequest int
    Width which is requested in the parent widget. The actual width can be larger.

    Description

    The tree command creates a new tree widget. On creation at least on of the options -columns, -children, -titles or -types must be given. The number of columns of the created tree is the maximum of these four values. This number cannot be changed after creation, but hiding columns should do the job in most cases.

    Each row can be identified by its path. A path is a list of integers which describe recursively the position of the row relative to its parent: the highest level rows have the path 0, 1 etc.; the children of the second row the path {1 0}, {1 1}, {1 2} etc.; the children of the first child of the second child of the second row have the path {1 1 0 0}, {1 1 0 1}, {1 1 0 2} etc. The level above the first level has the empty path {}. Each element in a path may also be "end" which is equivalent to the last element in this level. A given path may point to different rows during the lifetime of a tree, since the position of a row is dependent on the sort order and changes if rows are inserted or deleted before the referenced row.

    A path may be converted to a reference. A reference points during the lifetime of the tree and the lifetime of the referenced row to the same row, independent of sort order or insertion or deletion. Since a reference has to be stored inside the tree widget, it should be deleted if it is not needed any more.

    Commands

    id add pathOrReference row-list
    Add rows as children to the pathOrReference pathOrReference. The new rows are placed behind existing rows. Use the empty path {} to add toplevel rows. The command returns a list of paths to every new row. If the column type is "image", the entry must be a percent string of type file which determines the image file to be loaded (e.g. ("%/./gnocl.png")
    Options
    -singleRow boolean (default: false)
    If set to true, row-list is not a list of rows but only a list of elements for a single row. This option exists only to simplify the addition of one single row.
    -singleColumn boolean (default: false)
    If set to true, row-list is not a list of rows but only a list of one element for every row. This option exists only to simplify the addition of one single column.
    id addBegin pathOrReference row-list
    Same as add, but adds the new rows before existing rows.
    id addEnd pathOrReference row-list
    Same as add.
    id cellConfigure pathOrReference column [-option value...]
    Configure a cell.
    Options
    -value string
    Value of the cell. The type must correspond to the type of the column.
    -visible boolean (default: 1)
    Whether this cell is visible.
    id collapse [-option value...]
    Collapse a row.
    Options
    -path pathOrReference (default: 0)
    Which row to collapse.
    id columnCget column option
    Returns the value for one column option. The option may have any of the values accepted by columnConfigure. TODO: not yet all options implemented.
    id columnConfigure column [-option value...]
    Configure a column
    Options
    -autoResize boolean (default: true)
    Whether the width of the column should automatically increase if necessary
    -onCellData string (default: "")
    Command which is executed, before the content of a cell is rendered. This can be used to configure the cells dependent on their content. The command must return valid row configuration options (e.g. "-foreground red"). Before evaluation the following percent strings are substituted:

    %w    widget name
    %p    path of the cell
    %v    value (content) of the cell
    -onEdited string (default: "")
    Only valid for editable columns. Command which is executed, if a cell in this column is edited. Before evaluation the following percent strings are substituted:

    %w    widget name
    %p    path of selected cell
    %v    new text (value)
    -onToggled string (default: "")
    Only valid for boolean columns. Command which is executed, if it a cell in this column is toggled. Before evaluation the following percent strings are substituted:

    %w    widget name
    %p    path of selected cell
    -visible boolean (default: 1)
    Whether this column is visible.
    -clickable boolean
    Whether it can be clicked on the column header and sort this column.
    -title string (default: "")
    Title of the column.
    -resizable boolean (default: 1)
    Whether the column can be resized by the user.
    -reorderable boolean
    Whether the column can be moved to another place in the tree.
    -minWidth integer
    Minimum width of the column in pixel.
    -maxWidth integer
    Maximum width of the column in pixel.
    -titleAlign one of  left, center, right or a float between 0 and 1
    Horizontal alignment of the title.
    -align one of topLeft, top, topRight, left, center, right, bottomLeft, bottom, or bottomRight
    Alignment of the cells.
    -width integer
    Width of the cells.
    -height integer
    Height of the cells.
    -xPad integer
    Horizontal padding of the column.
    -yPad integer
    Vertical padding of the column.
    -background color
    Background colour of the cells.
    -foreground color
    Foreground colour of the cells.
    -font font
    Font used for the rendering of the cells.
    -fontFamily string
    Font used for the rendering of the cells.
    -fontStyle one of normal, oblique or italic (default: normal)
    Font style used for the rendering of the cells.
    -fontVariant one of normal or smallCaps (default: normal)
    Font variant used for the rendering of the cells.
    -fontWeight one of ultralight, light, normal, bold, ultrabold or heavy (default: normal)
    Font weight used for the rendering of the cells.
    -fontRise integer (default: 0)
    How many pixels the text should be risen.
    -fontStretch string (default: normal)
    Font stretch used for the rendering of the cells. Use one of ultraCondensed, extraCondensed, condensed, semiCondensed, normal, semiExpanded, expanded, extraExpanded or ultraExpanded
    -fontSize integer
    Font size used for the rendering of the cells.
    -fontScale float or one of xx-small, x-small, small, medium, large, x-large or xx-large (default: normal)
    Font scale used for the rendering of the cells.
    -strikethrough boolean (default: 0)
    Whether the text is struck through.
    -underline one of none, single, float, low (default: none)
    How the text in the cells should be underlined.
    -editable boolean (default: 0)
    Whether the text in the cells can be edited.
    -wrapMode string (default: none)
    Whether the text in the cells should be wrapped within the available row. One of word, char or none.
    -wrapWith int (default: 0)
    Set the width (in pixels) of text line prior to wrapping occurs.
    id configure [-option value...]
    Configure the widget. Option may have any of the values accepted by the tree command except from columns and -types.
    id coordsToPath x y
    Calculates from the given windows coordinates x and y (for example aquired from the onButtonPress callback) to a path. Returns a list of four elements: a path, a column, x cell coordinate and y cell coordinate.
    id delete
    Deletes the widget and the associated tcl command.
    id deleteReference reference
    Deletes a reference. The reference may not be used after it has been deleted.
    id erase startPathOrReference ?endPathOrReference?
    Deletes all rows between startPathOrReference and endPathOrReference. Deletes only one row if only startPathOrReference is given. If endPathOrReference is "end" deletes all child rows of the parent of startPathOrReference starting at startPathOrReference. "erase 0 end" deletes all rows.
    id expand [-option value...]
    Expand a row.
    Options
    -path pathOrReference (default: 0)
    Which row to expand.
    -recursive boolean (default: 1)
    Whether to expand all children recursively.
    id get pathOrReference column
    Get the value of one cell.
    id getNumChildren ?pathOrReference?
    Returns the number of children for the given pathOrReference. If no pathOrReference is given the number of top level rows is returned.
    id getReference path
    Returns a reference to path.
    id getSelection
    Returns a list of the paths of the selected rows.
    id onSelectionChanged
    Executes the onSelectionChanged command, if there is any. Otherwise does nothing.
    id setSelection pathOrReference-list [-option value...]
    Selects each row that is given in pathOrReference-list. The onSelectionChanged callback is not called. If pathOrReference is "all" all rows are selected. To select more than one row, selectionMode must be set to multiple or extended.
    Options
    -add boolean (default: false)
    If set to true, the given rows are added to the selection, else the selection contains only the given rows.
    -unselect boolean (default: false)
    If set to true, the selection is removed from the given rows.
    -single boolean (default: false)
    If set to true, pathOrReference-list is not a list of paths but only one single pathOrReference. This option exists only to simplify the selection of one single row.
    id referenceToPath reference
    Returns the path of reference.
    id scrollToPosition [-option value...]
    Scrolls the widget so that the specified row is visible. If only "-column" is given, the widget is scrolled only horizontal so that this column is visible. If neither "-column" nor "-path" is given, the widget is scrolled to the last expanded row.
    Options
    -align  one of topLeft, top, topRight, left, center, right, bottomLeft, bottom, or bottomRight
    Specifies where the row shall be shown.
    -path pathOrReference
    Specifies which row shall be shown.
    -column integer
    Specifies which column shall be shown.
    id setCursor pathOrReference [-option value...]
    Sets the cursor to a specific row.
    Options
    -column integer
    Sets the cursor to a specific column in the row
    -startEdit boolean (default: 0)
    Whether to start editing the cell given by column and row. The column has to be editable and the tree has to be realized.

    Example

    set tree [gnocl::tree \
        -types {string integer} \
        -titles {"" "# of Legs"}]

    $tree add {} {Mamals Birds Bugs}

    $tree add 0 {{Cat 4} {Dog 4} {Human 2}}

    foreach {paro pred} [$tree add 1 {Parrots Predator}] {}

    $tree add $paro {{Cockatoo 2} {Amazone 2}}

    $tree add $pred {{Hawk 2} {Eagle 2}}

    $tree expand \
        -path "1" \
        -recursive 1

    gnocl::window \
        -title "Tree" \
        -child $tree \
        -defaultWidth 300 \
        -defaultHeight 200

    Sections