R: Simple Point-and-Click Interface Panels

simplepanel {spatstat.geom} | R Documentation

## Simple Point-and-Click Interface Panels

### Description

These functions enable the user to create a simple, robust, point-and-click interface to any R code.

### Usage

       simplepanel(title, B, boxes, clicks,
          redraws=NULL, exit = NULL, env)

       grow.simplepanel(P, side = c("right", "left", "top", "bottom"),
          len = NULL, new.clicks, new.redraws=NULL, ..., aspect)

### Arguments

`title` | Character string giving the title of the interface panel.
`B` | Bounding box of the panel coordinates. A rectangular window (object of class `"owin"`)
`boxes` | A list of rectangular windows (objects of class `"owin"`) specifying the placement of the buttons and other interactive components of the panel.
`clicks` | A list of R functions, of the same length as `boxes`, specifying the operations to be performed when each button is clicked. Entries can also be `NULL` indicating that no action should occur. See Details.
`redraws` | Optional list of R functions, of the same length as `boxes`, specifying how to redraw each button. Entries can also be `NULL` indicating a simple default. See Details.
`exit` | An R function specifying actions to be taken when the interactive panel terminates.
`env` | An `environment` that will be passed as an argument to all the functions in `clicks`, `redraws` and `exit`.
`P` | An existing interaction panel (object of class `"simplepanel"`).
`side` | Character string identifying which side of the panel `P` should be grown to accommodate the new buttons.
`len` | Optional. Thickness of the new panel area that should be grown to accommodate the new buttons. A single number in the same units as the coordinate system of `P`.
`new.clicks` | List of R functions defining the operations to be performed when each of the new buttons is clicked.
`new.redraws` | Optional. List of R functions, of the same length as `new.clicks`, defining how to redraw each of the new buttons.
`...` | Arguments passed to `layout.boxes` to determine the layout of the new buttons.
`aspect` | Optional. Aspect ratio (height/width) of the new buttons.

### Details

These functions enable the user to create a simple, robust, point-and-click interface to any R code.

The functions `simplepanel` and `grow.simplepanel` create an object of class `"simplepanel"`. Such an object defines the graphics to be displayed and the actions to be performed when the user interacts with the panel.

The panel is activated by calling `run.simplepanel`.

The function `simplepanel` creates a panel object from basic data. The function `grow.simplepanel` modifies an existing panel object `P` by growing an additional row or column of buttons.

For `simplepanel`,

- The spatial layout of the panel is determined by the rectangles `B` and `boxes`.

- The argument `clicks` must be a list of functions specifying the action to be taken when each button is clicked (or `NULL` to indicate that no action should be taken). The list entries should have names (but there are sensible defaults). Each function should be of the form `function(env, xy)` where `env` is an `environment` that may contain shared data, and `xy` gives the coordinates of the mouse click, in the format `list(x, y)`. The function returns `TRUE` if the panel should continue running, and `FALSE` if the panel should terminate.

- The argument `redraws`, if given, must be a list of functions specifying the action to be taken when each button is to be redrawn. Each function should be of the form `function(button, name, env)` where `button` is a rectangle specifying the location of the button in the current coordinate system; `name` is a character string giving the name of the button; and `env` is the `environment` that may contain shared data. The function returns `TRUE` if the panel should continue running, and `FALSE` if the panel should terminate. If `redraws` is not given (or if one of the entries in `redraws` is `NULL`), the default action is to draw a pink rectangle showing the button position, draw the name of the button in the middle of this rectangle, and return `TRUE`.

- The argument `exit`, if given, must be a function specifying the action to be taken when the panel terminates. (Termination occurs when one of the `clicks` functions returns `FALSE`). The `exit` function should be of the form `function(env)` where `env` is the `environment` that may contain shared data. Its return value will be used as the return value of `run.simplepanel`.

- The argument `env` should be an R environment. The panel buttons will have access to this environment, and will be able to read and write data in it. This mechanism is used to exchange data between the panel and other R code.

For `grow.simplepanel`,

- the spatial layout of the new boxes is determined by the arguments `side`, `len`, `aspect` and by the additional `...` arguments passed to `layout.boxes`.

- the argument `new.clicks` should have the same format as `clicks`. It implicitly specifies the number of new buttons to be added, and the actions to be performed when they are clicked.

- the optional argument `new.redraws`, if given, should have the same format as `redraws`. It specifies the actions to be performed when the new buttons are clicked.

### Value

An object of class `"simplepanel"`.

### Author(s)

Adrian Baddeley Adrian.Baddeley@curtin.edu.au, Rolf Turner r.turner@auckland.ac.nz and Ege Rubak rubak@math.aau.dk.

### See Also

`run.simplepanel`, `layout.boxes`

### Examples

      # make boxes (alternatively use layout.boxes())
      Bminus <- square(1)
      Bvalue <- shift(Bminus, c(1.2, 0))
      Bplus <- shift(Bvalue, c(1.2, 0))
      Bdone <- shift(Bplus, c(1.2, 0))
      myboxes <- list(Bminus, Bvalue, Bplus, Bdone)
      myB <- do.call(boundingbox,myboxes)

      # make environment containing an integer count
      myenv <- new.env()
      assign("answer", 0, envir=myenv)

      # what to do when finished: return the count.
      myexit <- function(e) { return(get("answer", envir=e)) }

      # button clicks
      # decrement the count
      Cminus <- function(e, xy) {
        ans <- get("answer", envir=e)
        assign("answer", ans - 1, envir=e)
        return(TRUE)
      }
      # display the count (clicking does nothing)
      Cvalue <- function(...) { TRUE }
      # increment the count
      Cplus <- function(e, xy) {
        ans <- get("answer", envir=e)
        assign("answer", ans + 1, envir=e)
        return(TRUE)
      }
      # 'Clear' button
      Cclear <- function(e, xy) {
        assign("answer", 0, envir=e)
        return(TRUE)
      }
      # quit button
      Cdone <- function(e, xy) { return(FALSE) }

      myclicks <- list("-"=Cminus,
                       value=Cvalue,
                       "+"=Cplus,
                       done=Cdone)

      # redraw the button that displays the current value of the count
      Rvalue <- function(button, nam, e) {
         plot(button, add=TRUE)
         ans <- get("answer", envir=e)
         text(centroid.owin(button), labels=ans)
         return(TRUE)
      }

      # make the panel
      P <- simplepanel("Counter",
                       B=myB, boxes=myboxes,
                       clicks=myclicks,
                       redraws = list(NULL, Rvalue, NULL, NULL),
                       exit=myexit, env=myenv)
      # print it
      P
      # show what it looks like
      redraw.simplepanel(P)

      # ( type run.simplepanel(P) to run the panel interactively )

      # add another button to right
      Pplus <- grow.simplepanel(P, "right", new.clicks=list(clear=Cclear))

[Package spatstat.geom version 2.3-2 Index]