BrowserVizClass {BrowserViz} | R Documentation |
A concrete base class for interactive R/javascript visualization tools. Derived classes obtain socket setup, status and retrieval methods for free, obscuring many complicated details.
BrowserViz(portRange=10000:10100, title="BrowserViz", browserFile, quiet=TRUE, httpQueryProcessingFunction=NULL) toJSON(..., auto_unbox=TRUE) addRMessageHandler(key, functionName) ## S4 method for signature 'BrowserVizClass' ready(obj) ## S4 method for signature 'BrowserVizClass' send(obj, msg) ## S4 method for signature 'BrowserVizClass' browserResponseReady(obj) ## S4 method for signature 'BrowserVizClass' getBrowserResponse(obj) ## S4 method for signature 'BrowserVizClass' getBrowserInfo(obj) ## S4 method for signature 'BrowserVizClass' closeWebSocket(obj) ## S4 method for signature 'BrowserVizClass' port(obj) ## S4 method for signature 'BrowserVizClass' wait(obj, msecs) ## S4 method for signature 'BrowserVizClass' getBrowserWindowTitle(obj) ## S4 method for signature 'BrowserVizClass' setBrowserWindowTitle(obj, newTitle) ## S4 method for signature 'BrowserVizClass' getBrowserWindowSize(obj) ## S4 method for signature 'BrowserVizClass' roundTripTest(obj, ...) ## S4 method for signature 'BrowserVizClass' displayHTMLInDiv(obj, htmlText, div.id)
obj |
The |
portRange |
One or more consecutive integers in the range
1025-65535. A typical choice is |
title |
The constructor creates a new window (or a new tab, depending on how you web browser is configured). This title is displayed at the top of the window or tab. |
quiet |
Trace and tracking messages are written to the R console if this variable is set to FALSE. |
browserFile |
defaults to |
httpQueryProcessingFunction |
defaults to |
msg |
A name list, with four required slots: "cmd", "status", "callback", "payload". See below. |
msecs |
Numeric, number of milliseconds. |
newTitle |
A character string. |
htmlText |
A character string, i.e., "<h3>successful round trip of json-encoded data, length 48915.</h3>" |
div.id |
A character string, i.e., "bvDemoDiv" |
key |
A character string, the "cmd" field of the incoming four-field JSON command, used to dispatch on, so that the proper function is called. |
functionName |
A character string: the name of a function to which incoming web socket json commands can be dispatched. |
auto_unbox |
Logical, default TRUE; unboxing: do not coerce a scalar into a 1-element list, as the new (2015) jsonlite package prefers to do. |
... |
Arguments for our local, very slightly reddfined version of toJSON. |
In the code snippets below, obj
is an instance of the BrowserVizClass.
BrowserViz(portRange=10000:10100, title="BrowserViz",
browserFile, quiet=TRUE, httpQueryProcessingFunction=NULL)
:
Constructs a BrowserViz object. Among the several actions
included are: your default webrowser browses to the uri of a minimal
http server embedded in BrowserViz; the browserFile
is returned
to the browser; the websocket connection is initialized on both ends,
and the lowest numbered port in portRange
.
ready(obj)
:
returns TRUE when the R/browser websocket connection is ready for use.
port(obj)
: returns the actual port being used.
getBrowserInfo(obj)
: returns a character string describing
the browser to which we are connected, using the standard W3C DOM navigator.userAgent.
send(obj, msg)
: sends a properly structured (having four fields: cmd,
callback, status, payload) JSON message to the browser.
browserResponseReady(obj)
: returns TRUE when the
asynchronous response to the last message has been received from
the browser.
getBrowserResponse(obj)
: returns the just-received
JSON-encoded, four-field response to the latest message sent to
the brower.
closeWebSocket(obj)
: Close the websocket port now in use, making it
available for reuse.
getBrowserWindowTitle(obj)
: Returns the title of the web page (or
tab).
setBrowserWindowTitle(obj, newTitle)
: Sets the
title of the web page or tab to which we are currently connected.
getBrowserWindowSize(object)
: in pixels.
roundTripTest(object, ...)
: Sends json-enoded data to the
browser, decodes the return, which should be identical to the original.
displayHTMLInDiv(object, htmlText, div.id)
: intended
primarily for debugging, used currently with roundTripTest to
display json/character count of the data sent and returned.
Further arguments for toJSON
, typically just the
variable to be encoded.
Paul Shannon
if(interactive()){ library(BrowserViz) browserVizBrowserFile <- system.file(package="BrowserViz", "browserCode", "dist", "bvdemo.html") bv <- BrowserViz(browserFile=browserVizBrowserFile, quiet=TRUE) ## make sure everything is ready to use while(!ready(bv)) Sys.sleep(0.1) port(bv) ## illustrate a "low level" call. This detail is usually hidden from ## the user, implemented and contained (in the case of this example) ## in a getBrowserWindowTitle(bv) method call. This level of detail ## reveals what goes on behind the scenes. msg <- list(cmd="getWindowTitle", status="request", callback="handleResponse", payload="") send(bv, msg) while(!browserResponseReady(bv)) Sys.sleep(0.1) getBrowserResponse(bv) ## a simpler user-level approach: getBrowserWindowTitle(bv) ## set and get the windowTitle setBrowserWindowTitle(bv, "new title") getBrowserWindowTitle(bv) ## BrowserViz provides another information method which, like the others, will apply ## and maybe be of some use to derived classes getBrowserWindowSize(bv) ## finally, you should close BrowserViz when you are done, returning ## the port for use by other applications. closeWebSocket(bv) } # if interactive