gWidgets2-package {gWidgets2} | R Documentation

## 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.

### 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

### Author(s)

John Verzani jverzani@gmail.com

Maintainer: John Verzani jverzani@gmail.com

[Package gWidgets2 version 1.0-8 Index]