The R Project SVN R

Rev

Rev 68948 | Go to most recent revision | Show entire file | Ignore whitespace | Details | Blame | Last modification | View Log | RSS feed

Rev 68948 Rev 72261
Line 15... Line 15...
15 
}
 15 
}
16 
\usage{
 16 
\usage{
17 
getGraphicsEvent(prompt = "Waiting for input",
 17 
getGraphicsEvent(prompt = "Waiting for input",
18 
                 onMouseDown = NULL, onMouseMove = NULL,
 18 
                 onMouseDown = NULL, onMouseMove = NULL,
19 
                 onMouseUp = NULL, onKeybd = NULL,
 19 
                 onMouseUp = NULL, onKeybd = NULL,
- 
 
 20 
                 onIdle = NULL,
20 
                 consolePrompt = prompt)
 21 
                 consolePrompt = prompt)
21 
setGraphicsEventHandlers(which = dev.cur(), ...)
 22 
setGraphicsEventHandlers(which = dev.cur(), ...)
22 
getGraphicsEventEnv(which = dev.cur())
 23 
getGraphicsEventEnv(which = dev.cur())
23 
setGraphicsEventEnv(which = dev.cur(), env)
 24 
setGraphicsEventEnv(which = dev.cur(), env)
24 
 
 25 
 
Line 27... Line 28...
27 
  \item{prompt}{prompt to be displayed to the user in the graphics window}
 28 
  \item{prompt}{prompt to be displayed to the user in the graphics window}
28 
  \item{onMouseDown}{a function to respond to mouse clicks}
 29 
  \item{onMouseDown}{a function to respond to mouse clicks}
29 
  \item{onMouseMove}{a function to respond to mouse movement}
 30 
  \item{onMouseMove}{a function to respond to mouse movement}
30 
  \item{onMouseUp}{a function to respond to mouse button releases}
 31 
  \item{onMouseUp}{a function to respond to mouse button releases}
31 
  \item{onKeybd}{a function to respond to key presses}
 32 
  \item{onKeybd}{a function to respond to key presses}
- 
 
 33 
  \item{onIdle}{a function to call when no events are pending}
32 
  \item{consolePrompt}{prompt to be displayed to the user in the console}
 34 
  \item{consolePrompt}{prompt to be displayed to the user in the console}
33 
  \item{which}{which graphics device does the call apply to?}
 35 
  \item{which}{which graphics device does the call apply to?}
34 
  \item{...}{items including handlers to be placed in the event environment}
 36 
  \item{...}{items including handlers to be placed in the event environment}
35 
  \item{env}{an environment to be used as the event environment}
 37 
  \item{env}{an environment to be used as the event environment}
36 
}
 38 
}
37 
\details{
 39 
\details{
38 
These functions allow user input from some graphics devices (currently
 40 
These functions allow user input from some graphics devices (currently
39 
only the \code{windows()} and \code{X11(type = "Xlib")} screen displays
 41 
only the \code{windows()}, \code{X11(type = "Xlib")}
- 
 
 42 
and \code{X11(type = "cairo")} screen displays
40 
in base \R{}). Event handlers may be installed to respond to events
 43 
in base \R{}). Event handlers may be installed to respond to events
41 
involving the mouse or keyboard.
 44 
involving the mouse or keyboard.
42 
 
 45 
 
43 
The functions are related as follows.  If any of the first five
 46 
The functions are related as follows.  If any of the first six
44 
arguments to \code{getGraphicsEvent} are given, then it uses those
 47 
arguments to \code{getGraphicsEvent} are given, then it uses those
45 
in a call to \code{setGraphicsEventHandlers} to replace any existing
 48 
in a call to \code{setGraphicsEventHandlers} to replace any existing
46 
handlers in the current device.  This is for compatibility with pre-2.12.0 \R{}
 49 
handlers in the current device.  This is for compatibility with pre-2.12.0 \R{}
47 
versions.  The current normal way to set up event handlers is to
 50 
versions.  The current normal way to set up event handlers is to
48 
set them using \code{setGraphicsEventHandlers} or \code{setGraphicsEventEnv} on
 51 
set them using \code{setGraphicsEventHandlers} or \code{setGraphicsEventEnv} on
Line 51... Line 54...
51 
\code{getGraphicsEventEnv()} may be used to save the event environment
 54 
\code{getGraphicsEventEnv()} may be used to save the event environment
52 
for use later.
 55 
for use later.
53 
 
 56 
 
54 
The names of the arguments in \code{getGraphicsEvent} are special.  When
 57 
The names of the arguments in \code{getGraphicsEvent} are special.  When
55 
handling events, the graphics system will look through the event
 58 
handling events, the graphics system will look through the event
56 
environment for functions named \code{onMouseDown}, \code{onMouseMove}, \code{onMouseUp}
 59 
environment for functions named \code{onMouseDown}, \code{onMouseMove},
57 
and \code{onKeybd} and use them as event handlers.  It will use
 60 
\code{onMouseUp}, \code{onKeybd}, and \code{onIdle}, and use them as
- 
 
 61 
event handlers.  It will use
58 
\code{prompt} for a label on the graphics device.  Two other special names are
 62 
\code{prompt} for a label on the graphics device.  Two other special names are
59 
\code{which}, which will identify the graphics device, and
 63 
\code{which}, which will identify the graphics device, and
60 
\code{result}, where the result of the last event
 64 
\code{result}, where the result of the last event
61 
handler will be stored before being returned by \code{getGraphicsEvent()}.
 65 
handler will be stored before being returned by \code{getGraphicsEvent()}.
62 
 
 66 
 
Line 80... Line 84...
80 
     \code{"Left", "Up", "Right", "Down", "PgUp", "PgDn", "End", "Home"}
 84 
     \code{"Left", "Up", "Right", "Down", "PgUp", "PgDn", "End", "Home"}
81 
     \item Edit keys, passed as one of \code{"Ins", "Del"}
 85 
     \item Edit keys, passed as one of \code{"Ins", "Del"}
82 
     \item Function keys, passed as one of \code{"F1", "F2", ...}
 86 
     \item Function keys, passed as one of \code{"F1", "F2", ...}
83 
}
 87 
}
84 
 
 88 
 
