gWidgets2-package: gWidgets2. An API for programming GUIs
In gWidgets2: Rewrite of gWidgets API for Simplified GUI Construction

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.

gbutton: Provides a basic button to initiate an action
gcalendar: Provides a text entry area with selector for a date
gcheckbox: Provides a labeled checkbox to allow a user to toggle a selection
gcheckboxgroup: Provides a collection of checkboxes allowing selection or 0, 1, or several from many items
gcombobox: Provides a drop down list of choices to select from and possible and entry area for free response
gdf: Provides a data frame editing widget
gedit: Provides a single line text entry widget
ggraphics: Provides an embeddable graphic device
gimage: Provides a widget to hold images
glabel: Provides a widget to hold labels for other controls
gmenu: Provides menus for top-level windows and popup menus
gradio: Provides a means to select one of many items
gseparator: Provides a visual line to separate off parts of a window
gslider: Provides a means to select one value from a (seeming) continuum of values
gspinbutton: Provides means to select a value from s sequence of values
gstatusbar: Provides a widget to display status messages in a top-level window
gtable: Provides a widget to display tabular data for selection
gtext: Provides a multiline text-editing widget
gtimer: Provides a one-shot or repeatable timer
gtoolbar: Provides toolbars for top-level windows
gtree: Provides a display for heirarchicial data
gvarbrowser: Provides a widget showing a shapshot of the current global workspace
gaction: 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:

gexpandgroup: Provides a container with an option to disclose or hide its children
gframe: Provides a framed box container
ggroup: Provides a horizontal or vertical box container for packing in child components
glayout: Provides a container to organize data by row and column cell
gnotebook: Provides a notebook container
gpanedgroup: Provides a divided container with adjustable divider
gstackwidget: Provides a container like a notebook, but without tab labels
gwindow: 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.

gmessage: Produces a simple dialog to display a message
gconfirm: Produces a dialog for a user to confirm an action
ginput: Provides a dialog to gather user in=put
gbasicdialog: Provides a means to produce general modal dialogs
galert: Provides a short transient message dialog
gfile: Provides a dialog to select a filename or directory name

Methods

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
isExtant: 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.
getToolkitWidget: Returns the underlying toolkit object that is packaged into a gWidgets2 object
add: Method used to add a child component to a parent container
delete: Method used to delete a component from its parent
dispose: 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.
dim: 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
update: 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.

addHandlerChanged: Assigns callback for the most generic event
addHandlerClicked: Assigns callback for a mouse click event
addHandlerDoubleclick: Assigns callback for a mouse double-click event
addHandlerRightclick: Assigns callback for a mouse right-click event
addHandlerColumnclicked: Assigns callback for a column-click event
addHandlerColumnDoubleclicked: Assigns callback for a column-double-click event
addHandlerColumnRightclicked: Assigns callback for a column-right-click event
addHandlerSelect: Assigns callback when the underlying selection is changed
addHandlerFocus: Assigns a callback for when a widget receives focus
addHandlerBlur: Assigns a callback for when a widget loses focus
addHandlerDestroy: Assigns a callback for when a widget is destroyed
addHandlerUnrealize: For gwindow this is called before the destroy event and may stop that from happening.
addHandlerExpose: Assigns callback to be called when a widget is exposed
addHandlerKeystroke: Assigns callback to be called when a key event occurs
addHandlerMouseMotion: Assigns callback to be called when a mouse moves over a widget
addHandler: Base method to add a callback though rarely called, as it is toolkit specific
addHandlerIdle: Assign a callback to be called at periodic intervals. See also gtimer
addPopupMenu: Add a popup menu
addRightclickPopupMenu: Add a popup menu for the right mouse (context menu)
addDropSource: Specify widget as a source (drag area) for drag and drop
addDropTarget: Specify widget as a target (drop area) for drag and drop
addDragMotion: 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)
removeHandler: Remove a handler by it ID