Package 'Gwidgetswww'

Package ‘gWidgetsWWW’

July 2, 2014

Version 0.0-23

Title Toolkit implementation of the gWidgets API for use with web pages

Author John Verzani

Maintainer John Verzani

Depends R (>= 2.11.0), methods, proto, ﬁlehash, digest, rjson

Suggests

Extends canvas, RSVGTipsDevice, SVGAnnotation, webvis

Description Port of the gWidgets API to program dynamic websites. Can be used with R's dynamic help web server to serve local ﬁles. This provides a convenient means to make local GUIs for users without concern for external GUI toolkits. Also, in combination with RApache,http://biostat.mc.vanderbilt.edu/rapache/index.html, this framework can be used to make public websites powered by R. The Ext JavaScript libararies (www.extjs.com) are used to create and manipulate the widgets dynamically.

License GPL (>= 3)

URL http://gwidgets.r-forge.r-project.org/

LazyLoad FALSE

Repository CRAN

Date/Publication 2012-06-09 10:18:19

NeedsCompilation no

1 2 gWidgetsWWW-package

R topics documented:

gWidgetsWWW-package ...... 2 gcanvas ...... 11 ggooglemaps ...... 13 gprocessingjs ...... 15 gsvg...... 18 gwebvis ...... 20 gWidgetsWWW-helpers ...... 21 gWidgetsWWW-undocumented ...... 22 gw_browseEnv ...... 22 gw_package ...... 22 localServerStart ...... 23

Index 25

gWidgetsWWW-package Toolkit implementation of gWidgets for WWW

Description Port of gWidgets API to WWW using RApache and the ExtJS javascript libraries.

Details This package ports the gWidgets API to WWW, allowing the authoring of interactive webpages within R commands.

The webpages can be seen locally through a local server or viewed through the internet:The local version is installed with the package and uses R’s internal web server for serving help pages. The server version requires the RApache module for Apache to be installed and conﬁgured. (More later.)

The webpages themselves use the excellent Extjs toolkit (www.sencha.com) to render the widgets. This toolkit is installed with the package.

The gWidgets API is meant to be multi-toolkit. For its other implementations (gWidgetsRGtk2, gWidgetsQt, gWidgetstcltk) the main methods are deﬁned in the gWidgets package, with toolkit packages providing the link between the graphical widget library and R. The gWidgetsWWW is different, it is a more-or-less faithful implementation of the API, but this is not enforced by using the gWidgets pacakge. This was chosen, as there are some signiﬁcant differences between an interactive desktop GUI and a webpage.

As the differences are not great, this ﬁle documents differences from the API. We defer to the gWid- gets documentation for more detail. (However, this package is not compatible with the gWidgets package so reading that documentation is best done with a separate R process.) gWidgetsWWW-package 3

Overview:

The gWidgetsWWW package at one level maps R\/ commands to javascript commands. Basically it just pastes together a bunch of javascript commands to send to the browser. A more sophisticated treatment (like pyjamas for python) would compile the R code into javascript, but that does not happen here. This package is a simple mapping.

The communication between R\/ and the browser works as follows. Before a page is rendered, it can be constructed using the gWidget constructors and methods. When the top-level window is shown (via its print method), the javascript code to produce the page is created. This javascript code takes advantage of the freely available Ext libraries which greatly enhance the base javascript language. This code should be contained in or sourced into a web page so that it can be rendered in a browser. The gWidgetsWWW package provides several examples of how this works. The interactivity of a GUI is created through httpxmlrequests back to the RApache server. Each page load creates a unique session to store the state. This allows data to be passed from the web page back to an R process and back without needed to reload an entire page. In fact, reloading a page creates a new session. What is missing is a way to initiate a request from R\/ to the web page and then back to R. As such, the state of the web page is constantly passed back to the R\/ session. That is, when a control is updated, such as when a radio button is clicked, there is a call back into R\/ to set that value. This allows handlers in R to be aware of the state of the web page. On the downside, this may cause a lag in performance. Installation:

To run the local version of gWidgetsWWW no installation is necessary beyond installing the package. The command localServerStart can be used to load a script.

Installation for the server requires several steps: a) installing RApache, b) installing gWidgetsWWW c) conﬁguring RApache for gWidgetsWWW, and d) creating some webpages

Installing RApache is documented at the RApache website. Installing gWidgetsWWW is straightforward.

To configure RApache for gWidgetsWWW, a sample configuration is included in the templates directory. There are several variables to configure. The defaults work with a recent version of Ubuntu, so it can be as easy as simply copying the file into the appropriate place for the web server to read it.

