addCBFunction             package:iSPlot             R Documentation

_A_d_d _a _p_o_t_e_n_t_i_a_l _c_a_l_l_b_a_c_k _f_u_n_c_t_i_o_n _f_o_r _a_n _e_v_e_n_t

_D_e_s_c_r_i_p_t_i_o_n:

     addCBFunction adds a potential callback function for an event. 
     This callback function will then be available to link to an event
     through the Event menu on the GUI and through the command line
     function, setCallFunc.

_U_s_a_g_e:

     addCBFunction(callFunction, shortName, preprocessingFun, eventLists)

_A_r_g_u_m_e_n_t_s:

callFunction: the callback function 

shortName: a short character description of what the callback function
          does 

preprocessingFun: a list of functions that must be called before the
          callback function; these preprocessing functions set values
          that the callback function will need; if there are no
          preprocessing functions, then this parameter is set to NULL 

eventLists: a vector of event names that this callback function can be
          linked to 

_D_e_t_a_i_l_s:

     The callback function that is given in the callFunction parameter
     must take only one argument and that argument must of be of type
     character to represent a row name from the data frame.  This
     function must create and handle a gUpdateDataMessage so that the
     data is updated.

     Not all callback functions will need preprocessing functions so
     this parameter can be set to NULL.  If the callback function needs
     some information besides the row name (which is the only parameter
     a callback function has), then the callback function must have one
     or more preprocessing functions.  For example, when the callback
     function is to color a point, there must be a preprocessing
     function that has the user set the color they want to use.

     Currently, the eventLists parameter can be a vector containing one
     or more of the following events: "mouseOver", "leftButtonClick",
     "middleButtonClick", "rightButtonClick".

_A_u_t_h_o_r(_s):

     Elizabeth Whalen

_S_e_e _A_l_s_o:

     'getEvents', 'getDescForEvent', 'setCallFunc'

_E_x_a_m_p_l_e_s:

       if (interactive())
       {
         loadData("USArrests")
         setActiveMVC("USArrests")
         getDescForEvent("leftButtonClick")

         changePch<-function(rowName)
         {
           curMVC<-getMVCFromWinNum()
           virtualData<-virtualData(model(curMVC))

           # column name
           colName<-"pch"

           # need to change the virtualData slot in model object 
           # using messages
           # for this example, just set the pch value to 2
           colIndex<-match(colName, colnames(virtualData))
           rowIndex<-match(rowName, rownames(virtualData))
           # determining the pch value should be set in a preprocessing function
           newPchValue<-2

           mData<-as.list(newPchValue)
           names(mData)<-rowName

           # if a point was clicked, then we want to create a 
           # gUpdateDataMessage
           dfMessage<-new("gUpdateDataMessage", type=colName, mData=mData,
                      dataName=modelName(model(curMVC)), from="")
           handleMessage(dfMessage)
         }

         addCBFunction(changePch, "change the plotting character", NULL,
         c("leftButtonClick", "middleButtonClick", "rightButtonClick"))

         getDescForEvent("leftButtonClick")
       }

