gWidgets-handlers          package:gWidgets          R Documentation

_M_e_t_h_o_d_s _t_o _a_d_d  _e_v_e_n_t _h_a_n_d_l_e_r_s _t_o _o_b_j_e_c_t_s

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

     In the gWidgets API handlers are called in reponse to certain
     events such as keystrokes or clicks. This set of methods makes a
     consistent interface to some typical events. Not all handlers are
     defined for each widget.

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

     addhandlerchanged(obj, handler = NULL, action = NULL, ...) 

     addhandlerkeystroke(obj, handler = NULL, action = NULL, ...) 

     addhandlerclicked(obj, handler = NULL, action = NULL, ...) 

     addhandlerdoubleclick(obj, handler = NULL, action = NULL, ...) 

     addhandlerrightclick(obj, handler = NULL, action = NULL, ...) 

     addhandlerexpose(obj, handler = NULL, action = NULL, ...) 

     addhandlerunrealize(obj, handler = NULL, action = NULL, ...) 

     addhandlerdestroy(obj, handler = NULL, action = NULL, ...) 

     addhandleridle (obj, handler = NULL, action = NULL, interval = 1000,   ...) 

     addpopupmenu(obj, menulist, action=NULL, ...)

     add3rdmousepopupmenu(obj, menulist, action=NULL, ...)

     removehandler(obj, ID, ...)

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

     obj: The object to assign handler to

 handler: A function to call if the given event occurs. The function's
          first argument is a list with some specific components. The
          component 'obj' contains the object that the handler was
          assigned to. The 'action' component contains the value given
          to the argument 'action'. This can be used with 'do.call' to
          make simple handlers. Or, this can be used to pass in other
          widgets, etc. 

          Sometimes there are other components. For drag and drop
          handlers the component 'dropdata' refers to the dropped data.
          For 'ggraphics' the 'addhandlerclicked' contains components
          'x' and 'y' indicating where the click occurred. 

  action: Used to pass extra information into handlers 

interval: For 'addhandleridle' this specifies the time in milliseconds
          between calls to the handler.

menulist: For 'addpopupmenu' and 'add3rdmousepopupmenu' this specifies
          a menubar using a list which is in turn passed to 'gmenu'.

      ID: When a handler is assigned, an id is returned. This id can be
          used to remove a handler from an object.

     ...: 

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

     At first these handlers were all lowercase. These functions are
     still availabe, although the mixed case usage is encouraged

     In GTK, and other toolkits, an event causes a signal to be
     triggered and these handlers are called in response to that
     signal. 

     These signals have various names known to the GTK programmer. say.
     These functions attempt to shield the gWidgets user from needing
     to learn these signals. For gWidgetsRGtk, if these handlers prove
     insufficient then the non-exported 'addhandler' function has an
     additional 'signal' argument: '(obj,signal,handler, action,...)'
     for specifying a GTK signal. By avoiding this, we can make the
     gWidgets API non-toolkit specific.

     The signals are defined to match the event described by the method
     name, e.g., "doubleclick." 

     The handlers all have signature '(h,...)' where the first argument
     is a list with components 'obj' containing the widget the handler
     is added to and 'action' containing the values passed along to the
     'action' argument. This can be used to pass in other widget's
     names, when they can not be found from a function closure, say.

     The handlers do not have lazy evaluation. The value of 'action' is
     the one at the time of creation of the widget. (See the example).
     In GTK, a means to cheat this is to pass in a gWidget instance, as
     the underlying GTK objects are stored as pointers, not copies, so
     that when queried, their current state is used.

     \description{

'_a_d_d_h_a_n_d_l_e_r_c_h_a_n_g_e_d': This handler is called when a widget is "changed."
      This is interpreted differently by the various widgets. For
     'gedit' change refers to a changed value, not a keystroke change
     (when ENTER is pressed). For notebooks, this is called when a page
     is changed.


'_a_d_d_h_a_n_d_l_e_r_k_e_y_s_t_r_o_k_e': This handler is called when keys are pressed in
     the text widgets. 

'_a_d_d_h_a_n_d_l_e_r_c_l_i_c_k_e_d': This handler is called when a widget, such as a
     button or label, is clicked. 

'_a_d_d_h_a_n_d_l_e_r_d_o_u_b_l_e_c_l_i_c_k': This handler is called when a widget is
     doubleclicked, like in the tree widget. Not all widgets receive a
     double click signal. Only when a single mouse click is needed for
     selection is this implemented.

 '_a_d_d_h_a_n_d_l_e_r_e_x_p_o_s_e': handler is called when a widget is exposed. For
     instance when a page in a notebook is exposed.

 '_a_d_d_h_a_n_d_l_e_r_u_n_r_e_a_l_i_z_e': handler is called when a widget is being
     unrealized.

 '_a_d_d_h_a_n_d_l_e_r_d_e_s_t_r_o_y': handler is called when a widget is being
     destroyed. A slight difference between the previous. 

 '_a_d_d_h_a_n_d_l_e_r_i_d_l_e': handler is called every so often, and can be used to
     update a widget's content. This method has an extra argument 
     'interval' specifying the interval in milliseconds with a default
     of 1000 or 1 second.  }

     Although not handlers, the 'addpopupmenu' method adds a popup menu
     to a mouse click. The popup menu is specified using a list that is
     passed to 'gmenu'.

     A refinement of this is the 'add3rdmousepopupmenu' method which
     puts the popupmenu on the right mouse click.

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

     'gWidgets-methods'

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

     ## Not run: 
             ## a default handler, useful for when action is enough to
             ## specify desired results

             handler.default = function(h,...) do.call(h$action,list(svalue(h$obj)))
             group = ggroup(horizontal=FALSE, container=gwindow("Click
                     button"))
             button = gbutton("Click me", container=group)
             addhandlerclicked(button, handler=handler.default, action="print")

             ## use two widgets, one to update the other
             group = ggroup(horizontal=FALSE, container=gwindow("two widgets"))
             button = gbutton("click me", container=group)
             label = glabel("Button has not been clicked", container=group)
             addhandlerclicked(button, handler = function(h,...) {
             svalue(h$obj) <-"click me again"
             svalue(h$action) <- "Button has been clicked"
             }, action = label)

             ## lazy evaluation is not used here
             obj = 4
             gbutton("click",cont=TRUE, handler=function(h,...)
             print(h$action), action=obj)
             obj = 2
             ## now click button and value of 4 will be printed, not 2

             ## Whereas, if one uses a gWidget we get the same as lazy
            ## loading
            obj = gedit("4")          
             gbutton("click",cont=TRUE, handler=function(h,...)
                     print(svalue(h$action)), action=obj)
             svalue(obj) <- "2"
             ## Now click and "2" is printed.
     ## End(Not run)

