Port of gWidgets API to RGtk2
This package allows the gWidgets API to use the RGtk2 package allowing the use of the GTK libraries within R. The documentation for the functions in this package are contained in the gWidgets package.
As gWidgets is meant to be multi-toolkit, this file documents differences from the API, as defined by the man pages of the gWidgets package.
Containers:
If using a ggraphics
device, one should call gwindow
with the argument visible=FALSE
then after the device is
added call the visible<-
method to show the window.
To access the underlying gtk container from a gframe
object
one uses getToolkitWidget(obj)$getParent()
The gnotebook changed handler has component pageno
to
indicate the newly selected page number, as the svalue
method
returns the page before the change.
Widgets:
The gbutton
constructor can not be called before
gWidgetsRGtk2 is loaded. This means that an initial call like
gbutton("label", cont=gwindow())
won't work. Instead, either
load directly gWidgetsRGtk2 (not just gWidgets) or
create another widget, like a top-level window. Something similar is the case
for the gdfedit
widget.
The gradio
widget can now have its items shortened or lengthened via [<-
.
For the data frame viewer gtable
when no filtering is
requested -- the default -- the column headers can be clicked to sort
the values. Setting the index to 0 will clear the selection.
In the data frame editor gdf
the subset
option only
works if the column names have not been changed. One can suppress
the creation of keyboard navigation and the right click popup on the
column headers. The hiddern argument diy
(for do it yourself)
if left empty will place in both. A value of "suppress.key"
or "suppress.popup"
(or both) will suppress the respective
handler.
The gaction
constructor produces action objects. The
enabled<-
method can be used to set their sensitivity. The
objects can be used with gbutton
through the action
argument, and in the lists defining menubars and toolbars. The
key.accel
argument (for assigning a keyboard accelerator) of the constructor is ignored for now. The
tooltip
is OS sensitive, as it depends on the event loop
implementation.
The gtoolbar
list can have components that are a) lists with
a handler componented, b) lists with a separator component, c)
gaction instances d) gWidgets, in which case the widget appears in
the toolbar. The latter is not portable to other gWidgets
implementations.
The gvarbrowser
constructor depends on a variable
knownTypes
. A default is provided in the package, but this can
be overridden by a) providing a hidden argument knownTypes
to
the constructor or b) setting an option knownTypes
. In each
case this is a named list whose components are character vectors
listing classes of a similar nature. For example, the default value
for knownTypes
included "data sets"=
c("numeric","logical","factor","character","integer",
"data.frame","matrix","list", "table","xtabs",
"nfnGroupedData","nffGroupedData","nmGroupedData",
"POSIXct","POSIXlt","POSIXt" )
.
The function used to map a class to an icon is by default
getStockIconFromClass
. This can be changed by assigning a
function to the option gWidgetsStockIconFromClass
. This function should take a class and return a stock icon name. (The class passed is the first value only.)
The gfile
constructor has the argument multiple
, which if
TRUE will allow for multiple selections of files. This feature
should be merged into the gWidgets API, but for now is passed in via
...
.
The ggraphics
constructor provides a means to embed a graphics
window inside a GUI. A right mouse popup allows one to copy the
graphic to the clipboard or save it to a file. The different file
types are limited by the function gdkPixbufSave
whose manual page states
that jpg, png, ico and bmp are permissable.
A few quirks exist.
Drawing a graphic too soon may result in a message about
plot.margins too small
. This comes from trying to draw the
first graphic before the window is fully realized.
One workaround is to initially set the window not visible then when the GUI is done, make the window visible. That is, try: w <- gwindow(visible=FALSE); ggraphics(cont=w); visible(w) <- TRUE; hist(rnorm(100))
When there are multiple
devices, the standard means of setting a device via dev.set
are supplemented by mouse handlers. Clicking in the graphics window
sets the window as the current device.
The handler for addHandlerClicked
responds to a mouse
click. The components x
and y
give the coordinates in
"usr" coordinates.
The handler for addHandlerChanged
responds to the
"rubber-banding" effect that comes from trying to trace out a
rectangle in the graphic window. The components x
and y
give the coordinates in "usr" coordinates. (These each have two
values.) The functions grconvertX
and grconvertY
can
convert to other coordinate systems for you. See the ggraphics
help page for an example of how
this can be used to update a data frame.
The gbasicdialog
constructor can be used both ways. The hidden
argument buttons
can take values ok
, yes
,
cancel
, close
, no
, with a default of c("ok","cancel")
.
Methods:
The font
method is not implemented.
For widgets which allow markup (gframe
, glabel
) PANGO
markup is used. This is not HTML, but is similar to basic HTML.
gWidgetsRGtk2 and the RGtk2 package:
The RGtk2 package is imported only so its namespace, which is large, is not loaded by default. To access its functions, load the package.
The RGtk2 package and gWidgetsRGtk2 can be used together
in the following ways. First, an RGtk2 object can be added to
a gWidgetsRGtk2 through the add
method of the
container. This works for most objects. If you find one that doesn't
work, simply place it inside a gtkHBox
container, then add
that container. Second, a gWidgetsRGtk2 object can be added to
to a RGtk2 container by adding the return value of the
getToolkitWidget
method of the object. Again, this should
work, but if not, the gWidgetsRGtk2 can be added to a
ggroup
container first. In either case, the
gWidgetsRGtk2 object should not be previsously attached to a container, so
in particular the constructor should be called with its
container
argument as NULL
(the default).
gWidgets