\HeaderA{addCBFunction}{Add a potential callback function for an event}{addCBFunction}
\keyword{data}{addCBFunction}
\begin{Description}\relax
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.
\end{Description}
\begin{Usage}
\begin{verbatim}
addCBFunction(callFunction, shortName, preprocessingFun, eventLists)
\end{verbatim}
\end{Usage}
\begin{Arguments}
\begin{ldescription}
\item[\code{callFunction}] the callback function 
\item[\code{shortName}] a short character description of what the callback
function does 
\item[\code{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 
\item[\code{eventLists}] a vector of event names that this callback function can
be linked to 
\end{ldescription}
\end{Arguments}
\begin{Details}\relax
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".
\end{Details}
\begin{Author}\relax
Elizabeth Whalen
\end{Author}
\begin{SeeAlso}\relax
\code{\LinkA{getEvents}{getEvents}},
\code{\LinkA{getDescForEvent}{getDescForEvent}},
\code{\LinkA{setCallFunc}{setCallFunc}}
\end{SeeAlso}
\begin{Examples}
\begin{ExampleCode}
  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")
  }
\end{ExampleCode}
\end{Examples}

