gWidgetstcltk-package {gWidgetstcltk}R Documentation

Toolkit implementation of gWidgets for tcltk

Description

Port of gWidgets API to tcltk. The gWidgets API is an abstract, lightweight means to interact with GUI toolkits. In this case, the tcltk toolkit.

Details

This file documents differences between gWidgetstcltk and the gWidgets API, which is documented both in the man pages for that package and in its vignette. The gWidgetstcltk package is not as complete as gWidgetsRGtk2. This is due to limitations in the base libraries implementing tcl/tk. This package was designed to work with the limited version that comes with the standard Windows installation of R.

Notes on this implementation:

The primary difference in this version is that each widget requires a container when being constructed. The container is given to the container argument. The value may be the logical TRUE indicating that a new window is constructed, or a container widget. This precludes the two-step process of creating a widget, then adding it to a container. As such, use the arguments to add in the construction of the widget. that is

  g = ggroup(cont=gwindow("An example"))
  b = gbutton("a button")
  add(g, b, expand=TRUE)

Would be combined, as in:

  g = ggroup(cont=gwindow("An example"))
  gbutton("a button", container=g, expand=TRUE)

The basic tcltk installation does not include several widgets that appear in other toolkits. For instance a grid widget, a notebook widget, etc. These are provided by extensions to the basic tcltk libraries. Rather than require users to install these libraries, the missing widgets are approximated, or hacked, as much as possible. Some are still unavailable. Suggestions as to how the hacks could be improved are welcome.

Other differences are that tcltk does not seem to have a markup language like Pango for GTK or HTML for JAVA, as such the markup argument for several widgets that is used to format text is not available. The font<- method can substitute.

Containers:

gwindow() The visible= argument is ignored. The top-level window is always produced. The width= and height= arguments refer to the minimum window size, not the preferred default size.

ggroup() also has the expand= and anchor= arguments. If expand=TRUE the widget takes up as much space as possible. The anchor= argument adjusts a widget left or right, up or down, within its space. Only one component works at a time for the anchor argument. In a horizontal box, only the y component can be used to move a value up or down. In a vertical box, only the x component can be used to move a value left or right. The default is c(-1,1) so that horizontal layouts are towards the top, and vertical layouts towards the left.

The use.scrollwindows feature is lacking.

gframe() no markup in title. Use font<- to give it markup.

gexpandgroup() This is a hack, but works well. As with gframe, the markup= argument doesn't work, but the font for the label can be adjusted using font<-.

gdfnotebook() Is a hack. There is no underlying notebook widget. The hack provides some of the functionality, but lacks the look of a true notebook widget. Primarily the tabs can grow without bounds in length (in other toolkits, gWidgetsRGtk2 for example, there is a mechanism to provide arrows for selecting among a subset of the tabs when there are too many). The tabs do not use the markup argument or have close buttons.

The add method, which is used to add pages, is called when the notebook is given as a container during the construction of a widget. Hence, to add a page something like this is done:

  nb <- gnotebook(cont=gwindow("Notebook example"))
  gbutton("Page 1", cont=nb, label = "tab1")
  glabel("Page 2", cont=nb, label = "tab2")
  gedit("Page 3", cont=nb, label = "tab3")

glayout() has two additional arguments: expand=TRUE is like expand= for ggroup(), in that the attached widget expands to fill the possible space in the container. If this isn't given the anchor= argument can be used to adjust the location of the widget withing the cell. A value of c(-1,1) is the lower left, c(-1,1) the upper left (the default), c(1,-1) the lower right, and c(1,1) the upper right. The value 0 for either is also possible.

Unlike gWidgetsRGtk2 the use of visible<- is not necessary, the widget is updated dynamically.

gpanedgroup() The constructor is called with no widgets. To add a widget to the paned group the paned group is passed as a container, as in

  pg <- gpanedgroup(container=gwindow("example"), horizontal = FALSE)
  b1 = gbutton("button 1", container=pg)
  b2 = gbutton("button 2", container=pg)

The paned window will need to be adjusted manually. The delete method can be used to delete a widget. It may be added back with the add method.

The basic widgets or components: (These may also be known as controls)

gbutton() mostly works. The button won't resize to take up all the possible space for a widget, even if expand=TRUE is given.

gcalendar() is not implemented, as there is no underlying calendar widget in the base tcltk.

gcheckbox() works as advertised

gcheckboxgroup() works as advertised

gdf() is not implemented. There is no underlying grid widget in the base tcltk.

