Package ‘gWidgetsWWW’February 15, 2013

Version 0.0-23

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

Author John Verzani

Maintainer John Verzani <jverzani@gmail.com>

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

Suggests

Extends canvas, RSVGTipsDevice, SVGAnnotation, webvis

Description Port of the gWidgets API to program dynamic websites. Canbe used with R’s dynamic help web server to serve local files.This provides a convenient means to make local GUIs for userswithout concern for external GUI toolkits. Also, incombination with RApache,http://biostat.mc.vanderbilt.edu/rapache/index.html, thisframework can be used to make public websites powered by R.The Ext JavaScript libararies (www.extjs.com) are used tocreate 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 . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 2gcanvas . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 11ggooglemaps . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 13gprocessingjs . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 15gsvg . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 18gwebvis . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 20gWidgetsWWW-helpers . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 21gWidgetsWWW-undocumented . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22gw_browseEnv . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22gw_package . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 22localServerStart . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . . 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 webpageswithin R commands.

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

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 defined in the gWidgets package, with toolkitpackages providing the link between the graphical widget library and R. The gWidgetsWWW isdifferent, it is a more-or-less faithful implementation of the API, but this is not enforced by usingthe gWidgets pacakge. This was chosen, as there are some significant differences between an in-teractive desktop GUI and a webpage.

As the differences are not great, this file documents differences from the API. We defer to the gWid-gets documentation for more detail. (However, this package is not compatible with the gWidgetspackage 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. Basicallyit just pastes together a bunch of javascript commands to send to the browser. A more sophisticatedtreatment (like pyjamas for python) would compile the R code into javascript, but that does nothappen here. This package is a simple mapping.

The communication between R\/ and the browser works as follows. Before a page is rendered, itcan be constructed using the gWidget constructors and methods. When the top-level window isshown (via its print method), the javascript code to produce the page is created. This javascriptcode takes advantage of the freely available Ext libraries which greatly enhance the base javascriptlanguage. This code should be contained in or sourced into a web page so that it can be rendered ina 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. Eachpage load creates a unique session to store the state. This allows data to be passed from the webpage back to an R process and back without needed to reload an entire page. In fact, reloading apage creates a new session. What is missing is a way to initiate a request from R\/ to the web pageand 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 intoR\/ to set that value. This allows handlers in R to be aware of the state of the web page. On thedownside, this may cause a lag in performance.

Installation:

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

Installation for the server requires several steps: a) installing RApache, b) installing gWidgetsWWWc) configuring RApache for gWidgetsWWW, and d) creating some webpages

Installing RApache is documented at the RApache website. Installing gWidgetsWWW is straight-forward.

To configure RApache for gWidgetsWWW, a sample configuration is included in the templates di-rectory. 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 readit.

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 configuration reads these files from where the R package is installed. (This may needadjustment), so no installation is necessary.

To complete the installation, the gWidgetsWWW package provides some stock icons in the basehtml/imagesdirectory.. As with the extjs libraries, these can be installed whereever, but the default configurationfinds 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 generatethe 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 scriptneed only be put into the proper directory. (This is /var/www/gWidgetsWWW in the default configura-tion.) 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 namefor the invocation and scriptname the file in the directory (or directories) specified to searchthrough.

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 commandsfor layout, and finally a call to the visible<- method of gwindow to print out the javascript com-mands 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 Renvironments. HTML itself is stateless, so some means is necessary to keep track of data betweeninteractions. The use of AJAX allows pieces of a page to be updated without the entire page, mak-ing pages appear much more responsive. This involves callbacks into a R process that are executedwithin the environment stored for the session.

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

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

The sessions are stored by default in files under a directory using filehash. This has the advantageof 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 con-tainers.

A primary difference in gWidgetsWWW over gWidgets for other toolkits is the restriction to onlyone top-level window, which maps to the webpage. Subwindows are possible though. These areconstructed with the same constructor, but one passes in the top-level window to the parent argu-ment. The window object is a bit different than other gWidgets implementations, as the object isnot 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 wid-gets can be added but it doesn’t happen by the same process and may not work as desired. To be onthe safe side, you can add child widgets and make them not visible to begin. The default handleris assigned to the unload signal which is called when a page is left. One thing to remember, isthat web pages in gWidgetsWWW will lose state when reloaded. For windows, only the svalue<-method, for adjusting the title, is defined.

There are a few proto properties to adjust the page. The property doLoadingText can be set toFALSE 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 withappropriate id.

