org.rosuda.JRI
Interface RMainLoopCallbacks

All Known Implementing Classes:

JGRConsole, JGRConsolePlaceholder, JRIEngine

public interface RMainLoopCallbacks

Interface which must be implmented by any class that wants to pose as the call-back handler for R event loop callbacks. It is legal to return immediately except when user interaction is required: rReadConsole(org.rosuda.JRI.Rengine, java.lang.String, int) and rChooseFile(org.rosuda.JRI.Rengine, int) are expected to block until the user performs the desired action.

Method Summary

void	rBusy(Rengine re, int which) called when R enters or exits a longer evaluation.
java.lang.String	rChooseFile(Rengine re, int newFile) called when R expects the user to choose a file
void	rFlushConsole(Rengine re) called when R requests the console to flush any buffered output
void	rLoadHistory(Rengine re, java.lang.String filename) called to load the contents of the history
java.lang.String	rReadConsole(Rengine re, java.lang.String prompt, int addToHistory) called when R waits for user input.
void	rSaveHistory(Rengine re, java.lang.String filename) called to save the contents of the history (the implementation is responsible of keeping track of the history)
void	rShowMessage(Rengine re, java.lang.String message) called when R want to show a warning/error message (not to be confused with messages displayed in the console output)
void	rWriteConsole(Rengine re, java.lang.String text, int oType) called when R prints output to the console

Method Detail

rWriteConsole

void rWriteConsole(Rengine re,
                   java.lang.String text,
                   int oType)

called when R prints output to the console

Parameters:

re - calling engine

text - text to display in the console

oType - output type (0=regular, 1=error/warning)

rBusy

void rBusy(Rengine re,
           int which)

called when R enters or exits a longer evaluation. It is usually a good idea to signal this state to the user, e.g. by changing the cursor to a "hourglass" and back.

Parameters:

re - calling engine

which - identifies whether R enters (1) or exits (0) the busy state

rReadConsole

java.lang.String rReadConsole(Rengine re,
                              java.lang.String prompt,
                              int addToHistory)

called when R waits for user input. During the duration of this callback it is safe to re-enter R, and very often it is also the only time. The implementation is free to block on this call until the user hits Enter, but in JRI it is a good idea to call Rengine.rniIdle() occasionally to allow other event handlers (e.g graphics device UIs) to run. Implementations should NEVER return immediately even if there is no input - such behavior will result in a fast cycling event loop which makes the use of R pretty much impossible.

Parameters:

re - calling engine

prompt - prompt to be displayed at the console prior to user's input

addToHistory - flag telling the handler whether the input should be considered for adding to history (!=0) or not (0)

Returns:

user's input to be passed to R for evaluation

rShowMessage

void rShowMessage(Rengine re,
                  java.lang.String message)

called when R want to show a warning/error message (not to be confused with messages displayed in the console output)

Parameters:

re - calling engine

message - message to display

rChooseFile

java.lang.String rChooseFile(Rengine re,
                             int newFile)

called when R expects the user to choose a file

Parameters:

re - calling engine

newFile - flag determining whether an existing or new file is to be selecteed

Returns:

path/name of the selected file

rFlushConsole

void rFlushConsole(Rengine re)

called when R requests the console to flush any buffered output

Parameters:

re - calling engine

rSaveHistory

void rSaveHistory(Rengine re,
                  java.lang.String filename)

called to save the contents of the history (the implementation is responsible of keeping track of the history)

Parameters:

re - calling engine

filename - name of the history file

rLoadHistory

void rLoadHistory(Rengine re,
                  java.lang.String filename)

called to load the contents of the history

Parameters:

re - calling engine

filename - name of the history file