gWidgets2-package: gWidgets2. An API for programming GUIs

Description Details Author(s)


The gWidgets2 package provides a programming interface for making graphical user interfaces within R. The package is a rewrite of the gWidgets package, introducing a few external changes but a significant number of internal ones. The package relies on one of several underlying toolkit packages providing access to the graphical libraries. These will include RGtk2, tcltk, qtbase, and a collection of browser widgets provided by ExtJS. As of now, only gWidgets2RGtk2 is near completion.


The package provides constructors to produce controls, the widgets that a user interacts with; containers, GUI objects used to organize the controls within a window; and dialogs, simple one-off windows for gathering quick user feedback. These objects are manipulated through various methods. The package provides a few new generics and, as much as possible, leverages existing methods for R.

Control constructors

Controls are created by constructors. The package API includes the following. As much as possible these are implemented in the toolkit packages, but there may be instances where that is not possible.


Provides a basic button to initiate an action


Provides a text entry area with selector for a date


Provides a labeled checkbox to allow a user to toggle a selection


Provides a collection of checkboxes allowing selection or 0, 1, or several from many items


Provides a drop down list of choices to select from and possible and entry area for free response


Provides a data frame editing widget


Provides a single line text entry widget


Provides an embeddable graphic device


Provides a widget to hold images


Provides a widget to hold labels for other controls


Provides menus for top-level windows and popup menus


Provides a means to select one of many items


Provides a visual line to separate off parts of a window


Provides a means to select one value from a (seeming) continuum of values


Provides means to select a value from s sequence of values


Provides a widget to display status messages in a top-level window


Provides a widget to display tabular data for selection


Provides a multiline text-editing widget


Provides a one-shot or repeatable timer


Provides toolbars for top-level windows


Provides a display for heirarchicial data


Provides a widget showing a shapshot of the current global workspace


Provides a means to encapsulate actions for use with menu bars, tool bars and buttons.

Containers are used to organize controls with a window. The package provides the following:


Provides a container with an option to disclose or hide its children


Provides a framed box container


Provides a horizontal or vertical box container for packing in child components


Provides a container to organize data by row and column cell


Provides a notebook container


Provides a divided container with adjustable divider


Provides a container like a notebook, but without tab labels


Provides a top-level window

Dialog constructors

Dialogs in gWidgets2 are typically modal, meaning they block input to any other window and the R process. They do not return objects to be manipulated through methods, but rather return values selected by the user.


Produces a simple dialog to display a message


Produces a dialog for a user to confirm an action


Provides a dialog to gather user in=put


Provides a means to produce general modal dialogs


Provides a short transient message dialog


Provides a dialog to select a filename or directory name


Except for dialogs, the constructors produce objects for which several methods are defined that allow the programmer access to getting and setting of the object state. For the most part these are S3 methods. The actual returned object is a reference class instance, as provided by an underlying toolkit. These may have toolkit-specific methods defined as reference class methods (i.e., call them using $meth_name). Any such methods are documented in the toolkit packages.

svalue, svalue<-

The main new method. This is used to retrieve or set the main property associated with a widget

enabled, enabled<-

A widget is enabled if it is sensitive to user input. Non-enabled widgets typically are rendered in a greyed out state.

visible, visible<-

The generic idea of a visible widget is one that is drawn. However, several classes override this to mean part of the widget is visible or not visible.

focus, focus<-

A widget with focus receives any keyboard input.

editable, editable<-

A widget is editable if it can receive keyboard input.

font, font<-

The font for an object is specifed through this method using a convention illustrated in the help page.

size, size<-

The size of a widget is retrieved or requested through these methods

tooltip, tooltip<-A tooltip provides contextual information when a mouse hovers over an object

undo, redo

Some widgets support an undo and redo stack


A method to check if the GUI part of a widget still exists. (A constructor produces an R object and GUI object through the toolkit.)

tag, tag<-

A method used to set attributes for an object that are stored in an environment so that they are passed by reference, not copy. This allows event handlers to manipulate an object's attributes outside the scope of the callback.


Returns the underlying toolkit object that is packaged into a gWidgets2 object


Method used to add a child component to a parent container


Method used to delete a component from its parent


Method used to delete a component

The package overloads some familar R methods.

length, length<-

Returns the length of an object, typically related to the number of children a container has, or the length of the items that a user can selection from.


Used to return row and column size information as applicable.

names, names<-

Used to set the names associated to an object. These may be column names in the table widget, or tab names in the notebook container.

dimnames, dimnames<-

Used to set row and column names, as applicable.

[, [<-

Used to update the underlying items that a selection widget offers. Also used to specify layout in glayout


Call to update the state of a widget, when applicable.

Event handlers

Graphical User Interfaces are made interactive by assigning a function (a callback) to be called when some event happens. In gWidgets2 the addHandlerXXX methods are defined to assign this callback to a type of event specified through the XXX, detailed below. The generic addHandlerChanged is the most common event for a widget. This event can also have a handler specified through the handler argument of the widget constructor.

In gWidgets2 handlers are functions which when called are passed a list as the first argument, and possibly toolkit-specific arguments for subsequent arguments. As such the signature typically looks like (h,...), where the list h has components obj, containing a reference to the widget emitting the event and action passing in any information specified to the action argument. Some events also pass back extra information, such as x and y for position, or key for key events, as appropriate.


Assigns callback for the most generic event


Assigns callback for a mouse click event


Assigns callback for a mouse double-click event


Assigns callback for a mouse right-click event


Assigns callback for a column-click event


Assigns callback for a column-double-click event


Assigns callback for a column-right-click event


Assigns callback when the underlying selection is changed


Assigns a callback for when a widget receives focus


Assigns a callback for when a widget loses focus


Assigns a callback for when a widget is destroyed


For gwindow this is called before the destroy event and may stop that from happening.


Assigns callback to be called when a widget is exposed


Assigns callback to be called when a key event occurs


Assigns callback to be called when a mouse moves over a widget


Base method to add a callback though rarely called, as it is toolkit specific


Assign a callback to be called at periodic intervals. See also gtimer


Add a popup menu


Add a popup menu for the right mouse (context menu)


Specify widget as a source (drag area) for drag and drop


Specify widget as a target (drop area) for drag and drop


Assign callback for event that a drag event crosses a widget

blockHandlers, blockHandler

Block all handlers for a widget (or by single ID)

unblockHandlers, unblockHandler

Unblock any blocked handlers (or by single ID)


Remove a handler by it ID


John Verzani [email protected]

Maintainer: John Verzani [email protected]

gWidgets2 documentation built on May 29, 2017, 9:20 p.m.