gWidgetsWWW-package {gWidgetsWWW}R Documentation

Toolkit implementation of gWidgets for WWW

Description

Port of gWidgets API to WWW using the Rpad package and the ExtJS javascript libraries.

Details

This package ports the gWidgets API allowing the creation of interactive webpages. The interactivity is provided through the Rpad package. The webpages themselves use the Ext toolkit (www.extjs.com) to render the widgets. This toolkit must be installed separately and configured to work.

As gWidgets is meant to be multi-toolkit, this file documents differences from the API, of which there are many. However, this package is not compatible with the gWidgets package so reading that documentation is best done with a separate R process.

Overview:

The gWidgetsWWW package at one level maps R/ commands to javascript commands. 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. (Rpad itself has a similar set of libraries – the open source dojo toolkit, www.dojotoolkit.org– but gWidgetsWWW uses extjs, which although is not as freely licensed, it is more up to data and has an excellent API and set of examples.) 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 Rpad package provides a mechanism for the web page to call back into the R/ program. The same R/ session is used throughout the lifetime of a page. (That means don't refresh the page.) The server version of Rpad can open several different sessions to handle multiple requests. When a page calls the R/ session, the gWidgets code can produce JavaScript to cause the page to do something, such as update the GUI. This allows the web page to be interactive. 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:

Before the package can run, both the Rpad package and the Ext libraries must be installed. The Rpad package installation performs a local installation without much work. The "server" installation requires an external web served to be set up. The package provides a script to automate the configuration. The Rpad package installs a javascript toolkit dojo. The web page must call this in and the Rpad code. Some sample code to do so might be

<script type="text/javascript" src="gui/dojo.js"></script>
<script type="text/javascript" src="gui/Rpad_main.js"></script>

The Ext libraries may be downloaded from www.extjs.com. Ext has a dual-license model, offering an open source LGPL license along with a per-developer, royalty-free commercial license. The gWidgetsWWW package makes no assumptions about where this library is installed, but the web page that calls the R/ code must call in these javascript libraries. The examples use

<script type="text/javascript" src="ext-2.1/adapter/ext/ext-base.js"></script>
<script type="text/javascript" src="ext-2.1/ext-all.js"></script>

To complete the installation, the gWidgetsWWW package provides some stock icons. For now, these icons need to be installed in directory called images in the base directory of the web server.

Containers:

The gwindow container is treated differently in gWidgetsWWW than in gWidgets. There can be only one top-level window, as this maps to a 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 isn't rendered until the web page is ready to display. This rendering is done through the print method. In particular, the 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 defined.

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 defined.

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 specifies the location using the [ method and specifies 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.

Tje gformlayout widget is used to layout widgets using glayout is imlemented.

Widgets:

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 define 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 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.

The gspinbutton widget is not yet implemented. One can use the gslider widget instead.

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 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 files. There is no handler defined 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, 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 gfilebrowse widget needs writing

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 addHandlerClick and addHandlerDoubleclick are working. The filtering feature (specified through filter.FUN say) is not implemented. The icon.FUN should return either url's or stock icon names.

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). Thi scan 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 first as a character vector to edit. and then take them off again.

The gtree widget needs writing.

The gaction widget creates "actions" which can be used in menubars and attached to buttons. 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.

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 status 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. This constructor is gWidgetsWWW specific and is documented in its own help file.

Dialogs:

The galert(title = "", message = "", delay=3) dialog is specific to gWidgetsWWW. It creates a quick alert that pops down from the top of the web page. It has a title and message argument for the message and delay in seconds to specify the time the dialog appears.

The other dialogs 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 has an issue. The handler is called on the "ok" selection, but the javascript code it produces is not rendered by the browser. This is due to some elusive subtlety with cat that will hopefully be identified and worked around.

The ginput widget has the same issue with the handler as gconfirm.

As an alternative to gconfirm and ginput a subwindow can be used. These are created by the gwindow constructor when the container argument is specified.

icons:

The funtion getStockIcons returns a vector of these icons. The names of this vector may be used to 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 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 dispose<- method only hides 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.

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 fill 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.

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 identified 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 – through the essential Rpad package – 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.

Handlers write out javascript to be interpreted by the web browser. No other output to STDOUT should be inside the handler body. That is, don't use print or cat.

Drag and Drop:

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

Compound widgets:

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 specified 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 specific, 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. This should cat out javascript code.

If you do this, and think your code should be integrated into the main code, please share it.

Author(s)

John Verzani <gwidgetsrgtk@gmail.com>

See Also

gWidgets


[Package gWidgetsWWW version 0.0-6 Index]