- 
 
 89 
The idle event handler \code{onIdle} should be a function with no
- 
 
 90 
arguments. If the function is undefined or \code{NULL}, then R will
- 
 
 91 
typically call a system function which (efficiently) waits for the next
- 
 
 92 
event to appear on a filehandle. Otherwise, the idle event handler will
- 
 
 93 
be called whenever the event queue of the graphics device was found to
- 
 
 94 
be empty, i.e. in an infinite loop. This feature is intended to allow
- 
 
 95 
animations to respond to user input, and could be CPU-intensive.
- 
 
 96 
Currently, \code{onIdle} is only implemented for \code{X11()} devices.
- 
 
 97 
 
- 
 
 98 
Note that calling \code{Sys.sleep()} is not recommended within an idle
- 
 
 99 
handler - \code{Sys.sleep()} removes pending graphics events in order to
- 
 
 100 
allow users to move, close, or resize windows while it is executing.
- 
 
 101 
Events such as mouse and keyboard events occurring during
- 
 
 102 
\code{Sys.sleep()} are lost, and currently do not trigger the event
- 
 
 103 
handlers registered via \code{getGraphicsEvent} or
- 
 
 104 
\code{setGraphicsEventHandlers}.
- 
 
 105 
 
- 
 
 106 
 
85 
The event handlers are standard R functions, and will be executed as though called
 107 
The event handlers are standard R functions, and will be executed as though called
86 
from the event environment.
 108 
from the event environment.
87 
 
 109 
 
88 
In an interactive session, events will be processed until
 110 
In an interactive session, events will be processed until
89 
\itemize{
 111 
\itemize{
Line 106... Line 128...
106 
\code{setGraphicsEventEnv} and \code{setGraphicsEventHandlers} return the previous
 128 
\code{setGraphicsEventEnv} and \code{setGraphicsEventHandlers} return the previous
107 
event environment for the graphics device.
 129 
event environment for the graphics device.
108 
}
 130 
}
109 
\author{Duncan Murdoch}
 131 
\author{Duncan Murdoch}
110 
\examples{
 132 
\examples{
111 
# This currently only works on the Windows
 133 
# This currently only works on the Windows, X11(type = "Xlib"), and
112 
# and X11(type = "Xlib") screen devices...
 134 
# X11(type = "cairo") screen devices...
113 
\dontrun{
 135 
\dontrun{
114 
savepar <- par(ask = FALSE)
 136 
savepar <- par(ask = FALSE)
115 
dragplot <- function(..., xlim = NULL, ylim = NULL, xaxs = "r", yaxs = "r") {
 137 
dragplot <- function(..., xlim = NULL, ylim = NULL, xaxs = "r", yaxs = "r") {
116 
    plot(..., xlim = xlim, ylim = ylim, xaxs = xaxs, yaxs = yaxs)
 138 
    plot(..., xlim = xlim, ylim = ylim, xaxs = xaxs, yaxs = yaxs)
117 
    startx <- NULL
 139 
    startx <- NULL