plotAndPlayButtons      package:plotAndPlayGTK      R Documentation

_U_t_i_l_i_t_i_e_s _f_o_r _p_l_o_t_A_n_d_P_l_a_y_G_T_K _b_u_t_t_o_n_s

_D_e_s_c_r_i_p_t_i_o_n:

     Make new buttons for a 'plotAndPlay' plot window.

_U_s_a_g_e:

     plotAndPlayButtons
     plotAndPlayBasicButtons

     quickTool(label, icon.name = NULL, tooltip = NULL, f, data = NULL, isToggle = F)

     plotAndPlayGetState(item = NULL, name = plotAndPlayGetCurrID())
     plotAndPlaySetState(..., name = plotAndPlayGetCurrID())

     plotAndPlayGetCurrID()
     plotAndPlaySetCurrID(name)

     plotAndPlayUpdate()

     plotAndPlayDoFocus(highlight = T, ...)
     plotAndPlayMakePrompt()
     plotAndPlayUnmakePrompt()
     plotAndPlaySetPrompt(text)

     plotAndPlayGetToolbar()
     plotAndPlayGetDA()

     plotAndPlaySetRawXLim(x)
     plotAndPlaySetRawYLim(x)

     unlogX(x, the.call, is.lattice = T)
     unlogY(x, the.call, is.lattice = T)

     xy.coords.call(the.call, envir = parent.frame(), log = NULL, recycle = TRUE)

_A_r_g_u_m_e_n_t_s:

   label: the button label. 

icon.name: name of the GTK icon to use, starting with "gtk-".  See
          <URL:
          http://developer.gnome.org/doc/API/2.0/gtk/gtk-Stock-Items.html#GTK-STOCK-ABOUT:CAPS>
          for a list. 

 tooltip: the button tooltip. 

       f: function to be called when the button is clicked ("callback
          function"). 

    data: extra data to be passed to the callback function. 

isToggle: whether the button should be a 'gtkToggleToolButton'. 

    item: name of one element of the state list (see below).  If 'NULL'
          (the default), the whole list is returned or set. 

    name: name of a plot window. This can almost always be ignored. 

     ...: to 'plotAndPlaySetState',  pass one named item to replace the
          corresponding named element of the state list (see below). 
          If not named, it will replace the whole state list. 

highlight: passed to 'trellis.focus'. 

    text: text to display in the plot window prompt. 

       x: numeric vector. 

the.call: a plot call. Ignored if 'is.lattice=F'. 

is.lattice: whether the plot call generates a lattice plot. 

   envir: environment in which to evaluate call arguments. 

log, recycle: passed to 'xy.coords'. 

_D_e_t_a_i_l_s:

     'plotAndPlayButtons' and 'plotAndPlayBasicButtons' are lists of
     calls to generate 'gtkToolItem's. These are used as buttons in a
     'plotAndPlay' plot window.

     New buttons can be defined: see the 'Examples' section of this
     page.

     'quickTool' is a convenience function to create a 'gtkToolButton'
     with the given label, icon, tooltip and click handler. For
     example, one element of 'plotAndPlayButtons' is
     'zoomout=quickTool("Zoom out", "gtk-zoom-out",
     f=.plotAndPlay_zoomout_event)'.

     'plotAndPlayGetState' can be used by callback functions to get
     access to the plot window and plot state.  It returns a list (see
     below for details), or one of its elements ('item'),  which can be
     modified and passed back to 'plotAndPlaySetState'.

     'plotAndPlayUpdate' re-generates the current plot display (e.g.
     after updating the call).

     'plotAndPlayDoFocus' brings one lattice panel into focus.  If
     there is only one panel it is chosen automatically and without
     highlighting. Otherwise the user is prompted to choose one.  It
     returns the new focus (see 'focus' item below) or NULL if the user
     cancelled.

     The 'playwith' window can show a simple prompt to the user. This
     must be initialised with 'plotAndPlayMakePrompt', then set with
     'plotAndPlaySetPrompt',  and finally removed with
     'plotAndPlayUnmakePrompt'.

     'plotAndPlayGetToolbar' returns the 'gtkToolbar',  and
     'plotAndPlayGetDA' returns the 'gtkDrawingArea'.

     'plotAndPlaySetRawXLim' converts a numeric range, in the raw
     native plot coordinates, to values suitable for  the plot 'xlim'
     argument: it may convert back from log-transformed scales, convert
     to factor levels, and convert to a date/time format. It then
     updates the current plot call with the new value. Note: this
     function requires a panel to be in focus, since it uses
     'trellis.panelArgs()'. 

     'unlogX' just converts back from log-transformed scales if
     necessary.

     'xy.coords.call' is a wrapper around 'xy.coords' based on the call
     arguments.

_V_a_l_u_e:

     'plotAndPlayGetState()' returns a list containing at least: 

     win: a 'gtkWindow' (the plot window).

     dev: the plot device number.

    call: the current plot call.

     env: local environment used to store evaluated plot call
          arguments.

 id.call: the call to 'identify' or similar, used to label data points.

label.args: style arguments for labelling points.

nav.scales: see 'plotAndPlay'.

trans.scales: see 'plotAndPlay'.

     ids: a list, each item contains a vector of subscripts for the
          points currently labelled in the named lattice packet. For
          non-lattice plots, there is only one item '"all"'.

 brushed: a list, each item contains a vector of subscripts for the
          points currently brushed in the named lattice packet. 