The ggroup container accepts the horizontal and spacing arguments, but does not use the use.scrollwindowargument (spacing can not be done after rendering with the svalue<- method though). Whenadding 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 foralignment. Additionally, the addSpring and addSpace methods are not defined.

Nested horizontal groups will expand to fill all the space to the right. To stop this behaviour – whichis 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 thesvalue<- method.

The gexpandgroup container extends the gframe container by making the title clickable. Whenclicked the container will toggle between a hidden and visible state. When hidden only the title isvisible. 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 islayed out in the parent cell through the anchor arugment. When adding a child to this containerone specifies the location using the [ method and specifies the container to the constructor as in thisexample: 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 argumentonly accepts values of 1 and 3 for top and bottom placement of tabs. The close.buttons argumentis not yet implemented. Adding child components is done by specifying the notebook object to theconstructor’s container argument. When done, the extra argument label is used to specify the tablabel. The svalue<- method can be used to set the tab by index, the names and names<- methodset 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 notwork if not escaped. The font<- method can be used to adjust font properties. This method takesa vector of values with corresponding names being the CSS property.

The gbutton widget: Can accept a gaction object to define the click handler. Pass in the action tothe 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 HTMLformatted text. Some browsers will process this text before it gets to R, so it may be best to sourcein the file 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 "<b>{0} percent complete</b>" to the constructor. (The 0 inbraces is substituted into the HTML fragment.) The [<- method to set the values to choose from isnot implemented.

The gspinbutton widget is implemented but the trigger icons may not appear. The widget is re-sponsive to arrow keys to cycle through the specified values. The [<- method to set the values tochoose from is not implemented.

The gedit widget: The transport occurs on the "blur" signal – when the focus leaves the widget ba-sically. 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 userthat it looks like a combobox, but this will not be drawn if the property ..hideTrigger is set toTRUE, as in obj = gcombobox(...); obj$..hideTrigger <- TRUE. In a similar way, one canspecify "typeAhead" by setting obj$..typeAhead <- TRUE. The handler addHandlerKeystrokereturns the numeric value of the key that is pressed in the key component of the first argument, h.This is supposed to be a UNICODE value. If one adds the arguments "key=’e.ENTER’" (say EN-TER could be BACKSPACE, ..) or "charCode=65", where 65 is "A" or "a" then a check is made atthe browser level before calling back into R.

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

The gimage widget filename and dirname referring to url’s not to local files. There is no handlerdefined for this widget.

The gcombobox widget has an items argument which can be a data vector, or a data frame withone, two, three, or perhaps more columns. This should have two or more values. If a data vector orone-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 animage. If the values are identified as URL, or have that class the image will be downloaded, other-wise 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 canbe 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 fordates 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 dif-ferently than an interactive graphics device – how ggraphics is meant to be used, but is similar tohow a non-interactive device is used. The canvas grahics device allows graphics to be written usingJavaScript, so they render natively in a canvas widget in a browser. Not all browsers implement thisrelatively modern widget.

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

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

The gtable widget: when using [<- to replace values, indices don’t work and when replacingdata frame the replacement must have same number of columns, each with the same type; has nonames<- method to set column names. Only addHandlerClicked and addHandlerDoubleclickare working.

The filtering feature (specified through filter.FUN say) is not implemented. However, a protomethod filter is available to filter by a column name and regular expression after the widget isshown. Call as in: tbl=gtable(mtcars, ...); tbl$filter("cyl","6"). The ex-gtableexample 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 allowsone to specify the widths of each column in pixels. Otherwise these are intuited from the maxmimnumber of characters in each column at time of construction.

The formatting of the columns is controlled by a few javascript functions. For example the for-matting 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, defing 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 atonce. The number of lines displayed is specified 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 providesdifferent means to edit the values. However, there is no capacity to add rows or columns. (Onecould start with more rows and columns than needed and then trim.) As the column types comefrom 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. Fornumeric 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 first as acharacter 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 logicalvector. In addition, a proto method filter is available to filter by a column name and regular ex-pression 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 parentargument. The methods svalue<- and enabled<- can be used to set the label and the en/dis ablethe items.

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

At this time, support for popup menus via add3rdMousePopupMenu and addPopupMenu is not im-plemented.

The gtoolbar widget is subsumed in the gmenu widget. The gaction constructor can be used tocreate 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 aretransient, lasting for about 10 seconds.

The gseparator widget only works for horizontal lines, and simply uses the HR tag within theghtml widget.

The ggooglemaps widget allows one to integrate google maps into an application. It is not working.This constructor is gWidgetsWWW specific and is documented in its own help file.

Dialogs:

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

gWidgetsWWW-package 9

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

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

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 thetext typed into the box.

As an alternative to gconfirm and ginput a subwindow can be used. These are created by thegwindow constructor when the parent argument is specified. (The dialogs are modal, the subwin-dow 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 usedto define 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 GUIis 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 behavedifferently) 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 novisible=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 sizingfor many widgets is "auto", which will fill the width of the page. This will make horizontal=TRUEnot behave as expected.

The print method for windows (gwindow) will print out the javascript to produce the page. Thisis 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 charactervector; a URL which returns a string (URLs are identified by the function isURL); or a list withcomponents title and message, where the title component is a string and the message componenta character vector.

Handlers:

The interactivity between the web browser GUI and R is provided by handlers which respond to GUIsignals sent when an event occurs. For instance, when the mouse clicks on a button, a mousedownsignal is sent. The gWidgetsWWW code allows R\/ functions to be used as handlers. These functionscreate JavaScript code to update the the web browser. The gWidgetsWWW package takes themethods of gWidgetsWWW and produces the JavaScript code, so the R\/ programmer need onlyknow how to program in R.

Handlers in gWidgetsWWW are slightly different than in other implementations of gWidgets. Aswith others, the first argument to the handler, traditionally h, is a list with components obj, referringto the widget; action, referring to the value passed into the action argument; and occasionallyothers.

Handlers are added to the widget through the handler argument of the constructor, or using one ofthe addHandlerXXX methods. The constructor assigns a default signal (or more) to bind the handlerto. 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 asignal.

Handlers may not evaluate within the scope of the function, as one would expect. This should beaddressed. 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 currentlysupported.

Compound widgets:

The gcommandline widget is implemented to run locally only. It provides a simple notebook likeinterface. The implementation does not follow the API of gWidgets, the only arguments are thecontainer, 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. Thiswas done as much for variety than any other reason. The user of gWidgetsWWW need not beaware 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 constructionof the widget, but are not specified by the arugments to the constructor. This is due to the EXTlibraries having more options, than are given by gWidgets. For instance, in the gcombobox functionthe properties ..hideTrigger and ..emptyText can be set. The ..hideTrigger values is a logicalvalue, 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 ..emptyTextargument 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 specific,hence the funny names.

Another way to modify a widget is to set the method ..ExtCfgOptions. This should be a functionwhich returns a list. The named components of the list map to the properties of the EXT con-structor. (See that API for things you may want). These values will override any others set bygWidgetsWWW. The conversion will quote values of type character. If this is undesired, use theclass String returned by the String function.

The above two examples set properties of the object. These only effect the rendering if set priorto rendering. To affect the widget after rendering, one can create JavaScript to be sent back tothe browser. This can only occur during a handler. Most of the gWidgetsWWW methods eventuallycall a function ending in JS. For instance, svalue<- calls the proto method setValue which inturn 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 <jverzani@gmail.com>

See Also

gWidgets

gcanvas Interface to canvas device

Description

This function allows the canvas package to create a javascript device. Although this isn’t workingwith all browsers, it does work quite well with firefox.

12 gcanvas

Usage

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

Arguments

f optional filename 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 ifvery similar to a regular, non-interactive R device, such as png. The gcanvas widget provides thescreen space to display the graphic.

The svalue<- method is used to update the graphic. By default the background color for a canvasdevice is transparent, so graphs will layer on top of each other. To avoid this, specify a backgroundcolor 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 fixedvariable name. This includes subwindows of a GUI, so this is a poor choice for using in a windowthat can be dismissed and re-opened.

Both the gcanvas constructor and the canvas device have width and height arguments. Theseshould 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 graphf <- tempfile() ## A file to store the javascript codecanvas(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 methodb <- gbutton("click me", cont = g, handler = function(h,...) {canvas(file=f, width=480, height=400, bg="#ffffff") ## specify a

## background colorhist(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 specific.

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 vectorof 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 hopefullyjust 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 keyargument. 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. Thefollowing will work for the domain 127.0.0.1:8079:

<script src="http://maps.google.com/maps?file=api&v=2.x&key=ABQIAAAAYpRTbDoR3NFWvhN4JrY1ahS5eHnalTx_x--TpGz1e2ncErJceBS7FrNBqzV5DPxkpbheIzZ9nTJPsQ"type="text/javascript"></script>

This widget is experimental. Its API is still not settled. As of now, the method svalue<- is used toset 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 aremoved with the mouse.

The [$<$- method can be used to set markers. The value can These are specified in a 2 or 3 columndata 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 argumentof the handler, h, is, as usual, a list. The component latlng contains a vector with the latitude andlongitude of the location the mouse click occurred at.

More of the Google maps API is availble through some proto methods. These methods are calledusing 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 oflatitude 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 pointwith tooltip. These markers may be draggable. A popup shows the new coordinates afterdragging. 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 graphicfunction, this method adds line segments to the map. The points are specified in latlng, whichis a matrix or data frame with columns of latitude and longitude values. If this is missing, thevalues set via [$<$- and addMarker are used. The color is set using hexadecimal RGB nota-tion, eg. "\#ff0000". Opacity levels less than 1 allow the map to bleed through. When the lineis 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 specified by a matrix (or data.frame) to latlng. If missing, the values setvia [$<$- or addMarker are used.. When the polygon is clicked its area in square meters ispresented.

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 graphicscommands in R. The processing.js (http://ejohn.org/blog/processingjs) javascript library isused to provide an interface to the canvas web object.

The package also provides gcanvas, for the canvas device, which uses the same technology todisplay 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-based graphics.

The gcanvas widget is more straightforward to use, but this widget is still included, as it can beused to create relatively interactive graphics with the local server version of gWidgetsWWW. Forthis use, no installation is required.

This does not work like a typical R device. The constructor returns a proto object, for which severalmethods are defined, including many familiar graphics primitives. Methods for proto objects arecalled through the object-oriented notation obj$methodname(arguments).

The proto object has properties ..margin and ..background that may be changed directly toadjust 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 valuesare 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 thegraphic. 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 ad-justed by col

p\$polygon(x, y=NULL, col=NA Draw polygon using opints in x and y. The col sets the interiorfill.

p\$rect(xleft, ybottom, xright, ytop, col=NA, ...) Draw rectangle(s) filling 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 la-bel 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 APIallows 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, themethods "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 thebrowser 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 sliderw <- gwindow("processing example")g <- ggroup(horizontal=FALSE, cont=w)x <- faithful$eruptionsp <- 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 clicksx <- c(); y <- c()glabel("Click in graph to set points", container=g)p1 <- gprocessingjs(width=500, height = 400, container = g)p1$..background <- 200p1$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 backgroundp1$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 = 200p1$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.5p1$addHandlerMousemove(handler = function(h,...) {

xy = p1$pixelsToXY(h$xy) ## need to convert to user coordinatesp1$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 files 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, thelatter allows for some very fancy javascripting to make dynamic graphics.

Usage

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

Arguments

f optional filename storing file 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, thereare facilities to create a temporary file in a public webspace getStaticTempFile. This functionuses the variable gWidgetsWWWStaticDir which must be configured for RApache. The functionconvertStaticFileToUrl 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 specified. The SVGgraphics "S"cale to fill the allotted space.

Adding a handler to this device is not yet supported. However, the SVGAnnotation package allowsone to do very interesting things with svg graphic files.

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

See Also

RSVGTipsDevice, gcanvas

Examples

## Not run:w <- gwindow("svg test")g <- ggroup(cont = w)sg <- gsvg(cont = g)

makePlot <- function() {require(RSVGTipsDevice, quietly=TRUE, warn=FALSE) # must require within callbackf <- getStaticTmpFile(ext=".svg") ## use the extension or paste laterdevSVGTips(f)plot(rnorm(100))dev.off()f

}

svalue(sg) <- makePlot()## can updateb <- gbutton("click me", cont = g, handler = function(h,...) {

svalue(sg) <- makePlot()})

visible(w) <- TRUE

## End(Not run)

gwebvis Interface to webvis device

Description

This function uses the webvis package to create a device

Usage

gwebvis(wv, handler=NULL, action=NULL, container = NULL, ...)

Arguments

wv webvis argument

handler handler

action action argument

container parent container for processing object

... not used

gWidgetsWWW-helpers 21

Details

???

Value

Returns a proto object with class gWebvis.

Author(s)

John Verzani

References

The webvis device package

gWidgetsWWW-helpers Helper functions in gWidgetsWWW

Description

These functions are simple convenience functions.

Details

The function escapeHTML converts HTML, such as $<$ into a corresponding entity. The reverse isdone unescapeURL, so named as such encoding is typically done in URLs.

The function asURL simply adds the class URL to a character. This allows gWidgetsWWW to iden-tify local URLs that are not prefaced with http://.

The function String creates an object of class String. This class treats a character string as a vec-tor of letters. (That is, "abc" is c("a","b","c").) The method c can be used to combine strings.The more natural (in some way, but not every way) + method can also be used to join strings. Thisis the primary convenience of this class. Otherwise, the [ method is useful for string extraction.The length method is an alternative to nchar.

The need for temporary files that can be accessed through a URL gives rise to the functionsgetStaticTmpFile, which creates a temporary file, and convertStaticFileToUrl which returnsthe URL from the name of the static temporary file.

22 gw_package

gWidgetsWWW-undocumented

Undocumented functions in gWidgetsWWW

Description

The main source for documentation of gWidgetsWWW is in the gWidgets package. Changes tothe API are discussed in the gWidgetsWWW-package help file.

gw_browseEnv A simple workspace browser...

Description

A simple workspace browser

Details

Available for local use

Value

Creates a web page for browsing objects in the workspace

gw_package a package browser/installer...

Description

a package browser/installer

Details

Available for local installs only

Value

makes a web page for managing installation/loading of packages

localServerStart 23

localServerStart Function to interact with local web server

Description

The gWidgetsWWW package allows gWidgets scripts to be run through a web browser. For widerdeployment, the package can be run through the RApache package. To develop scripts and to runscripts standalone, the local server may be used.

The package uses R’s dynamic help web server for the local server. The main functions arelocalServerStart, localServerOpen and localServerSource.

Usage

localServerStart(file = "", port = 8079, package = NULL, ...)

localServerOpen(file, package=NULL, ...)

localServerSource(file_or_url)

gWidgetsWWWIsLocal()

localServerStop()

localServerRestart()

Arguments

file Name of file to open. If no package is specified, this is a file relative to thedirectory returned by getwd. If the package argument is given, then the file isfound from the call system.file(file, package=package).

package If specified, files are found reltive to this package through system.file(file,package=package).

file\_or\_url A file or url to source in to create the web page.

port Deprected

... passed to constructor

Details

The calls localServerOpen and localServerSource will start the help system web server if itisn’t already started.

Use localServerSource to download a file from a website to run. This allows one to distributescripts quite easily.

24 localServerStart

There is no way to send information to the browser from the R console. The browser must initiatethe request.

The local server logs error messages in the console.

The functions localServerStop and localServerRestart are deprected.

Value

For localServerStart, localServerOpen and localServerSource a new browser page is opened.

Author(s)

John Verzani

References

The dynamic help system is well described by Duncan Murdoch and Simon Urbanek here in "TheNew R Help System." The R Journal, 1(2):60-65, December 2009. The use of a custom handler wasderived by work of Romain Francois’s highlight package http://romainfrancois.blog.free.fr/.

See Also

Rpad where this idea originated.

Examples

## Not run:localServerStart() # opens browser with files in working directorylocalServerOpen(file="Examples/ex-index.R", package="gWidgetsWWW")

## End(Not run)

Index

∗Topic interfacegcanvas, 11ggooglemaps, 13gprocessingjs, 15gsvg, 18gwebvis, 20gWidgetsWWW-helpers, 21gWidgetsWWW-undocumented, 22

∗Topic misclocalServerStart, 23

∗Topic packagegWidgetsWWW-package, 2

add (gWidgetsWWW-undocumented), 22addDropMotion

(gWidgetsWWW-undocumented), 22addDropSource

(gWidgetsWWW-undocumented), 22addDropTarget

(gWidgetsWWW-undocumented), 22addHandler (gWidgetsWWW-undocumented),

22addHandlerBlur

(gWidgetsWWW-undocumented), 22addHandlerChanged

(gWidgetsWWW-undocumented), 22addHandlerClicked

(gWidgetsWWW-undocumented), 22addHandlerDestroy

(gWidgetsWWW-undocumented), 22addHandlerDoubleclick

(gWidgetsWWW-undocumented), 22addHandlerExposed

(gWidgetsWWW-undocumented), 22addHandlerIdle

(gWidgetsWWW-undocumented), 22addHandlerKeystroke

(gWidgetsWWW-undocumented), 22addHandlerMouseclick

(gWidgetsWWW-undocumented), 22

addHandlerMouseMotion(gWidgetsWWW-undocumented), 22

addHandlerSelect(gWidgetsWWW-undocumented), 22

addSpace (gWidgetsWWW-undocumented), 22addSpring (gWidgetsWWW-undocumented), 22addStockIcons

(gWidgetsWWW-undocumented), 22asURL (gWidgetsWWW-helpers), 21

blockHandler(gWidgetsWWW-undocumented), 22

convertStaticFileToUrl(gWidgetsWWW-helpers), 21

delete (gWidgetsWWW-undocumented), 22dispose (gWidgetsWWW-undocumented), 22

enabled (gWidgetsWWW-undocumented), 22enabled<- (gWidgetsWWW-undocumented), 22escapeHTML (gWidgetsWWW-helpers), 21

focus<- (gWidgetsWWW-undocumented), 22font<- (gWidgetsWWW-undocumented), 22

gaction (gWidgetsWWW-undocumented), 22galert (gWidgetsWWW-undocumented), 22gbigtable (gWidgetsWWW-undocumented), 22gbutton (gWidgetsWWW-undocumented), 22gcalendar (gWidgetsWWW-undocumented), 22gcanvas, 11, 20gcheckbox (gWidgetsWWW-undocumented), 22gcheckboxgroup

(gWidgetsWWW-undocumented), 22gcombobox (gWidgetsWWW-undocumented), 22gcommandline

(gWidgetsWWW-undocumented), 22gconfirm (gWidgetsWWW-undocumented), 22gdf (gWidgetsWWW-undocumented), 22gdroplist (gWidgetsWWW-undocumented), 22

25

26 INDEX

gedit (gWidgetsWWW-undocumented), 22getStaticTmpFile (gWidgetsWWW-helpers),

21getStockIcons

(gWidgetsWWW-undocumented), 22gexpandgroup

(gWidgetsWWW-undocumented), 22gfile (gWidgetsWWW-undocumented), 22gformlayout (gWidgetsWWW-undocumented),

22gframe (gWidgetsWWW-undocumented), 22ggooglemaps, 8, 13ggraphics (gcanvas), 11ggroup (gWidgetsWWW-undocumented), 22ghtml (gWidgetsWWW-undocumented), 22gimage (gWidgetsWWW-undocumented), 22ginput (gWidgetsWWW-undocumented), 22glabel (gWidgetsWWW-undocumented), 22glayout (gWidgetsWWW-undocumented), 22gmenu (gWidgetsWWW-undocumented), 22gmessage (gWidgetsWWW-undocumented), 22gnotebook (gWidgetsWWW-undocumented), 22gpanedgroup (gWidgetsWWW-undocumented),

22gprocessingjs, 15gradio (gWidgetsWWW-undocumented), 22gseparator (gWidgetsWWW-undocumented),

22gslider (gWidgetsWWW-undocumented), 22gspinbutton (gWidgetsWWW-undocumented),

22gstatusbar (gWidgetsWWW-undocumented),

22gsvg, 18gtable (gWidgetsWWW-undocumented), 22gtext (gWidgetsWWW-undocumented), 22gtree (gWidgetsWWW-undocumented), 22gw_browseEnv, 22gw_package, 22gwebvis, 20gWidgetsWWW (gWidgetsWWW-package), 2gWidgetsWWW-helpers, 21gWidgetsWWW-package, 2gWidgetsWWW-undocumented, 22gWidgetsWWWIsLocal (localServerStart),

23gwindow (gWidgetsWWW-undocumented), 22

isExtant (gWidgetsWWW-undocumented), 22

isURL (gWidgetsWWW-helpers), 21

lines, 15localServerOpen (localServerStart), 23localServerRestart (localServerStart),

23localServerSource (localServerStart), 23localServerStart, 23localServerStop (localServerStart), 23

makeSessionID (localServerStart), 23

polygon, 15

removeHandler(gWidgetsWWW-undocumented), 22

runHandler (gWidgetsWWW-helpers), 21

shQuoteEsc (gWidgetsWWW-helpers), 21size (gWidgetsWWW-undocumented), 22size<- (gWidgetsWWW-undocumented), 22String, 11String (gWidgetsWWW-helpers), 21svalue (gWidgetsWWW-undocumented), 22svalue<- (gWidgetsWWW-undocumented), 22

tag (gWidgetsWWW-undocumented), 22tag<- (gWidgetsWWW-undocumented), 22tooltip<- (gWidgetsWWW-undocumented), 22

unblockHandler(gWidgetsWWW-undocumented), 22

unescapeURL (gWidgetsWWW-helpers), 21

visible (gWidgetsWWW-undocumented), 22visible<- (gWidgetsWWW-undocumented), 22