The Ext libraries are included in the basehtml/ext directory. Ext has a dual-license model, of- fering an open source LGPL license along with a per-developer, royalty-free commercial license. The standard conﬁguration reads these ﬁles from where the R package is installed. (This may need adjustment), so no installation is necessary.

To complete the installation, the gWidgetsWWW package provides some stock icons in the basehtml/images directory.. As with the extjs libraries, these can be installed whereever, but the default conﬁguration ﬁnds them where R installs the package. The author would very much appreciate that a coherent set 4 gWidgetsWWW-package

of icons be contributed.

Web pages can be made in two ways. Once can use a brew template and call back into R to generate the page. However, it is much easier to write a standalone R script and call that.

For local installs, the function localServerOpen is used to open a file. For server installs, the script need only be put into the proper directory. (This is /var/www/gWidgetsWWW in the default configuration.) The script is loaded by calling the proper URL, which takes the form: servername/gWidgetsWWWrun/scriptname, where servername is the http:///www.yourhost.com bit, gWidgetsWWWrun is the default name for the invocation and scriptname the file in the directory (or directories) specified to search through.

The scripts themselves have a pretty standard structure: there must be a global gwindow instance (corresponding to the main web page, or which there can only be on), gWidgetsWWW commands for layout, and ﬁnally a call to the visible<- method of gwindow to print out the javascript commands generated by the package. The Examples directory has many examples. (Try localServerOpen("Examples/ex-index.R", pacakge="gWidgetsWWW") to see.) Sessions: gWidgetsWWW uses sessions to store data when a web page is loaded. Sessions are simply R environments. HTML itself is stateless, so some means is necessary to keep track of data between interactions. The use of AJAX allows pieces of a page to be updated without the entire page, making pages appear much more responsive. This involves callbacks into a R process that are executed within the environment stored for the session.

The environments do not remember which packages are loaded, so if your callback requires a package beyond the base and gWidgetsWWW you will need to include the appropriate require command in the callback.

Sometimes the database driver will complain. Likely this is due to the database not being locked while a transaction is being completed.

The sessions are stored by default in ﬁles under a directory using ﬁlehash. This has the advantage of being easy to remove using regular cron jobs, but may be slower than other forms of storage.

This is all a bit of a hack, so any report of bugs is appreciated.

Containers: We now describe implementation of the basic widgets in gWidgetsWWW beginning with the containers.

A primary difference in gWidgetsWWW over gWidgets for other toolkits is the restriction to only one top-level window, which maps to the webpage. Subwindows are possible though. These are constructed with the same constructor, but one passes in the top-level window to the parent argument. The window object is a bit different than other gWidgets implementations, as the object is not rendered until the web page is ready to display. This rendering is done through the visible<- gWidgetsWWW-package 5

method. (In particular, the constructor’s visible argument is ignored.) After rendering, new widgets can be added but it doesn’t happen by the same process and may not work as desired. To be on the safe side, you can add child widgets and make them not visible to begin. The default handler is assigned to the unload signal which is called when a page is left. One thing to remember, is that web pages in gWidgetsWWW will lose state when reloaded. For windows, only the svalue<- method, for adjusting the title, is deﬁned.

There are a few proto properties to adjust the page. The property doLoadingText can be set to FALSE to suppress the "loading" message whenever a handler is being called.

The default means of each window being a webpage can be overridden by specifying a value of ..renderTo, as in w = gwindow(); w$..renderTo = "someId" for some HTML object with appropriate id.

The ggroup container accepts the horizontal and spacing arguments, but does not use the use.scrollwindow argument (spacing can not be done after rendering with the svalue<- method though). When adding a child component (which is done when a ggroup instance is used as a parent container) the expand argument is not used, nor is the anchor argument of gWidgets. These are useful for alignment. Additionally, the addSpring and addSpace methods are not deﬁned.

Nested horizontal groups will expand to ﬁll all the space to the right. To stop this behaviour – which is desired as you can’t display other widgets – set the width of the container via the size<- method. The gframe container simply adds a title to a ggroup instance. This can be adjusted with the svalue<- method.

The gexpandgroup container extends the gframe container by making the title clickable. When clicked the container will toggle between a hidden and visible state. When hidden only the title is visible. This can be done programatically through the visible<- method.

