getGraphicsEvent          package:grDevices          R Documentation

_W_a_i_t _f_o_r _a _m_o_u_s_e _o_r _k_e_y_b_o_a_r_d _e_v_e_n_t _f_r_o_m _a _g_r_a_p_h_i_c_s _w_i_n_d_o_w

_D_e_s_c_r_i_p_t_i_o_n:

     This function waits for input from a graphics window in the form
     of a mouse or keyboard event.

_U_s_a_g_e:

     getGraphicsEvent(prompt = "Waiting for input", 
                      onMouseDown = NULL, onMouseMove = NULL,
                      onMouseUp = NULL, onKeybd = NULL)

_A_r_g_u_m_e_n_t_s:

  prompt: prompt to be displayed to the user

onMouseDown: a function to respond to mouse clicks

onMouseMove: a function to respond to mouse movement

onMouseUp: a function to respond to mouse button releases

 onKeybd: a function to respond to key presses

_D_e_t_a_i_l_s:

     This function allows user input from some graphics devices
     (currently only the Windows screen display).  When called, event
     handlers may be  installed to respond to events involving the
     mouse or keyboard.  

     The mouse event handlers should be functions with header 
     'function(buttons, x, y)'.  The coordinates 'x' and 'y' will be
     passed to mouse event handlers in device independent coordinates
     (i.e. the lower left corner of the window is '(0,0)',  the upper
     right is '(1,1)').  The 'buttons' 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.

     The keyboard event handler should be a function with header
     'function(key)'.  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 'shift-a' will be
     passed as '"A"'.  The following special keys may also be passed to
     the handler:

        *  Control keys, passed as '"Ctrl-A"', etc.

        *  Navigation keys, passed as one of '"Left", "Up", "Right",
           "Down", "PgUp", "PgDn", "End", "Home"'

        *  Edit keys, passed as one of '"Ins", "Del"'

        *  Function keys, passed as one of '"F1", "F2", ...'

     The event handlers are standard R functions, and will be executed
     in an environment as though they had been called directly from
     'getGraphicsEvent'.

     Events will be processed until

        *  one of the event handlers returns a non-'NULL' value which
           will be returned as the value of 'getGraphicsEvent', or 

        *  the user interrupts the function from the console.

_V_a_l_u_e:

     A non-'NULL' value returned from one of the event handlers.

_A_u_t_h_o_r(_s):

     Duncan Murdoch

_E_x_a_m_p_l_e_s:

     ## Not run: 
         mousedown <- function(buttons, x, y) {
             plx <- grconvertX(x, "ndc", "user")
             ply <- grconvertY(y, "ndc", "user")    
             cat("Buttons ", paste(buttons, collapse=" "), " at ndc",
                 x, y, "user", plx, ply, "\n")
             points(plx, ply, col="red", pch=19, cex=2)
             if (x > 0.85 && y > 0.85) "Done"
             else NULL
         }
         
         mousemove <- function(buttons, x, y) {
             plx <- grconvertX(x, "ndc", "user")
             ply <- grconvertY(y, "ndc", "user")    
             points(plx, ply)
             NULL
         }
         
         keybd <- function(key) {
             cat("Key <", key, ">\n", sep = "")
         }
         
         plot(0:1, 0:1, type='n')
         getGraphicsEvent("Click on upper right to quit",
                          onMouseDown = mousedown,
                          onMouseMove = mousemove,
                          onKeybd = keybd)
     ## End(Not run)