gtree {gWidgets2} | R Documentation

## constructor for widget to display heirarchical data

### Description

The `gtree` widget is used to present structured heirarchical data. This data may be specified through a data frame with some accompanying columns by which to split the data, or dynamically through a function (`offspring`).

generic for toolkit dispatch

For a `GTree` object, svalue refers to the path specified as a vector of keys or (if `INDEX=TRUE`) by an integer vector of offspring positions. The `drop` argument is used to indicate if the terminus of the path is returned or the entire path, defaults=TRUE. To get the data associated with a row, use the `[` method.

For a `GTree` object, svalue refers to the path specified as a vector of keys . For the assignment method, one assigns by index. That is `svalue(tr, index=TRUE) <- svalue(tr, index=TRUE)` should not change the state of the widget. (The `index=TRUE` argument is the case for setting, but not getting.)

The `[` method is used to return the data associated with a selected row. The `svalue` method returns the path or its endpoint, the `[` method returns the row data associated with the path.

The update method for `GTree` recomputes the base nodes, then reopens the given node if still available

### Usage

    gtree(x = NULL, INDICES = NULL, offspring = x, offspring.data = NULL,
      chosen.col = 1, offspring.col = 2, icon.col = NULL,
      tooltip.col = NULL, multiple = FALSE, handler = NULL, action = NULL,
      container = NULL, ..., toolkit = guiToolkit())

    .gtree(toolkit, offspring = NULL, offspring.data = NULL, chosen.col = 1,
      offspring.col = 2, icon.col = NULL, tooltip.col = NULL,
      multiple = FALSE, handler = NULL, action = NULL, container = NULL,
      ...)

    ## S3 method for class 'GTree'
    svalue(obj, index = FALSE, drop = TRUE, ...)

    ## S3 replacement method for class 'GTree'
     svalue(obj, index=TRUE, ...) <- value

    ## S3 method for class 'GTree'
    x[i, j, ..., drop = FALSE]

    ## S3 method for class 'GTree'
    update(object, ...)

### Arguments

`x` | Data frame. Optional, if given specify INDICES value to split data into heirarchical data structure
`INDICES` | Integers or column names, referring to columns of `x`. Used to form heirarchical structure. Order is important.
`offspring` | function. A function passed values `path` and `data`, the latter from `offspring.data`. The path is the current position of the parent item using the named keys from the chosen column.
`offspring.data` | Passed to second argument of `offspring` function. Used to parameterize a function call.
`chosen.col` | integer or one of column names of data frame returned by `offspring`. The chosen column gives the key and value of the path.
`offspring.col` | integer or column name. Points to column containing logical values indicating if a row has offspring.
`icon.col` | integer of one of the column names of the data frame. If provided (non-NULL), then this column should provide a stock icon name to be placed in the row for the given data.
`tooltip.col` | integer or one of the column names of the data frame. If provided (non-NULL), then the row for this item will have a tooltip given by the pointed to value.
`multiple` | logical. Is multiple selection allowed?
`handler` | A handler assigned to the default change signal. Handlers are called when some event triggers a widget to emit a signal. For each widget some default signal is assumed, and handlers may be assigned to that through `addHandlerChanged` or at construction time. Handlers are functions whose first argument, `h` in the documentation, is a list with atleast two components `obj`, referring to the object emitting the signal and `action`, which passes in user-specified data to parameterize the function call. Handlers may also be added via `addHandlerXXX` methods for the widgets, where `XXX` indicates the signal, with a default signal mapped to `addHandlerChanged` (cf. `addHandler` for a listing). These methods pass back a handler ID that can be used with `blockHandler` and `unblockHandler` to suppress temporarily the calling of the handler.
`action` | User supplied data passed to the handler when it is called
`container` | A parent container. When a widget is created it can be incorporated into the widget heirarchy by passing in a parent container at construction time. (For some toolkits this is not optional, e.g. gWidgets2tcltk or gWidgets2WWW2.)
`...` | passed to update method
`toolkit` | Each widget constructor is passed in the toolkit it will use. This is typically done using the default, which will lookup the toolkit through `guiToolkit`.
`obj` | object
`index` | index
`drop` | do we return tip or path
`value` | vector of indices
`i` | ignored
`j` | ignored
`object` | object to update

### Details

In the former case, the data frame is split up by the columns specified by INDICES. The first index is used to give the intial branches, the second index the second, etc. The end leaves are the data associated with a given path, with key given by that column specified by `chosen.col`

For the latter case, the "path" of the current node (the node and its ancestors) is passed to the `offspring` function which computes the next level in the heirarchy. This level is specified through a data frame. This data frame has special columns. The `chosen.col` specifies which column is used as the key in the path, the `icon.col` (when given) points to a stock icon name to decorate the column. Similarly, the `tooltip.columns`. The fact that a row in the data frame has offspring is specified through the `offspring.col` column, again specifed by index or column name.

### Examples

    ##################################################
    ## This tree reads a list
    offspring <- function(path=character(0), lst, ...) {
      if(length(path))
        obj <- lst[[path]]
        else
          obj <- lst
      nms <- names(obj)
      hasOffspring <- sapply(nms, function(i) {
        newobj <- obj[[i]]
        is.recursive(newobj) && !is.null(names(newobj))
        })
      data.frame(comps=nms, hasOffspring=hasOffspring, ## fred=nms,
                 stringsAsFactors=FALSE)
    }
    l <- list(a="1", b= list(a="21", b="22", c=list(a="231")))

    ## Not run:
    w <- gwindow("Tree test")
    t <- gtree(offspring=offspring, offspring.data=l, cont=w)

    ## End(Not run)

    ##################################################
    ## This tree looks at recursive objects
    describe <- function(x) UseMethod("describe")
    describe.default <- function(x) sprintf("An object with class %s", class(x)[1])
    describe.integer <- function(x) sprintf("An integer with %s value%s", length(x),
       ifelse(length(x) > 1, "s", ""))
    describe.numeric <- function(x) sprintf("A numeric with %s value%s", length(x),
       ifelse(length(x) > 1, "s", ""))
    describe.factor <- function(x) sprint("A factor with %s level%s", length(levels(x)),
       ifelse(length(levels(x)) > 1, "s", ""))

    offspring <- function(path, obj) {
      if(length(path) > 0)
        x <- obj[[path]]
      else
        x <- obj

      nms <- names(x)
      recursive <- sapply(x, function(i) {
        is.recursive(i) &&
        !is.null(attr(i, "names")) &&
        length(i) > 0
        })
      descr <- sapply(x, describe)

      data.frame(Variable=nms, offspring=recursive, Description=descr, stringsAsFactors=FALSE)
    }

    l <- lm(mpg ~ wt, mtcars)
    ## Not run:
    w <- gwindow("test")
    gtree(offspring=offspring, offspring.data=l, cont=w)

    ## End(Not run)

[Package gWidgets2 version 1.0-8 Index]