gtree: constructor for widget to display heirarchical data
In gWidgets2: Rewrite of gWidgets API for Simplified GUI Construction

Description Usage Arguments Details Examples

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).

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

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, ...)

`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

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.

##################################################
## 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)