gWidgets2-package: gWidgets2. An API for programming GUIs

Description

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.

Arguments

Details

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