The glayout container lays out its children in a grid. There is no ability to adjust how a child is layed out in the parent cell through the anchor arugment. When adding a child to this container one speciﬁes the location using the [ method and speciﬁes the container to the constructor as in this example: f <- glayout(cont = g); f[1,1] <- (b <- gbutton("hi", cont=f))

The gnotebook container does not implement all the features expected. The tab.pos argument only accepts values of 1 and 3 for top and bottom placement of tabs. The close.buttons argument is not yet implemented. Adding child components is done by specifying the notebook object to the constructor’s container argument. When done, the extra argument label is used to specify the tab label. The svalue<- method can be used to set the tab by index, the names and names<- method set the tab names. The dispose method deletes the current tab.

The gformlayout widget, used to layout widgets using glayout, is imlemented. Widgets: 6 gWidgetsWWW-package

The glabel widget has no handler, and is not editable. HTML markup is allowed, but may not work if not escaped. The font<- method can be used to adjust font properties. This method takes a vector of values with corresponding names being the CSS property. The gbutton widget: Can accept a gaction object to deﬁne the click handler. Pass in the action to the action component and NULL for the handler argument.

The ghtml widget shows urls in the window. The url should point to a basic web page or be HTML formatted text. Some browsers will process this text before it gets to R, so it may be best to source in the ﬁle that contains HTML formatted text.

The gcheckbox widget has no method to change the label ([<-, names<-)

The gcheckboxgroup widget has no [<- method.

The gradio widget has no [<- method.

The gslider widget has a tooltip that indicates the value of the widget. This tooltip can be cus- tomized. Pass a string, such as "{0} percent complete" to the constructor. (The 0 in braces is substituted into the HTML fragment.) The [<- method to set the values to choose from is not implemented.

The gspinbutton widget is implemented but the trigger icons may not appear. The widget is responsive to arrow keys to cycle through the speciﬁed values. The [<- method to set the values to choose from is not implemented.

The gedit widget: The transport occurs on the "blur" signal – when the focus leaves the widget basically. The gedit widget does not have the [<- method. However, if this is desired (for type ahead) the gcombobox widget can be used. By default, this widget has a "trigger" icon indicating to the user that it looks like a combobox, but this will not be drawn if the property ..hideTrigger is set to TRUE, as in obj = gcombobox(...); obj$..hideTrigger <- TRUE. In a similar way, one can specify "typeAhead" by setting obj$..typeAhead <- TRUE. The handler addHandlerKeystroke returns the numeric value of the key that is pressed in the key component of the ﬁrst argument, h. This is supposed to be a UNICODE value. If one adds the arguments "key=’e.ENTER’" (say ENTER could be BACKSPACE, ..) or "charCode=65", where 65 is "A" or "a" then a check is made at the browser level before calling back into R.

The gtext widget: The transport occurs on the "blur" signal – when the focus leaves the widget basically.

The gimage widget filename and dirname referring to url’s not to local ﬁles. There is no handler deﬁned for this widget.

The gcombobox widget has an items argument which can be a data vector, or a data frame with one, two, three, or perhaps more columns. This should have two or more values. If a data vector or one-column data frame, then it should be a vector of values. If a two or more column data frame, gWidgetsWWW-package 7

then the first column will be the value, the second column (if present) will be used to generate an image. If the values are identified as URL, or have that class the image will be downloaded, otherwise it will be assumed to be a character string identifying a stock icon. Finally, the third column (if present) will be used for a tooltip. For the real ambitious, the $tpl() method of the widget can be used to markup the combobox text and (perhaps) include other columns of the items argument. The template should use the names "value","text","iconurl" and "qtip" for the first four columns, where the "text" column is the "value" column repeated.

The gcalendar widget formatting may be unrealiable. The conversion from Ext to R format for dates may be locale dependent and this hasn’t been investigated.

The ggraphics widget is a link to the gWidgetsWWW gcanvas widget. This is used slightly differently than an interactive graphics device – how ggraphics is meant to be used, but is similar to how a non-interactive device is used. The canvas grahics device allows graphics to be written using JavaScript, so they render natively in a canvas widget in a browser. Not all browsers implement this relatively modern widget.

The gsvg widget creates a space in a page to use the RSVGTipsDevice package to display SVG graphics within a web page.

The gfilebrowse widget is written only for local installs. The handler does not work. The basic idea is that gfile is like an edit box with a button (like gfilebrowse in gWidgets) and a svalue method. However, the behaviour is limited. No path information is included. Even more, on Chrome that path has an extra windows-specific bit added called "fakepath". In short, this widget needs work.

The gtable widget: when using [<- to replace values, indices don’t work and when replacing data frame the replacement must have same number of columns, each with the same type; has no names<- method to set column names. Only addHandlerClicked and addHandlerDoubleclick are working. The filtering feature (specified through filter.FUN say) is not implemented. However, a proto method filter is available to filter by a column name and regular expression after the widget is shown. Call as in: tbl=gtable(mtcars, ...); tbl$filter("cyl","6"). The ex-gtable example has a sample usage. The icon.FUN should return either url’s or stock icon names.

For tables the size<- method can be, as usual, a vector of width and height values (in pixels). However, it ma also be a list with components width, height and columnWidths. The latter allows one to specify the widths of each column in pixels. Otherwise these are intuited from the maxmim number of characters in each column at time of construction. The formatting of the columns is controlled by a few javascript functions. For example the formatting of numeric variables by the javascript function gtableNumeric. This can be overridden. For example if tbl is a table widget, then before the GUI is drawn, deﬁng a new function in the ..scripts method can override the default. The gbigtable widget allows very large tables to be displayed, at it only shows part of the table at once. The number of lines displayed is speciﬁed by the pageSize argument, with default of 25. 8 gWidgetsWWW-package

The gdf widget is implemented but limited. The widget recognizes certain data types and provides different means to edit the values. However, there is no capacity to add rows or columns. (One could start with more rows and columns than needed and then trim.) As the column types come from the items argument, this must be provided. The widget does not gracefully handle NA values (items[complete.cases(items),] is used). This can be worked around, but isn’t automated. For numeric values NaN is recongized. For character, logical or factors vectors, one could use "NA" or "". The widget does not show the data frames row names. One could add these to items ﬁrst as a character vector to edit. and then take them off again.

The visible<- method is use to restrict the rows that are shown by a specification of a logical vector. In addition, a proto method filter is available to filter by a column name and regular expression after the widget is shown. The ex-gtable example has a sample usage. The visible<- method uses filter in an inefficient manner, so using filter is suggested for large data sets. (Al- though it is not portable across gWidgets toolkits).

The gtree widget works, but only for single columns. (No grid).

The gaction widget creates "actions" which can be used in menubars and attached to buttons. Un- like the gaction constructor of other gWidgets implementations, here one must include a parent argument. The methods svalue<- and enabled<- can be used to set the label and the en/dis able the items.

The gmenu widget has no methods to replace or access the elements of the menu. However, the leaves of the menu items should be gaction elements, rather than lists as with the other gwidgets implementations. This allows one to call enabled<- to disable, and svalue to change the text. The icons are not working.

At this time, support for popup menus via add3rdMousePopupMenu and addPopupMenu is not implemented.

The gtoolbar widget is subsumed in the gmenu widget. The gaction constructor can be used to create menubar elements.

The gstatusbar widget is slightly different from the gWidgets API, where there is a stack of sta- tus messages. The intial text stays until overridden via an svalue call. Subsequent svalue calls are transient, lasting for about 10 seconds.

The gseparator widget only works for horizontal lines, and simply uses the HR tag within the ghtml widget. The ggooglemaps widget allows one to integrate google maps into an application. It is not working. This constructor is gWidgetsWWW speciﬁc and is documented in its own help ﬁle. Dialogs:

The galert(title = "", message = "", delay=3, parent=NULL) dialog is speciﬁc to gWid- getsWWW. It creates a quick alert that pops down from the top of the web page. The parent gWidgetsWWW-package 9

should be the top-level window object. Otherwise, this constructor has a title and message argument for the message and delay in seconds to specify the time the dialog appears.

The other dialogs, as well, have a parent argument that must be speciﬁed. This allows handlers, etc. to be registered. Visually, the dialogs will appear to "pop-up" from the component speciﬁed.

The gmessage dialog produces a modal dialog similar to the javascript alert dialog.

The gconfirm widget works. The handler is called on the "ok" selection.

The ginput works. The handler is called on okay. The value of the input component contains the text typed into the box.

As an alternative to gconfirm and ginput a subwindow can be used. These are created by the gwindow constructor when the parent argument is speciﬁed. (The dialogs are modal, the subwindow is not, although it sits on top of the browser window.) icons:

The function getStockIcons returns a vector of these icons. The names of this vector may be used to deﬁne icons in some of the widgets. The return values are url’s of the stock icons. The function addStockIcons can be used to add to this list. These should be added before the GUI is rendered so that they will be available to the GUI’s components. Methods:

The svalue method should work as with gWidgets.

The svalue<- method should work as with gWidgets.

The add method for containers (implicitly called by constructors) is implemented (but may behave differently) for containers after they are rendered.

The enabled<- method is used to disable/enable a widget for user input.

The delete and dispose<- methods only hide the widget, rather than destroy the widget.

The focus<- method should work as expected to set the focus to the widget.

The visible<- method should unhide a child widget that was hidden via dispose<-. There is no visible=FALSE state for widgets when the GUI is initially drawn.

The [ method method for many constructors is not fully implemented. 10 gWidgetsWWW-package

The [<- method method likely won’t use the i,j indexing arguments

The names<- method method is only partially implemented.

The size<- method can be called with either c(width) or c(width, height). The default sizing for many widgets is "auto", which will ﬁll the width of the page. This will make horizontal=TRUE not behave as expected.

The print method for windows (gwindow) will print out the javascript to produce the page. This is how a page gets rendered to the web browser, but can also help in debugging (somewhat).

The tooltip<- method will set a tooltip for the widget. The value may be a string; a character vector; a URL which returns a string (URLs are identiﬁed by the function isURL); or a list with components title and message, where the title component is a string and the message component a character vector.

Handlers:

The interactivity between the web browser GUI and R is provided by handlers which respond to GUI signals sent when an event occurs. For instance, when the mouse clicks on a button, a mousedown signal is sent. The gWidgetsWWW code allows R\/ functions to be used as handlers. These functions create JavaScript code to update the the web browser. The gWidgetsWWW package takes the methods of gWidgetsWWW and produces the JavaScript code, so the R\/ programmer need only know how to program in R. Handlers in gWidgetsWWW are slightly different than in other implementations of gWidgets. As with others, the first argument to the handler, traditionally h, is a list with components obj, referring to the widget; action, referring to the value passed into the action argument; and occasionally others. Handlers are added to the widget through the handler argument of the constructor, or using one of the addHandlerXXX methods. The constructor assigns a default signal (or more) to bind the handler to. More control is given by the addHandlerXXX methods. If you want to bind to a different signal (after having read the Ext documentation say) the method addHandler allows the specification of a signal. Handlers may not evaluate within the scope of the function, as one would expect. This should be addressed. If not fixed, then one can use global variables within the handler. Drag and Drop:

The Ext library has some built in drag and drop support. Otherwise, drag and drop is not currently supported. Compound widgets:

The gcommandline widget is implemented to run locally only. It provides a simple notebook like interface. The implementation does not follow the API of gWidgets, the only arguments are the container, a width and a graphic_size (to specify the size for a gsvg widget). gcanvas 11

At this time the constructors of the compound widgets gdfnotebook, gvarbrowser, ggraphicsnotebook, ggenericwidget are not implemented. proto:

The proto package is used as the backend for this package, rather than the gWidgets package. This was done as much for variety than any other reason. The user of gWidgetsWWW need not be aware of this, but it does allow some undocumented access to the underlying widgets. A few examples. First, many of the widgets have properties that are set during the construction of the widget, but are not speciﬁed by the arugments to the constructor. This is due to the EXT libraries having more options, than are given by gWidgets. For instance, in the gcombobox function the properties ..hideTrigger and ..emptyText can be set. The ..hideTrigger values is a logical value, and it TRUE will render the widget without an arrow indicating to the user this is a combobox. This can be useful for setting values that will appear as the user types. In the API for gWidgets the [<- method for gedit should cause something similar to happen, but it doesn’t. The ..emptyText argument is there to set the initial text of the box in gray to suggest to the user what to do. The double dots are reserved for properties of methods of the widget that are instance speciﬁc, hence the funny names. Another way to modify a widget is to set the method ..ExtCfgOptions. This should be a function which returns a list. The named components of the list map to the properties of the EXT constructor. (See that API for things you may want). These values will override any others set by gWidgetsWWW. The conversion will quote values of type character. If this is undesired, use the class String returned by the String function. The above two examples set properties of the object. These only effect the rendering if set prior to rendering. To affect the widget after rendering, one can create JavaScript to be sent back to the browser. This can only occur during a handler. Most of the gWidgetsWWW methods eventually call a function ending in JS. For instance, svalue<- calls the proto method setValue which in turn calls setValueJS. The latter can be overridden, or can be added to by setting a method for ..setValueJS. If you do this, and think your code should be integrated into the main code, please share it.

Author(s) John Verzani

See Also gWidgets

gcanvas Interface to canvas device

Description This function allows the canvas package to create a javascript device. Although this isn’t working with all browsers, it does work quite well with ﬁrefox. 12 gcanvas

Usage

gcanvas(f, width=480, height=400, container = NULL, ...)

Arguments

f optional ﬁlename storing canvas output width width of canvas in pixels height height of canvas in pixels container parent container for processing object ... not used

Details

Jeffrey Horner’s canvas package provides a javascript implementation of an R device. The use if very similar to a regular, non-interactive R device, such as png. The gcanvas widget provides the screen space to display the graphic.

The svalue<- method is used to update the graphic. By default the background color for a canvas device is transparent, so graphs will layer on top of each other. To avoid this, specify a background color using hex notation, e.g., bg="#ffffff" for white.

Only one gcanvas widget can be used in a GUI, as underlying the canvas javascript is a ﬁxed variable name. This includes subwindows of a GUI, so this is a poor choice for using in a window that can be dismissed and re-opened.

Both the gcanvas constructor and the canvas device have width and height arguments. These should be the same, but it is up to the user to ensure this.

This replaces the gprocessingjs widget that isn’t working as of version 0.8.0

Value

Returns a proto object with class gCanvas.

Author(s)

John Verzani

References

The canvas device package ggooglemaps 13

Examples ## Not run: require(canvas, quietly=TRUE, warn=FALSE) ## require quietly

## Make a simple graph f <- tempfile() ## A file to store the javascript code canvas(file=f, width=480, height=400) hist(rnorm(100)) dev.off() ## write javascript code to f

w <- gwindow("Canvas test") g <- ggroup(cont = w, horiz=F) cv <- gcanvas(f,cont = g) ## when f is given, graph an initial graph ## is drawn ## How to update the graphic using the svalue method b <- gbutton("click me", cont = g, handler = function(h,...) { canvas(file=f, width=480, height=400, bg="#ffffff") ## specify a ## background color hist(rexp(100)) dev.off() svalue(cv) <- f })

## End(Not run)

ggooglemaps Contructor for Google maps widget

Description This creates a widget to show a map provided by Google. One can specify the center of the map, markers on the map and add line semgemnts and polygons. This extension to gWidgets is gWid- getsWWW speciﬁc.

Usage ggooglemaps(x, title = "", type = c("map", "panorama"), key = "ABQIAAAAYpRTbDoR3NFWvhN4JrY1ahS5eHnalTx_x--TpGz1e2ncErJceBS7FrNBqzV5DPxkpbheIzZ9nTJPsQ", container, ...)

Arguments x Location of center of map. Given as a string containing an address, or as a vector of latitude and longitude values. title The center is marked. This sets the text for the tooltip. type Determines type of map. One of "map" or "panorama". 14 ggooglemaps

key A google API key. The default is for localhost 127.0.0.1:8079, which hopefully just works. container A gWidgetsWWW container object ... ignored

Details This widget was created using the code posted to the ExtJS blog by Shea Frederick http://extjs. com/blog/2008/07/01/integrating-google-maps-api-with-extjs/ . This widget requires the HTML page that will render it have the DOCTYPE of the page set accord- ing to these instructions: http://code.google.com/apis/maps/documentation/index.html# XHTML_and_VML Next, the website the page will be listed on must register to have an API key: http://code. google.com/apis/maps/signup.html. NOT WORKING:This key is specifies through the key argument. The default will work for the domain 127.0.0.1:8079. The key can be specified in the header of the html page that will render the gWidgets code. The following will work for the domain 127.0.0.1:8079: This widget is experimental. Its API is still not settled. As of now, the method svalue<- is used to set the center of the map. After rendering this is done using a data vector of longitude and latitude. Prior to rendering an address can be used. The [ method will return the markers locations, but does not reflect their position after if they are moved with the mouse. The [$<$- method can be used to set markers. The value can These are specified in a 2 or 3 column data frame with columns of latitude, longitude and the optional title. After the widget has rendered, the proto method widget$addMarker is more efficient. The handlers addHandlerClicked and addHandlerDoubleclick should work. The first argument of the handler, h, is, as usual, a list. The component latlng contains a vector with the latitude and longitude of the location the mouse click occurred at. More of the Google maps API is availble through some proto methods. These methods are called using the dollar sign notation, as in widget$methodname(methodargs). The available proto methods and their signatures are:

widget\$getBounds() Returns a list with the lower and upper coordinates of the current map. widget\$panTo(latlng) Sets map center to new coordinates specified using a numeric vector of latitude and longitude. widget\$setZoom Sets new zoom value. Default is 14 widget\$openInfoWindow(latlng, myHTML) Pops up message at point specified by latlng widget\$addMarker(latlng, title, draggable=FALSE) Add a new marker at the specified point with tooltip. These markers may be draggable. A popup shows the new coordinates after dragging. However, the values returned by [ are not aware of the new coordinates. gprocessingjs 15

widget\$addPolyline(latlng, color = "\#ff0000", pixel.width = 5, opacity = 1 Like the lines graphic function, this method adds line segments to the map. The points are speciﬁed in latlng, which is a matrix or data frame with columns of latitude and longitude values. If this is missing, the values set via [$<$- and addMarker are used. The color is set using hexadecimal RGB notation, eg. "\#ff0000". Opacity levels less than 1 allow the map to bleed through. When the line is clicked, its length in meters is given. widget\$addPolygon(latlng,border.color="\#ff0000", border.pixel.width = 5,border.opacity = 1,region.color = "\#000000",region.opacity = .1) Like the polygon graphics function, this method draws a polygon, rendering it on the map. The points are speciﬁed by a matrix (or data.frame) to latlng. If missing, the values set via [$<$- or addMarker are used.. When the polygon is clicked its area in square meters is presented.

Adding additional methods from the Google API is certainly possible.

Value

Returns a gWidgetsWWW object.

Author(s)

John Verzani

References

http://extjs.com/blog/2008/07/01/integrating-google-maps-api-with-extjs/, http:// code.google.com/apis/maps/

gprocessingjs Interface to Processing.js code to create graphics with javascript

Description

This function provides the ability to write to canvas on the browser using somewhat familar graphics commands in R. The processing.js (http://ejohn.org/blog/processingjs) javascript library is used to provide an interface to the canvas web object.

The package also provides gcanvas, for the canvas device, which uses the same technology to display graphics, but using R’s plotting commands.

Usage

gprocessingjs(width=400, height=400, pointsize= 12, container = NULL, ...) 16 gprocessingjs

Arguments width width of canvas in pixels height height of canvas in pixels pointsize size of font in pixels container parent container for processing object ... not used

Details This package is an interface to the processing.js javascript libraries http://ejohn.org/apps/ processing.js/processing.js and http://ejohn.org/apps/processing.js/examples/init. js. These provide the processing API for javascript. (Processing is an API for JAVA-basedgraphics. The gcanvas widget is more straightforward to use, but this widget is still included, as it can be used to create relatively interactive graphics with the local server version of gWidgetsWWW. For this use, no installation is required. This does not work like a typical R device. The constructor returns a proto object, for which several methods are deﬁned, including many familiar graphics primitives. Methods for proto objects are called through the object-oriented notation obj$methodname(arguments). The proto object has properties ..margin and ..background that may be changed directly to adjust the defaults. The main methods have only an abbreviated subset of the graphical parameters available. The following familiar methods are implemented:

p\$plot.new() Simply sets the background color to the value in the ..background property p\$plot.window(xlim, ylim, ...) Set the user limits for the graphic. The underlying canvas values are in pixels, this allows conversion into x-y coordinates. p\$title(main=NULL, sub=NULL, xlab=NULL, ylab=NULL, cex=1 Set the titles etc. for the graphic. The ylabel is not rotated. p\$axis(side) Draw axis on side given by side. Uses pretty to label axis. p\$box() Draw a box around graphic area p\$lines(x, y=NULL, col=NA, lwd=1, ... Draw lines between values in x and values in y p\$points(x,y=NULL, cex=1, col=NA, ... Draw points centered at x,y. The interior color is adjusted by col p\$polygon(x, y=NULL, col=NA Draw polygon using opints in x and y. The col sets the interior ﬁll. p\$rect(xleft, ybottom, xright, ytop, col=NA, ...) Draw rectangle(s) ﬁlling with the color if given. p\$abline(a=NULL, b=NULL, v=NULL, h=NULL, coef=NULL, ...) draws line over the canvas p\$text(x, y = NULL, labels = seq\_along(x),cex = 1, col = NULL, pos = NULL, ...) Places text label at x,y position. The value of pos adjusts the text: 1 for below, 2 to left, 3 above, 4 to right, 0 center. gprocessingjs 17

There are also several methods from the processing API that are implemented. The processing API allows for interactive graphics. The example shows how one can use a slider to adjust a histogram. This can be kind of slow, as the lag between the browser and R can make the interface non- responsive. This isn’t so bad with the local version. If one wishes to write some javascript code, the methods "mouseDragged","mouseMoved", "mousePressed", "mouseReleased", "keyPressed","keyReleased","draw","setup" can be set to functions that produce javascript handlers. This way there is not a lag between the browser and the R process.

Value Returns a proto object with class gProcessing.

Author(s) John Verzani

References http://ejohn.org/blog/processingjs

Examples ## Not run: ## make a histogram with breaks controlled by a slider w <- gwindow("processing example") g <- ggroup(horizontal=FALSE, cont=w) x <- faithful$eruptions p <- gprocessingjs(width=500, height = 400, container = g) p$textFont("arial",14) p$Hist <- function(.,x, breaks = "Sturges", col = "goldenrod") { out <- hist(x, breaks = breaks, plot=FALSE) p$plot.new() p$plot.window(xlim = range(out$breaks), ylim = c(0, max(out$counts))) p$axis(1) p$title(main = deparse(substitute(x))) nb <- length(out$breaks) p$rect(out$breaks[1:(nb-1)], rep(0, length=nb-1), out$breaks[2:nb], out$counts, col) } p$Hist(faithful$eruptions) gslider(from = 1, to = length(x), by = 1, cont = g, handler = function(h,...) { p$Hist(faithful$eruptions, breaks =as.numeric(svalue(h$obj))) })

## Make regression line that follows mouse clicks x <- c(); y <- c() glabel("Click in graph to set points", container=g) p1 <- gprocessingjs(width=500, height = 400, container = g) p1$..background <- 200 p1$plot.new() 18 gsvg

p1$plot.window(xlim=c(0,10), ylim=c(0,10)) addHandlerMouseclick(p1, handler = function(h,...) { xy <- p1$pixelsToXY(h$xy) assign("x",c(x, xy[1]), envir=.GlobalEnv) assign("y",c(y, xy[2]), envir=.GlobalEnv) p1$plot.new() # paints background p1$points(x, y, cex=2, col="red") if(length(x) != 1) { res <- lm(y ~ x) p$abline(res,col="blue") } })

visible(w) <- TRUE

## This is really slow! w <- gwindow("Follow the cursor", cont=g) w$doLoadingText <- FALSE

f <- gframe("Regression example", horiz=FALSE, cont = w) glabel("Move mouse through canvas and red ball will follow along", container=f) p1 = gprocessingjs(width=500, height = 400, container = f) p1$..background = 200 p1$plot.new() p1$plot.window(xlim=c(0,10), ylim=c(0,10))

theta <- seq(0, 2*pi, length=100) inds <- 2*(0:4) + 1.5 p1$addHandlerMousemove(handler = function(h,...) { xy = p1$pixelsToXY(h$xy) ## need to convert to user coordinates p1$plot.new() for(i in inds) { for(j in inds) { r <- min(0.5, sqrt((i-xy[1])^2 + (j-xy[2])^2)/5) p1$points(i, j, cex=r*10, col="red") } } })

gstatusbar("Powered by gWidgetsWWW", cont=w) visible(w) <- TRUE

## End(Not run)

gsvg Interface to RSVGTipsDevice device gsvg 19

Description This package allows one to show ﬁles in a web page produced by the SVG deices in RSVGTips- Device or SVGAnnotation. The former allows one to easily place tooltips and links to URLs, the latter allows for some very fancy javascripting to make dynamic graphics.

Usage gsvg(f, width=480, height=400, container = NULL, ...)

Arguments f optional ﬁlename storing ﬁle with output width width of canvas in pixels height height of canvas in pixels container parent container for processing object ... not used

Details The SVG devices are non-interactive device and requires a file to be written to the file system. These files should have a .svg extension as they are severd from a web page. As such, there are facilities to create a temporary file in a public webspace getStaticTempFile. This function uses the variable gWidgetsWWWStaticDir which must be configured for RApache. The function convertStaticFileToUrl gives the URL for the file on the file system. The svalue<- method is used to update the graphic.

Unlike the gcanvas widget, only the constructor needs the width and height speciﬁed. The SVG graphics "S"cale to ﬁll the allotted space.

Adding a handler to this device is not yet supported. However, the SVGAnnotation package allows one to do very interesting things with svg graphic ﬁles.

The gcanvas widget is a similar function for providing graphical output within a browser.

Value Returns a proto object with class gSvg.

Author(s) John Verzani

References The RSVGTipsDevice 20 gwebvis