plotAndPlayButtons {plotAndPlayGTK}R Documentation

Utilities for plotAndPlayGTK buttons

Description

Make new buttons for a plotAndPlay plot window.

Usage

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)

Arguments

label the button label.
icon.name name of the GTK icon to use, starting with "gtk-". See 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.

Details

plotAndPlayButtons and plotAndPlayBasicButtons are lists of calls to generate gtkToolItems. 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.

Value

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.

Author(s)

Felix Andrews felix@nfrac.org

See Also

playwith

Examples

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

[Package plotAndPlayGTK version 0.8.72 Index]