gWidgetsWWW-package {gWidgetsWWW} | R Documentation |
Port of gWidgets API to WWW using the Rpad package and the ExtJS javascript libraries.
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.
John Verzani <gwidgetsrgtk@gmail.com>
gWidgets