gdroplist() This is a hack. It looks okay, but not great especially when editable=TRUE. The extra argument width= controls the width of the text box, as this does not grow dynamically.

gedit(), unlike the gWidgetsRGtk2 widget, has no type-ahead support via drop down boxes. The widget does not resize automatically. Set the width with width= at time of construction or with size<-

gfilebrowse() works.

ggraphics() Not implemented. The tkrplot package could be used in some way, but this does not provide a fully embeddable graphics device.

ghelp() Works as advertised. Uses a popup menu instead of a notebook, as gWidgetsRGtk2.

gimage() Only works with gif and pnm files, as the underlying tcltk widget only uses these by default.

glabel() No markup available. Use font<- instead.

gmenu() adds only to the top window, not any container. This is a tcltk limitation. Use a popupmenu instead.

gradio() has an extra argument coerce.with=, as otherwise it would treat everything as a character vector. It tries to guess when instantiated, if not explicitly given.

gseparator() works as expected.

gslider() in tcltk works with integer steps only. If the by= argument is less than 1 a gspinbutton() is used in place.

gspinbutton() Works as expected. The change handler responds to clicks of the arrows or to the return key in the text area.

gstatusbar() A hack. Just a ggroup() instance in disguise.

gtable() Uses the underling tklistbox which shows vectors of data. A hack creates a vector out of a matrix or data frame. The scrollbars are always present. There is no support for icons. Filtering by a column or by a function is implemented. When setting or retrieving values using svalue the index refers to the visible data set (if filtering), unlike with RGtk2.

gtext() The widget does not get dynamically resized. The size<- method can be used to resize the widget. This method guesses at the converstion from pixels to characters (width) and lines of text (height) used by the underlying widget.

gtoolbar() A hack. The buttons take up alot of screen real estate.

gtree() Not implemented.

Compound components:

gcommandline() is implemented, but could definitely be improved.

ghelpbrowser() just calls ghelp

ggenericwidget() Some kinks need ironing out when the main variable is a formula.

gdfnotebook() No gdf so no notebook

ggraphicsnotebook() No ggraphics so no notebook.

gvarbrowser() A hack. This seems to be best done with a tree widget, but none is available. One can drag variables from the list of variables.

Dialogs: (These are modal, hence they have no methods.)
gfile() works as advertised.

gmessage() works.

gconfirm() works.

ginput() works.

gdialog() Not implemented, as the widget needs to have a parent container.

Handlers:

Currently only one handler (the last one) for a signal is called. That is if you try to add to handlers for a click event, only the last will be called. As well, the removehandler function does not work except for the idle handler.

adddroptarget(), adddropsource(), and adddropmotion work for tcltk widgets. The cursor changes to a funny looking cursor, but nothing resembling a drag and drop cursor. One was chosen from the standard cursors. Dragging from other applications is not supported.

Note

Author(s)

John Verzani. Several code segments were inspired by the examples of Wettenhall and the Dalgaard article referenced below. The drag and drop code was modified from code at http://wiki.tcl.tk/416. Icons were "borrowed" from several places: the scigraphica project, KDE, and elsewhere.

Maintainer: John Verzani <gwidgetsrgtk@gmail.com>

References

Peter Dalgaard's RNews article on the tcltk pagkage http://cran.r-project.org/doc/Rnews/Rnews_2001-3.pdf; Several examples on http://bioinf.wehi.edu.au/~wettenhall/RTclTkExamples/; The PERL documentation was useful: http://search.cpan.org/~ni-s/Tk-804.027/, although this is for the most part a translation of the TK documentation.

For a package somewhat similar in intent see Bowman, Crawford, Alexander, and Bowman's rpanel package: http://www.jstatsoft.org/v17/i09/v17i09.pdf or the tkWidgets package of Zhang www.bioconductor.org.

Examples

## Not run: 
##
options(guiToolkit="tcltk")
## select CRAN miror example
setMirror = function(URL) {
   repos = getOption("repos")
   repos["CRAN"] = gsub("/$", "", URL)
   options(repos = repos)
}

  win = gwindow("Select a CRAN mirror")
  tbl = gtable(utils:::getCRANmirrors(), 
  container=win,
  chosencol=4, 
  handler = function(h,...) {
    URL = svalue(h$obj)
    setMirror(URL)
    dispose(win)
  })
##
## End(Not run)

[Package gWidgetstcltk version 0.0-5 Index]