EVOLUTION-MANAGER
Edit File: getGraphicsEvent.html
<!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Strict//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-strict.dtd"><html xmlns="http://www.w3.org/1999/xhtml"><head><title>R: Wait for a mouse or keyboard event from a graphics window</title> <meta http-equiv="Content-Type" content="text/html; charset=utf-8" /> <link rel="stylesheet" type="text/css" href="R.css" /> </head><body> <table width="100%" summary="page for getGraphicsEvent {grDevices}"><tr><td>getGraphicsEvent {grDevices}</td><td style="text-align: right;">R Documentation</td></tr></table> <h2>Wait for a mouse or keyboard event from a graphics window</h2> <h3>Description</h3> <p>This function waits for input from a graphics window in the form of a mouse or keyboard event. </p> <h3>Usage</h3> <pre> getGraphicsEvent(prompt = "Waiting for input", onMouseDown = NULL, onMouseMove = NULL, onMouseUp = NULL, onKeybd = NULL, onIdle = NULL, consolePrompt = prompt) setGraphicsEventHandlers(which = dev.cur(), ...) getGraphicsEventEnv(which = dev.cur()) setGraphicsEventEnv(which = dev.cur(), env) </pre> <h3>Arguments</h3> <table summary="R argblock"> <tr valign="top"><td><code>prompt</code></td> <td> <p>prompt to be displayed to the user in the graphics window</p> </td></tr> <tr valign="top"><td><code>onMouseDown</code></td> <td> <p>a function to respond to mouse clicks</p> </td></tr> <tr valign="top"><td><code>onMouseMove</code></td> <td> <p>a function to respond to mouse movement</p> </td></tr> <tr valign="top"><td><code>onMouseUp</code></td> <td> <p>a function to respond to mouse button releases</p> </td></tr> <tr valign="top"><td><code>onKeybd</code></td> <td> <p>a function to respond to key presses</p> </td></tr> <tr valign="top"><td><code>onIdle</code></td> <td> <p>a function to call when no events are pending</p> </td></tr> <tr valign="top"><td><code>consolePrompt</code></td> <td> <p>prompt to be displayed to the user in the console</p> </td></tr> <tr valign="top"><td><code>which</code></td> <td> <p>which graphics device does the call apply to?</p> </td></tr> <tr valign="top"><td><code>...</code></td> <td> <p>items including handlers to be placed in the event environment</p> </td></tr> <tr valign="top"><td><code>env</code></td> <td> <p>an environment to be used as the event environment</p> </td></tr> </table> <h3>Details</h3> <p>These functions allow user input from some graphics devices (currently only the <code>windows()</code>, <code>X11(type = "Xlib")</code> and <code>X11(type = "cairo")</code> screen displays in base <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span>). Event handlers may be installed to respond to events involving the mouse or keyboard. </p> <p>The functions are related as follows. If any of the first six arguments to <code>getGraphicsEvent</code> are given, then it uses those in a call to <code>setGraphicsEventHandlers</code> to replace any existing handlers in the current device. This is for compatibility with pre-2.12.0 <span style="font-family: Courier New, Courier; color: #666666;"><b>R</b></span> versions. The current normal way to set up event handlers is to set them using <code>setGraphicsEventHandlers</code> or <code>setGraphicsEventEnv</code> on one or more graphics devices, and then use <code>getGraphicsEvent()</code> with no arguments to retrieve event data. <code>getGraphicsEventEnv()</code> may be used to save the event environment for use later. </p> <p>The names of the arguments in <code>getGraphicsEvent</code> are special. When handling events, the graphics system will look through the event environment for functions named <code>onMouseDown</code>, <code>onMouseMove</code>, <code>onMouseUp</code>, <code>onKeybd</code>, and <code>onIdle</code>, and use them as event handlers. It will use <code>prompt</code> for a label on the graphics device. Two other special names are <code>which</code>, which will identify the graphics device, and <code>result</code>, where the result of the last event handler will be stored before being returned by <code>getGraphicsEvent()</code>. </p> <p>The mouse event handlers should be functions with header <code>function(buttons, x, y)</code>. The coordinates <code>x</code> and <code>y</code> will be passed to mouse event handlers in device independent coordinates (i.e., the lower left corner of the window is <code>(0,0)</code>, the upper right is <code>(1,1)</code>). The <code>buttons</code> argument will be a vector listing the buttons that are pressed at the time of the event, with 0 for left, 1 for middle, and 2 for right. </p> <p>The keyboard event handler should be a function with header <code>function(key)</code>. A single element character vector will be passed to this handler, corresponding to the key press. Shift and other modifier keys will have been processed, so <code>shift-a</code> will be passed as <code>"A"</code>. The following special keys may also be passed to the handler: </p> <ul> <li><p> Control keys, passed as <code>"Ctrl-A"</code>, etc. </p> </li> <li><p> Navigation keys, passed as one of<br /> <code>"Left", "Up", "Right", "Down", "PgUp", "PgDn", "End", "Home"</code> </p> </li> <li><p> Edit keys, passed as one of <code>"Ins", "Del"</code> </p> </li> <li><p> Function keys, passed as one of <code>"F1", "F2", ...</code> </p> </li></ul> <p>The idle event handler <code>onIdle</code> should be a function with no arguments. If the function is undefined or <code>NULL</code>, then R will typically call a system function which (efficiently) waits for the next event to appear on a filehandle. Otherwise, the idle event handler will be called whenever the event queue of the graphics device was found to be empty, i.e. in an infinite loop. This feature is intended to allow animations to respond to user input, and could be CPU-intensive. Currently, <code>onIdle</code> is only implemented for <code>X11()</code> devices. </p> <p>Note that calling <code>Sys.sleep()</code> is not recommended within an idle handler - <code>Sys.sleep()</code> removes pending graphics events in order to allow users to move, close, or resize windows while it is executing. Events such as mouse and keyboard events occurring during <code>Sys.sleep()</code> are lost, and currently do not trigger the event handlers registered via <code>getGraphicsEvent</code> or <code>setGraphicsEventHandlers</code>. </p> <p>The event handlers are standard R functions, and will be executed as though called from the event environment. </p> <p>In an interactive session, events will be processed until </p> <ul> <li><p> one of the event handlers returns a non-<code>NULL</code> value which will be returned as the value of <code>getGraphicsEvent</code>, or </p> </li> <li><p> the user interrupts the function from the console. </p> </li></ul> <h3>Value</h3> <p>When run interactively, <code>getGraphicsEvent</code> returns a non-<code>NULL</code> value returned from one of the event handlers. In a non-interactive session, <code>getGraphicsEvent</code> will return <code>NULL</code> immediately. It will also return <code>NULL</code> if the user closes the last window that has graphics handlers. </p> <p><code>getGraphicsEventEnv</code> returns the current event environment for the graphics device, or <code>NULL</code> if none has been set. </p> <p><code>setGraphicsEventEnv</code> and <code>setGraphicsEventHandlers</code> return the previous event environment for the graphics device. </p> <h3>Author(s)</h3> <p>Duncan Murdoch</p> <h3>Examples</h3> <pre> # This currently only works on the Windows, X11(type = "Xlib"), and # X11(type = "cairo") screen devices... ## Not run: savepar <- par(ask = FALSE) dragplot <- function(..., xlim = NULL, ylim = NULL, xaxs = "r", yaxs = "r") { plot(..., xlim = xlim, ylim = ylim, xaxs = xaxs, yaxs = yaxs) startx <- NULL starty <- NULL prevx <- NULL prevy <- NULL usr <- NULL devset <- function() if (dev.cur() != eventEnv$which) dev.set(eventEnv$which) dragmousedown <- function(buttons, x, y) { startx <<- x starty <<- y prevx <<- 0 prevy <<- 0 devset() usr <<- par("usr") eventEnv$onMouseMove <- dragmousemove NULL } dragmousemove <- function(buttons, x, y) { devset() deltax <- diff(grconvertX(c(startx, x), "ndc", "user")) deltay <- diff(grconvertY(c(starty, y), "ndc", "user")) if (abs(deltax-prevx) + abs(deltay-prevy) > 0) { plot(..., xlim = usr[1:2]-deltax, xaxs = "i", ylim = usr[3:4]-deltay, yaxs = "i") prevx <<- deltax prevy <<- deltay } NULL } mouseup <- function(buttons, x, y) { eventEnv$onMouseMove <- NULL } keydown <- function(key) { if (key == "q") return(invisible(1)) eventEnv$onMouseMove <- NULL NULL } setGraphicsEventHandlers(prompt = "Click and drag, hit q to quit", onMouseDown = dragmousedown, onMouseUp = mouseup, onKeybd = keydown) eventEnv <- getGraphicsEventEnv() } dragplot(rnorm(1000), rnorm(1000)) getGraphicsEvent() par(savepar) ## End(Not run) </pre> <hr /><div style="text-align: center;">[Package <em>grDevices</em> version 3.6.0 <a href="00Index.html">Index</a>]</div> </body></html>