is.lattice: logical: is it a lattice plot?

   focus: a list with items 'col' and 'row' for a lattice panel if one
          is in focus. Otherwise it is 'list(col=0, row=0)'.

    page: current lattice page number.

_A_u_t_h_o_r(_s):

     Felix Andrews felix@nfrac.org

_S_e_e _A_l_s_o:

     'playwith'

_E_x_a_m_p_l_e_s:

     ## Not run: 

     ## defining new buttons (and other widgets) for the toolbar...

     require(lattice)

     ## A kind of "OK" button: It gets the subscripts of currently labelled points 
     ## (from 'identify') and passes them to a function: in this case, just 'print'.
     showids_handler <- function(widget, user.data) {
             ids <- plotAndPlayGetState("ids")
             print(unique(unlist(ids)))
     }
     showids_button <- quote(quickTool("Show IDs", "gtk-yes", 
             tooltip="Print out indices of the selected points", f=showids_handler))
     playwith(xyplot(Income ~ Population / Area, data=data.frame(state.x77)), 
             extra.buttons=list(showids_button))

     ## A toggle button to add a smoothing line to xyplot
     ## (assumes the 'type' argument will be passed to panel.xyplot)
     smooth_handler <- function(widget, user.data) {
             tmp.state <- plotAndPlayGetState()
             # get the current 'type' argument
             plotType <- eval(tmp.state$call$type, tmp.state$env)
             if (is.null(plotType)) plotType <- "p"
             # remove "smooth" type if it is already there
             if (!is.na(i <- match("smooth", plotType))) plotType <- plotType[-i]
             # add "smooth" type if the toggle button is active
             if (widget["active"]) plotType <- c(plotType, "smooth")
             # update state
             tmp.state$call$type <- plotType
             plotAndPlaySetState(tmp.state)
             plotAndPlayUpdate()
     }
     smooth_button <- quote(quickTool("Smooth", "gtk-add", f=smooth_handler, 
             tooltip="Overlay loess smooth (with default span=2/3)", isToggle=T))
     playwith(xyplot(sunspot.year ~ 1700:1988, type="l"), 
             extra.buttons=list(smooth_button))

     ## Get the current plot limits and print them (works with lattice / traditional)
     ## It would be simpler to grab the xlim/ylim arguments, but they might be NULL.
     showlims_handler <- function(widget, user.data) {
             tmp.state <- plotAndPlayGetState()
             # get current plot limits
             if (tmp.state$is.lattice) {
                     # lattice plot
                     if (!any(tmp.state$focus)) {
                             trellis.focus("panel", 1, 1, highlight=F)
                     }
                     require(grid)
                     xlim <- convertX(unit(0:1, "npc"), "native", valueOnly=T)
                     ylim <- convertY(unit(0:1, "npc"), "native", valueOnly=T)
                     if (!any(tmp.state$focus)) trellis.unfocus()
             } else {
                     # traditional graphics plot
                     xlim <- par("usr")[1:2]
                     ylim <- par("usr")[3:4]
             }
             xlim <- unlogX(xlim, tmp.state$call, tmp.state$is.lattice)
             ylim <- unlogY(ylim, tmp.state$call, tmp.state$is.lattice)
             print(list(x=signif(xlim, 3), y=signif(ylim, 3)))
     }
     showlims_button <- quote(quickTool("Limits", "gtk-yes",
             tooltip="Print out current plot limits", f=showlims_handler))
     playwith(stripplot(Sepal.Length ~ Species, iris, jitter=T, factor=0.3),
             extra.buttons=c(list("logscale", "zero"), showlims_button))

     ## A more complex toolbar item:
     ## A "spinbutton" to choose a number 'n', then group the data into 'n' clusters.
     ## Should work with plot or xyplot.
     my_cluster_handler <- function(widget, user.data) {
             tmp.state <- plotAndPlayGetState()
             n <- widget["value"]
             xy <- xy.coords.call(tmp.state$call, tmp.state$env)
             groups <- NULL
             if (n > 1) {
                     clusts <- kmeans(cbind(xy$x,xy$y), n)
                     labels <- paste("#", 1:n, " (n = ", clusts$size, ")", sep="")
                     groups <- factor(clusts$cluster, labels=labels)
             }
             # update state
             #tmp.state$call$groups <- groups
             # to avoid putting a big vector in the plot call, store in local env:
             assign("auto_groups", groups, envir=tmp.state$env)
             tmp.state$call$groups <- if (!is.null(groups)) quote(auto_groups)
             plotAndPlaySetState(tmp.state)
             plotAndPlayUpdate()
     }
     my_cluster_spinner <- quote({
             spinner <- gtkSpinButton(min=1, max=10, step=1)
             spinner["value"] <- 1
             gSignalConnect(spinner, "value-changed", my_cluster_handler)
             vbox <- gtkVBox()
             vbox$packStart(gtkLabel("Clusters:"))
             vbox$packStart(spinner)
             foo <- gtkToolItem()
             foo$add(vbox)
             foo
     })
     # need to generate random data outside the plot call, otherwise it changes!
     xdata <- rnorm(100)
     ydata <- rnorm(100) * xdata / 2
     playwith(xyplot(ydata ~ xdata, aspect="iso", auto.key=list(space="right")), 
             extra.buttons=list(my_cluster_spinner))

     ## End(Not run)

