Package 'gWidgets2'

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 [email protected]

Maintainer: John Verzani [email protected]

Description

Toolkit constructor

Usage

## Default S3 method:
.gdfnotebook(toolkit, items, container = NULL, ...)

Arguments

Description

Names are used in many different contexts.

We use the extraction operator, [, typically to refer to the underlying items from which a selection can be made. As well, we overload this to containers to refer to the child components.

The update method will ca use a widget to recompute itself, if it is necessary.

The current items for a gdf object are both the visible and non-visible items. To retrieve just the currently visible items, use the idiom obj[visible(obj), ].

The underlying widget may allow autocompletion, if this is the case then this method is used to set the list of candidates.

Usage

## S3 method for class 'GDefaultWidget'
x[i, j, ...]

## S3 method for class 'GComponent'
length(x)

## S3 replacement method for class 'GComponent'
 length(x) <- value

## S3 method for class 'GComponent'
dim(x)

## S3 method for class 'GComponent'
names(x)

## S3 replacement method for class 'GComponent'
 names(x) <- value

## S3 method for class 'GComponent'
dimnames(x)

## S3 replacement method for class 'GComponent'
 dimnames(x) <- value

## S3 method for class 'GComponent'
x[i, j, ..., drop = TRUE]

## S3 method for class 'GContainer'
x[i, j, ..., drop = TRUE]

## S3 replacement method for class 'GComponent'
 x[i, j, ...] <- value

## S3 method for class 'GComponent'
update(object, ...)

## S3 method for class 'GComponent'
str(object, ...)

## S3 method for class 'GDf'
x[i, j, ..., drop = TRUE]

## S3 method for class 'GEdit'
x[i, j, ..., drop = TRUE]

## S3 replacement method for class 'GFrame'
 names(x) <- value

Arguments

Value

length of object

Description

Add packs in child objects.

Delete may or may not remove a child. This is toolkit specific. It may also be tied up with garbage collection. To avoid that, keep a reference to the child object before deleting.

Usage

add(obj, child, expand = FALSE, fill = NULL, anchor = NULL, ...)

## Default S3 method:
add(obj, child, expand = FALSE, fill = NULL, anchor = NULL, ...)

delete(obj, child)

## S3 method for class 'GContainer'
delete(obj, child)

Arguments

Description

The change handler for ggraphics is called when a rubber-band selection is completed

The click handler is called on a mouse click. The handler object should pass in value for x, y

A GUI is made interactive by assigning handlers to user-generated events, such as a mouse click, change of widget state, or keyboard press. In gWidgets2 handlers are assigned through various addHandlerXXX methods. The handlers are functions whose first argument should expect a list with components obj (to pass in the receiver object) and action (to pass in any user-supplied value to the action argument). Some handlers add other components, such as mouse position information on a click, or key information on a keyboard event.

The "changed" event varies wildly amongst the widgets, but is meant to be the most "obvious" one. Typically this is also similar to "selected".

This may not be supported by all toolkits.

This may not be supported by all toolkits.

This may not be supported by all toolkits.

For table widgets (gtable, gdf) clicking the column header should trigger this event. The column that is clicked on is passed back in the component column.

If defined (gtable, gdf) calls event handler for double click enent. Passes back column information through column component.

The select event defaults to the "changed" event.

The "select" event is when a user "selects" an object, the "selection changed" event is when the selection changes. The distinction is in table and tree widgets where a user may select values with a single click yet want to initiate an action with a double click. The latter is the "addHandlerSelect" event, the former the "addHandlerSelectionChanged" event.

When a widget has the focus, it will receive the keyboard input. This handler is called when a widget receives the focus.

A blur or focus out event for a widget triggers this event handler

When a widget is destroyed, a handler can be assigned to perform any clean up tasks that are needed.

For gwindow objects this handler is called before the window is closed. If this handler returns TRUE the window will be closed, if FALSE the window will not be closed. In contrast, the "destroy" handler does not allow conditional destruction.

The "h" argument has components key for the key and possibly modifier for the modifier.

deprecated. See gtimer.

Defaults to adding a right-click mouse popup menu, better known as a context menu, though some toolkits have both this and the latter provided.

These menus are also known as context menus, though there isn't really a good mechanism within gWidgets2 to make the menu items context sensitive.

Drag and drop requires one to register widgets a sources for dragging, a widgets as a targets for dropping.

The handler is called on the drop event. The component dropdata passes in the value being transferred by dragging.

Block all handlers for an object. Removed via unblockHandlers.

The block is a counter that gets decremented. If more blockHandlers calls are made than unblockHandlers, the handlers will still be blocked.

Usage

## Default S3 method:
addHandlerChanged(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerClicked(obj, handler, action = NULL, ...)

addHandler(obj, signal, handler, action = NULL, ...)

## Default S3 method:
addHandler(obj, signal, handler, action = NULL, ...)

addHandlerChanged(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerChanged(obj, handler, action = NULL, ...)

addHandlerClicked(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerClicked(obj, handler, action = NULL, ...)

addHandlerDoubleclick(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerDoubleclick(obj, handler, action = NULL, ...)

addHandlerRightclick(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerRightclick(obj, handler, action = NULL, ...)

addHandlerShiftclick(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerShiftclick(obj, handler, action = NULL, ...)

addHandlerControlclick(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerControlclick(obj, handler, action = NULL, ...)

addHandlerColumnclicked(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerColumnclicked(obj, handler, action = NULL, ...)

addHandlerColumnDoubleclicked(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerColumnDoubleclicked(obj, handler, action = NULL, ...)

addHandlerColumnRightclicked(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerColumnRightclicked(obj, handler, action = NULL, ...)

addHandlerSelect(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerSelect(obj, handler, action = NULL, ...)

addHandlerSelectionChanged(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerSelectionChanged(obj, handler, action = NULL, ...)

addHandlerFocus(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerFocus(obj, handler, action = NULL, ...)

addHandlerBlur(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerBlur(obj, handler, action = NULL, ...)

addHandlerDestroy(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerDestroy(obj, handler, action = NULL, ...)

addHandlerUnrealize(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerUnrealize(obj, handler, action = NULL, ...)

addHandlerExpose(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerExpose(obj, handler, action = NULL, ...)

addHandlerKeystroke(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerKeystroke(obj, handler, action = NULL, ...)

addHandlerMouseMotion(obj, handler, action = NULL, ...)

## Default S3 method:
addHandlerMouseMotion(obj, handler, action = NULL, ...)

addHandlerIdle(...)

addPopupMenu(obj, menulist, action = NULL, ...)

## Default S3 method:
addPopupMenu(obj, menulist, action = NULL, ...)

addRightclickPopupMenu(obj, menulist, action = NULL, ...)

## Default S3 method:
addRightclickPopupMenu(obj, menulist, action = NULL, ...)

## Default S3 method:
addRightclickPopupMenu(obj, menulist, action = NULL, ...)

## Default S3 method:
addRightclickPopupMenu(obj, menulist, action = NULL, ...)

addDropSource(
  obj,
  handler,
  action = NULL,
  data.type = c("text", "object"),
  ...
)

## Default S3 method:
addDropSource(
  obj,
  handler,
  action = NULL,
  data.type = c("text", "object"),
  ...
)

addDropTarget(obj, handler, action = NULL, ...)

## Default S3 method:
addDropTarget(obj, handler, action = NULL, ...)

addDragMotion(obj, handler, action = NULL, ...)

## Default S3 method:
addDragMotion(obj, handler, action = NULL, ...)

blockHandlers(obj, ...)

## Default S3 method:
blockHandlers(obj, ...)

blockHandler(obj, ID, ...)

## Default S3 method:
blockHandler(obj, ID, ...)

unblockHandlers(obj, ...)

## Default S3 method:
unblockHandlers(obj, ...)

unblockHandler(obj, ID, ...)

## Default S3 method:
unblockHandler(obj, ID, ...)

removeHandler(obj, ID, ...)

## Default S3 method:
removeHandler(obj, ID, ...)

Arguments

Details

Although the add_handler method, to which addHandler dispatches, is basically the workhorse to add a handler to response to a signal, it generally isn't called directly, as its use is not cross toolkit. Rather, if possible, one should use the addHandlerXXX methods to add a handler. These dispatch to this (basically) but do so in a toolkit independent manner.

This call (and the others) returns a handler ID which may be used for some toolkits later on to remove, block or unblock the call. All handlers for a widget may be blocked or unblocked via blockHandlers and unblockHandlers.

The "changed" event is also the one that a handler passed to the constructor is called on.

To specify the values that is transferred in a drag and drop event, the handler specified here should return the value to pass via drag and drop. It will appear as the dropdata component of the list passed in as the first argument of the drop handler

Value

a handler ID which can be used to block/unblock or remove the handler

Note

This method is not toolkit independent, as the signal value depends on the toolkit

For the gWidgets2Qt package one can not block, unblock or remove a single handler, but rather must do all the objects handlers at once.

See Also

blockHandlers, unblockHandlers, blockHandler, unblockHandler, and removeHandler

addHandlerUnrealize.

blockHandlers to block all handlers for widget

Description

A spring will separate the children packed in the box container prior to the spring be added and those being added, pushing the two as far apart as the allocated space will allow.

Add spring to GContainer class

Inserts a specific amount of space between the previously packed child and next one.

Add space to GContainer class

Usage

addSpring(obj)

## S3 method for class 'GContainer'
addSpring(obj)

addSpace(obj, value)

## S3 method for class 'GContainer'
addSpace(obj, value)

Arguments

Description

Method to add icon to list of stock icons

generic for dispath

toolkit implementation

return list of available stock icons

generic for toolkit dispatch

default

Return stock icon name, filename, icon object from its by name

generic

default implementation

Find a stock icon from the given class

generic for dispath

Default stock icon for a given class name

Find stock icon from the given object

generic for dispath

get stock icon from object by class

Usage

addStockIcons(iconNames, iconFiles, ..., toolkit = guiToolkit())

.addStockIcons(toolkit, iconNames, iconFiles, ...)

## Default S3 method:
.addStockIcons(toolkit, iconNames, iconFiles, ...)

getStockIcons(..., toolkit = guiToolkit())

.getStockIcons(toolkit, ...)

## Default S3 method:
.getStockIcons(toolkit, ...)

getStockIconByName(name, ..., toolkit = guiToolkit())

.getStockIconByName(toolkit, name, ...)

## Default S3 method:
.getStockIconByName(toolkit, name, file = TRUE, ...)

stockIconFromClass(theClass, ..., toolkit = guiToolkit())

.stockIconFromClass(toolkit, theClass, ...)

## Default S3 method:
.stockIconFromClass(toolkit, theClass, ...)

stockIconFromObject(obj, ..., toolkit = guiToolkit())

.stockIconFromObject(toolkit, obj, ...)

## Default S3 method:
.stockIconFromObject(toolkit, obj, ...)

Arguments

Value

list of icons with names the icon name and values the icon file name or icon object (as needed by the toolkit)

name of icon.

Examples

## Not run: 
## we can add icon sets, say those of glyphicons.com. Steps are download files, unzip
## then point x to path, y to name. Imagine we download and current directory is
## png directory. (Won't work with tcltk by default as these are png files)
x <- Sys.glob("*.png")
path <- paste(getwd(), x, sep=.Platform$file.sep)
nm <- gsub("\\.png", "", x)
nm <- gsub("-", "_", nm)
nm <- gsub("\\+", "_plus", nm)
addStockIcons(nm, path)

## End(Not run)

Description

helper function to bypass lack of cached value in method call

Usage

call_meth(meth, obj)

Arguments

Value

the method

Note

use as do.call(call_meth, args)

Description

Many arguments were deprecated due to various reasons. This is meant to ease porting of code.

Usage

check_deprecated(deprecated_args = list(), ...)

Arguments

Description

The S3 dispatch assumes naming conventions in the class names. This offers some check.

Usage

check_return_class(obj, ret_class)

Arguments

Value

throws error if a mismatch

Description

Dispose of object, primarily a window though this is modified in GNoteBook and GText.

Usage

dispose(obj, ...)

## S3 method for class 'GComponent'
dispose(obj, ...)

Arguments

Description

Some widgets may be editable. If possible, the setter method can be used to toggle the state. This method indicates the state.

Usage

editable(obj, i)

## Default S3 method:
editable(obj, i)

editable(obj, i) <- value

editable(obj, i) <- value

Arguments

Description

A widget is enabled if it is sensitive to user input

Usage

enabled(obj)

## Default S3 method:
enabled(obj)

enabled(obj) <- value

enabled(obj) <- value

Arguments

Value

logical indicating if widget is enabled

if value is logical and FALSE widget will be insensitive to user input and rendered in a muted state.

Description

Flatten a nested list

Usage

flatten(x)

Arguments

Author(s)

Tommy (http://stackoverflow.com/questions/8139677/how-to-flatten-a-list-to-a-list-without-coercion)

Description

a widget has focus if it will receive input events

For some widgets, this sets user focus (e.g. gedit gets focus for typing). For others, settig the focus calls the raise methods. (for gwindow, it will raise the window)

Usage

focus(obj)

## Default S3 method:
focus(obj)

focus(obj) <- value

focus(obj) <- value

Arguments

Description

The font assignment method is used to change the font of the currently selected text.

Usage

font(obj)

## Default S3 method:
font(obj)

font(obj) <- value

font(obj) <- value

## S3 replacement method for class 'GText'
 font(obj) <- value

Arguments

Description

A action object encapsulates an action (a callback) adding textual and graphic information. Actions may be proxied in buttons, menu bars or tool bars.

Usage

gaction(
  label,
  tooltip = NULL,
  icon = NULL,
  key.accel = NULL,
  handler = NULL,
  action = NULL,
  parent = NULL,
  ...,
  toolkit = guiToolkit()
)

.gaction(
  toolkit,
  label,
  tooltip = NULL,
  icon = NULL,
  key.accel = NULL,
  handler = NULL,
  action = NULL,
  parent = NULL,
  ...
)

Arguments

Value

a gaction instance

Description

Alert dialog to display transient messages

generic for toolkit dispatch

Usage

galert(
  msg,
  title = "message",
  delay = 3,
  parent = NULL,
  ...,
  toolkit = guiToolkit()
)

.galert(toolkit, msg, title = "message", delay = 3, parent = NULL, ...)

Arguments

See Also

gmessage, gconfirm, gbasicdialog, galert

Description

The basic dialog is basically a modal window. To use there is a 3 step process: 1) Create a container by calling this constructor, say dlg; 2) use dlg as a container for your subsequent GUI; 3) set the dialog to be modal by calling visible(dlg). (One can't call visible(dlg) <- TRUE.)

We overrided the basic use of visible for the gbasicdialog container to have it become visible and modal after this call. The better suited call visible(dlg) <- TRUE does not work as wanted, for we want to capture the return value.

dispose method for a basic dialog

Usage

gbasicdialog(
  title = "Dialog",
  parent = NULL,
  do.buttons = TRUE,
  handler = NULL,
  action = NULL,
  ...,
  toolkit = guiToolkit()
)

.gbasicdialog(
  toolkit,
  title = "Dialog",
  parent = NULL,
  do.buttons = TRUE,
  handler = NULL,
  action = NULL,
  ...
)

## S3 method for class 'GBasicDialog'
visible(obj, ...)

## S3 method for class 'GBasicDialog'
dispose(obj, ...)

Arguments

Value

A GBasicDialog instance with a visible method

logical indicating which button was pushed (or TRUE if no buttons present)

See Also

gmessage, gconfirm, gbasicdialog, galert

Examples

## Not run: 
## a modal dialog for editing a data frme 
fix_df <- function(DF, ...) {
  dfname <- deparse(substitute(DF))
  w <- gbasicdialog(..., handler=function(h,...) {
    assign(dfname, df[,], .GlobalEnv)
  })
  g <- ggroup(cont=w, horizontal=FALSE)
  glabel("Edit a data frame", cont=g)
  df <- gdf(DF, cont=g, expand=TRUE)
  size(w) <- c(400, 400)
  out <- visible(w)
}

m <- mtcars[1:3, 1:4]
fix_df(m)

## End(Not run)

Description

The basic button widget is a standard means to provide the user a mechanism to invoke an action. This action may be specified by a handler or by a gaction object. The main property for GButton is the label text. If this text matches a stock icon name and the toolkit supports it, an icon will accompany the button.

The svalue method for a button object refers to its main property, the button label

Usage

gbutton(
  text = "",
  handler = NULL,
  action = NULL,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.gbutton(toolkit, text, handler, action, container, ...)

## S3 method for class 'GButton'
addHandlerChanged(obj, handler, action = NULL, ...)

## S3 method for class 'GButton'
svalue(obj, index = NULL, drop = NULL, ...)

Arguments

Value

a GButton instance. While this object has its own (reference) methods, one primarily interacts with it through S3 methods defined within the package.

Examples

if(interactive()) {

  w <- gwindow("Buttons", visible=FALSE)
  g <- ggroup(cont=w, horizontal=FALSE)

  ## various buttons

  ## with icons
  b1 <- gbutton("open", cont=g)

  ## without icon
  b2 <- gbutton("ouvrir", cont=g)

  ## by an action
  act <- gaction("open", tooltip="open", icon="open", handler=function(...) {})
  b3 <- gbutton(action=act, cont=g)

  ## with a handler
  b4 <- gbutton("click me", cont=g, handler=function(h,...) {
    if(svalue(b2) == "open")
      svalue(b2) <- "ouvrir"
    else
      svalue(b2) <- "open"
  })


  ## handlers can be blocked/unblocked
  b5 <- gbutton("Click me for a message", cont=g)
  id <- addHandlerClicked(b5, function(h,...) print("Ouch"))
  b6 <- gcheckbox("toggle handler message", cont=g, use.togglebutton=TRUE, handler=function(h,...) {
      if (svalue(b6)) {
          blockHandler(b5, id)
      } else {
          unblockHandler(b5, id)
      }
  })
  
  visible(w) <- TRUE
}

Description

The date is the main property of this widget

The svalue method for a calendar object returns the selected date

Usage

gcalendar(
  text = "",
  format = "%Y-%m-%d",
  handler = NULL,
  action = NULL,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.gcalendar(
  toolkit,
  text = "",
  format = "%Y-%m-%d",
  handler = NULL,
  action = NULL,
  container = NULL,
  ...
)

## S3 method for class 'GCalendar'
addHandlerChanged(obj, handler, action = NULL, ...)

## S3 method for class 'GCalendar'
svalue(obj, index = NULL, drop = NULL, ...)

Arguments

Value

Returns an object of class GCalendar for which the following methods are overridden:

1. svalue get the date

2. svalue<- set the date

The change handler is inherited from gedit

If drop=TRUE a character string, else a Date class object.

Description

A checkbox widget is used to toggle the state of a labeled boolean variable. The main property of this widget is that state, not the label. This variable may be proxied in the usual way – with a box that indicates or check if TRUE – or through a toggle button.

The change handler for GCheckbox is called when the value toggles. You can inpsect the current value in the callback to have an action based on the state.

The object state is referred to by svalue as a logical (TRUE for checked). The svalue<- method ensures the value is a logical vector of length 1.

The item to select is referred to by the [ method, with only the first element being used.

Usage

gcheckbox(
  text = "",
  checked = FALSE,
  use.togglebutton = FALSE,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.gcheckbox(
  toolkit,
  text,
  checked = FALSE,
  use.togglebutton = FALSE,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...
)

## S3 method for class 'GCheckbox'
addHandlerChanged(obj, handler, action = NULL, ...)

## S3 replacement method for class 'GCheckbox'
 svalue(obj, index=NULL, ...) <- value

## S3 replacement method for class 'GCheckbox'
 x[i, j, ...] <- value

Arguments

Value

Returns an object of class GCheckbox.

Note

The value is coerced to character, then only first element used for checkbox label

Examples

if(interactive()) {
  w <- gwindow("Selection widgets")
  g <- gvbox(cont=w)

  fl <- gformlayout(cont=g)
  gcheckbox("checkbox", checked=TRUE, cont=fl, label="checkbox")
  gradio(state.name[1:4], selected=2, horizontal=TRUE, cont=fl, label="gradio")
  gcheckboxgroup(state.name[1:4], horizontal=FALSE, cont=fl, label="checkbox group")

  bg <- ggroup(cont=g)
  gbutton("ok", cont=bg, handler=function(h,...) print(sapply(fl$children, svalue)))



}

Description

Change handler for a GCheckboxGroupp is called when any of the checkboxes changes state.

The svalue methods refer to the selected values. By default these are the item values, coerced to characterq. When index=TRUE is specified, then the index is returned as an integer vector. For setting, one may also use a vector of logicals (which is recycled) for the index.

Usage

gcheckboxgroup(
  items,
  checked = FALSE,
  horizontal = FALSE,
  use.table = FALSE,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.gcheckboxgroup(
  toolkit,
  items,
  checked = FALSE,
  horizontal = FALSE,
  use.table = FALSE,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...
)

## S3 method for class 'GCheckboxGroup'
addHandlerChanged(obj, handler, action = NULL, ...)

## S3 method for class 'GCheckboxGroup'
svalue(obj, index = NULL, drop = NULL, ...)

Arguments

Value

Returns an object of class GCheckboxGroup for which the following methods are overridden:

• svalue Return the selected values or an empty character vector. If index=TRUE, returns indices of selected values.

• svalue<- Set the selected values one of three ways: by label name, by a logical variable indicating which are selected (if ambigous, logical wins), if index=TRUE by the indices to select.

• [ returns labels

• [<- set the label values. Should be able to shorten or lengthen list

Examples

if(interactive()) {
  w <- gwindow("Selection widgets")
  g <- gvbox(cont=w)

  fl <- gformlayout(cont=g)
  gcheckbox("checkbox", checked=TRUE, cont=fl, label="checkbox")
  gradio(state.name[1:4], selected=2, horizontal=TRUE, cont=fl, label="gradio")
  gcheckboxgroup(state.name[1:4], horizontal=FALSE, cont=fl, label="checkbox group")

  bg <- ggroup(cont=g)
  gbutton("ok", cont=bg, handler=function(h,...) print(sapply(fl$children, svalue)))



}

Description

A combobox can be either a drop down list (editable=FALSE), or a drop-down list and edit area (a combobox).

Non exported helper function to coerce items into a data frame. First column contains the values, second stock icons, third tooltips

Ensure that value is a data frame. One can pass a vector or a one-column data frame to inidicate the possible values for selection, a second column is used for an icons (if possible), a third for a tooltip (if possible).

Change handler for a non-editabe combobox is called when a new value is selected. For editable comboboxes, the handler is also called when the text entry box is activated.

The svalue method for a combobox object refers to its main property, the selected value. When index=FALSE (or NULL) the value is returned. If index=TRUE the index of the object within the set of items is used.

Usage

gcombobox(
  items,
  selected = 1,
  editable = FALSE,
  coerce.with = NULL,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.gcombobox(
  toolkit,
  items,
  selected = 1,
  editable = FALSE,
  coerce.with = NULL,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...
)

gdroplist(...)

.make_gcombobox_items(value)

## S3 replacement method for class 'GComboBox'
 x[i , j, ...] <- value

## S3 method for class 'GComboBox'
addHandlerChanged(obj, handler, action = NULL, ...)

## S3 method for class 'GComboBox'
svalue(obj, index = NULL, drop = NULL, ...)

Arguments

Value

Returns an object of class GComboBox for which the following methods are overriden:

1. svalue Return selected value by name or (if index=TRUE by index). The latter only if editable=FALSE.

2. svalue<- Set the selected value by value or if index=TRUE by index.

3. [ return items to select from

4. [<- Set items to select from.

Description

Constructor for modal dialog to get confirmation

generic for toolkit dispatch

Usage

gconfirm(
  msg,
  title = "Confirm",
  icon = c("info", "warning", "error", "question"),
  parent = NULL,
  ...,
  toolkit = guiToolkit()
)

.gconfirm(
  toolkit,
  msg,
  title = "Confirm",
  icon = c("info", "warning", "error", "question"),
  parent = NULL,
  ...
)

Arguments

Value

logical inidicating confirmation

See Also

gmessage, gconfirm, gbasicdialog, galert

Description

Used as template for documentation

Usage

gcontainer(container = NULL, ..., toolkit = guiToolkit())

Arguments

Description

Implementation varies wildly, but should provide at minimum functionality of edit.data.frame. A single mouse click on a cell should select that cell, a double click should initiate editing of that cell.

Assign handler to be called when a cell, row or column changes

For gdf svalue refers to the selected values.

visible is used to refer to which rows are being shown.

Usage

gdf(
  items = NULL,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.gdf(
  toolkit,
  items = NULL,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...
)

## S3 method for class 'GDf'
addHandlerChanged(obj, handler, action = NULL, ...)

## S3 method for class 'GDf'
svalue(obj, index = NULL, drop = TRUE, ...)

## S3 replacement method for class 'GDf'
 visible(obj) <- value

Arguments

Details

Contents of the data frame can be accessed via [ and manipulated with [<-.

The save_data reference class method can be called to save the data into a variable with the specified name.

example in inst/examples/ex-gdf.R

Value

An object of class gDf.

Description

A notebook container for many gdf instances

S3 generic whose methods are implemented in the toolkit packages

Usage

gdfnotebook(items = NULL, container = NULL, ..., toolkit = guiToolkit())

.gdfnotebook(toolkit, items, container, ...)

Arguments

Description

The default change handler is called when the return key is pressed. It can be useful to also call a handler when the widget loses focus. For that, the addHandlerBlur method is of use. (This was the default, but is now not, as it was hard to decouple the two when that was desirable.)

The default change handler call is when the user activates the entry by pressing the enter key. Other possible events to consider are covered by: addhandlerBlur (when the widget loses focuses) and addHandlerKeystroke (called after each keystroke). For the latter, if the toolkit supports it, the handler's first argument has a component key passing back the keystroke information.

The svalue method for a edit object refers to its main property, the text in the box.

Usage

gedit(
  text = "",
  width = 25,
  coerce.with = NULL,
  initial.msg = "",
  handler = NULL,
  action = NULL,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.gedit(
  toolkit,
  text = "",
  width = 25,
  coerce.with = NULL,
  initial.msg = "",
  handler = NULL,
  action = NULL,
  container = NULL,
  ...
)

## S3 method for class 'GEdit'
addHandlerChanged(obj, handler, action = NULL, ...)

## S3 method for class 'GEdit'
svalue(obj, index = NULL, drop = NULL, ...)

Arguments

Value

An object of class GEdit. This has sub-classed methods:

1. svalue to retrieve the text

2. svalue<- to set the text

3. [ to get the autocomplete values

4. [<- Character. To set autocomplete values

5. visible<- to specify a character to display instead of text (for passwords)

Description

Like match, but works with a list

Usage

get_index_in_list(lst, ele)

Arguments

Value

returns index of element or integer(0)

Description

Get an object from an environment specified by a string.

Usage

get_object_from_string(value, envir = .GlobalEnv)

Arguments

Value

the object or an error

Description

At times a user may wish to access the underlying toolkit widget. Although this is not cross-platform, one often has access to many more methods of the object, than through those provided by gWidgets.

For GWindow, the block is NULL

Usage

getToolkitWidget(obj)

## Default S3 method:
getToolkitWidget(obj)

getWidget(obj)

## S3 method for class 'GComponent'
getWidget(obj)

getBlock(obj)

## S3 method for class 'GComponent'
getBlock(obj)

## S3 method for class 'GWindow'
getBlock(obj)

getTopLevel(obj)

## S3 method for class 'GComponent'
getTopLevel(obj)

Arguments

Description

Return x unless NULL, NA, length 0, ..., in which case we give default

Usage

getWithDefault(x, default)

Arguments

Value

x or default

Description

For gexpandgroup, the visible assignment method is overridden to change the disclosure state

The change handler for a expandGroup is called when the group changes visibility

Usage

gexpandgroup(
  text = "",
  markup = FALSE,
  horizontal = TRUE,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.gexpandgroup(
  toolkit,
  text = "",
  markup = FALSE,
  horizontal = TRUE,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...
)

## S3 replacement method for class 'GExpandGroup'
 visible(obj) <- value

## S3 method for class 'GExpandGroup'
addHandlerChanged(obj, handler, action = NULL, ...)

Arguments

Value

An object of class GExpandGroup inheriting from GFrame

See Also

ggroup and gframe

Examples

if(interactive()) {
    w <- gwindow("Box containers")
    g <- gvbox(cont=w)                         # ggroup(horizonta=FALSE, ...)
    nb <- gnotebook(cont=g); gbutton("one", label="one", cont=nb)
    gframe("Frame", cont=g)
    pg <- gpanedgroup(cont=g);
    gbutton("one", cont=pg);
    gbutton("two", cont=pg)

    eg <- gexpandgroup(cont=g, horizontal=FALSE);
    glabel("Click above to hide", cont=eg);
    gbutton("one", cont=eg);
    gbutton("two", cont=eg)
}

Description

Basically an entry box instance with a button to initiate gfile.

Usage

gfile(
  text = "",
  type = c("open", "save", "selectdir"),
  initial.filename = NULL,
  initial.dir = getwd(),
  filter = list(),
  multi = FALSE,
  ...,
  toolkit = guiToolkit()
)

.gfile(
  toolkit,
  text = "",
  type = c("open", "save", "selectdir"),
  initial.filename = NULL,
  initial.dir = getwd(),
  filter = list(),
  multi = FALSE,
  ...
)

gfilebrowse(
  text = "Select a file...",
  type = c("open", "save", "selectdir"),
  initial.filename = NULL,
  initial.dir = getwd(),
  filter = list(),
  quote = TRUE,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.gfilebrowse(
  toolkit,
  text = "Select a file...",
  type = c("open", "save", "selectdir"),
  initial.filename = NULL,
  initial.dir = getwd(),
  filter = list(),
  quote = TRUE,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...
)

Arguments

Value

returns filename(s) or character(0) if no selection.

Returns an object of class gFilebrowse. This should inherit the methods of gedit instances.

Description

This widget provides a simple means to subset, or filter, a data frame.

The svalue method for a filter object returns a logical containing which rows are selected. There is no assignment method.

Usage

gfilter(
  DF,
  allow.edit = TRUE,
  initial.vars = NULL,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.gfilter(
  toolkit,
  DF,
  allow.edit = TRUE,
  initial.vars = NULL,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...
)

## S3 method for class 'GFilter'
svalue(obj, index = NULL, drop = NULL, ...)

## S3 method for class 'GFilter'
x[i, j, ..., drop = TRUE]

## Default S3 method:
.gfilter(
  toolkit = guiToolkit(),
  DF,
  allow.edit = TRUE,
  initial.vars = NULL,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...
)

Arguments

Value

returns GFilter object

Examples

## Not run: 
DF <- mtcars[, c("mpg", "cyl", "hp", "am", "wt")]
w <- gwindow("Example of gfilter", visible=FALSE)
pg <- ggroup(container=w)
df <- gtable(DF, container=pg)
a <- gfilter(df, initial.vars=data.frame(names(DF), names(DF),
                   c("single", "multiple", "range", "single", "range"),
                   stringsAsFactors=FALSE),
             allow.edit=TRUE,
             container=pg,
             handler=function(h,...) {
               visible(df) <- h$obj$get_value()
             }
             )
size(w) <- c(600, 600)
visible(w) <- TRUE

## End(Not run)

Description

This convenience container is basically a simpler form of glayout to be used to layout two columns forms with a label on the left. The label can be passed in to the add method of the container as is done with notebook labels

The svalue method for GFormLayout returns a list of values created by calling svalue on each child. The returned list is named by the corresponding labels.

Usage

gformlayout(
  align = c("default", "left", "center"),
  spacing = 5,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.gformlayout(toolkit, align = "left", spacing = 5, container = NULL, ...)

## S3 method for class 'GFormLayout'
svalue(obj, index = NULL, drop = NULL, ...)

Arguments

Examples

## Not run: 
w <- gwindow("gformlayout", visible=FALSE)
g <- gvbox(container=w)

flyt <- gformlayout(container=g)
gedit("", label="Name:", container=flyt)
gedit("", label="Rank:", container=flyt)
gedit("", label="Serial No.:", container=flyt)

b <- gbutton("Show me", container=g, handler=function(h,...) {
print(svalue(flyt))
})

addSpring(g) ## better with Qt, else flyt expands to fill.
visible(w) <- TRUE

## End(Not run)

Description

The framed box container inherits from ggroup. The main addition is a label, which is accessed via the name method.

Usage

gframe(
  text = "",
  markup = FALSE,
  pos = 0,
  horizontal = TRUE,
  spacing = 5,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.gframe(
  toolkit,
  text = "",
  markup = FALSE,
  pos = 0,
  horizontal = TRUE,
  spacing = 5,
  container = NULL,
  ...
)

Arguments

Note

to include a scrollwindow, place a ggroup within this window.

See Also

ggroup and gexpandgroup

Examples

## Not run: 
w <- gwindow("gformlayout", visible=FALSE)
f <- gframe("frame", horizontal=FALSE, container=w)
glabel("Lorem ipsum dolor sit amet, \nconsectetur adipiscing elit.", container=f)
gbutton("change name", container=f, handler=function(h,...) {
  names(f) <- "new name"
})
visible(w) <- TRUE

## End(Not run)

Description

Some toolkits provide an embeddable graphics device. When this is the case, this widget provides same.

Usage

ggraphics(
  width = dpi * 6,
  height = dpi * 6,
  dpi = 75,
  ps = 12,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.ggraphics(
  toolkit,
  width = dpi * 6,
  height = dpi * 6,
  dpi = 75,
  ps = 12,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...
)

Arguments

Examples

## Not run: 
## This shows how to use the device within a notebook

w <- gwindow("notebook example")
nb <- gnotebook(cont=w)

devs <- lapply(1:5, function(i) ggraphics(cont=nb, label=as.character(i)))

addHandlerChanged(nb, handler=function(h,...) {
  ## Tricky part is svalue(h$obj) is not the new page number -- but old
  ## so we use the pageno component here
    gg <- h$obj[h$pageno]
    visible(gg) <- TRUE
})



## End(Not run)

Description

A notebook widget holding plot devices

S3 generic whose methods are implemented in the toolkit packages

toolkit implementation

Usage

ggraphicsnotebook(
  width = dpi * 6,
  height = dpi * 6,
  dpi = 75,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.ggraphicsnotebook(toolkit, width, height, dpi, container, ...)

## Default S3 method:
.ggraphicsnotebook(toolkit, width, height, dpi, container, ...)

Arguments

Description

The svalue method refers to the main property of the box container, its spacing. There are generally two types of spacing: padding around border of the box and spacing between each child that is packed in. The spacing here is the between-child-component spacing. The reference class method set_borderwidth can be used for the other.

Avoids need to type horizontal=FALSE

Usage

ggroup(
  horizontal = TRUE,
  spacing = 5,
  use.scrollwindow = FALSE,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.ggroup(
  toolkit,
  horizontal = TRUE,
  spacing = 5,
  use.scrollwindow = FALSE,
  container = NULL,
  ...
)

## S3 replacement method for class 'GGroup'
 svalue(obj, index=TRUE, ...) <- value

gvbox(
  spacing = 5,
  use.scrollwindow = FALSE,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

Arguments

Details

Child components are typically added to a box container through the child components constructor. The argument expand, fill, and anchor determine how the child is positioned within the container.

Value

a GGroup instance.

a GGroup instance with vertical packing.

See Also

gframe and gexpandgroup

Examples

if(interactive()) {
  w <- gwindow("Box containers")
  g <- gvbox(cont=w)                         # ggroup(horizonta=FALSE, ...)
  nb <- gnotebook(cont=g); gbutton("one", label="one", cont=nb)
  gframe("Frame", cont=g)
  pg <- gpanedgroup(cont=g); gbutton("one", cont=pg); gbutton("two", cont=pg)
}

Description

This widget, when supported by the toolkit (not gWidgets2RGtk2 and gWidgets2tcltk) provides a simple means to display HTML formatted text.

Use to update displayed content. Value is HTML fragment or url

Usage

ghtml(x, container = NULL, ..., toolkit = guiToolkit())

.ghtml(toolkit, x, container = NULL, ...)

## S3 replacement method for class 'GHtml'
 svalue(obj, index=TRUE, ...) <- value

Arguments

Value

a GHtml instance.

Author(s)

john verzani

Description

A widget for displaying an image file

generic for toolkit dispatch

Usage

gimage(
  filename = "",
  dirname = "",
  stock.id = NULL,
  size = "",
  handler = NULL,
  action = NULL,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.gimage(
  toolkit,
  filename = "",
  dirname = "",
  stock.id = NULL,
  size = "",
  handler = NULL,
  action = NULL,
  container = NULL,
  ...
)

Arguments

Description

Constructor for modal dialog to collect a line of text

generic for toolkit dispatch

Usage

ginput(
  msg,
  text = "",
  title = "Input",
  icon = c("info", "warning", "error", "question"),
  parent = NULL,
  ...,
  toolkit = guiToolkit()
)

.ginput(
  toolkit,
  msg,
  text = "",
  title = "Input",
  icon = c("info", "warning", "error", "question"),
  parent = NULL,
  ...
)

Arguments

Value

value typed into box or character(0)

See Also

gmessage, gconfirm, gbasicdialog, galert

Description

The basic label widget allows one to label areas of a GUI using text. The most common use would be to label fields in a form. For gWidgets2 labels may be editable or responsive to mouse clicks, although it is the author's experience that such uses are not expected by the end user.

The svalue methods refer to the main property of the label, its text.

Usage

glabel(
  text = "",
  markup = FALSE,
  editable = FALSE,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.glabel(
  toolkit,
  text,
  markup = FALSE,
  editable = FALSE,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...
)

## S3 replacement method for class 'GLabel'
 svalue(obj, index=TRUE, ...) <- value

Arguments

Value

a GLabel instance. While this object has its own (reference) methods, one primarily interacts with it through S3 methods defined within the package.

Author(s)

john verzani

Examples

## Not run: 
w <- gwindow("gformlayout", visible=FALSE)
g <- gvbox(container=w)
g$set_borderwidth(10)

l1 <- glabel("static label", container=g)
l2 <- glabel("bold label", container=g)
font(l2) <- list(weight="bold")
l3 <- glabel("editable label. Click me", editable=TRUE, container=g)

visible(w) <- TRUE


## End(Not run)

Description

The grid layout container uses matrix notation to position its child components. This allows one to align widgets both horizontally and vertically, as desired. There is some support for matrix methods, such as dim and [ to reference the child objects.

The [ method for the grid layout allows one to reference the child objects by index. The return value is non standard. It may be the item, a list (if one dimensonaL) or an array. The list format is convenient to refer to all the child objects in a column.

The matrix notation allows for spanning of multiple rows and or columns, but no holes. The ... argument is used to pass in values for expand, fill, anchor (see the add method of ggroup) for their meaning).

Usage

glayout(
  homogeneous = FALSE,
  spacing = 10,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.glayout(toolkit, homogeneous = FALSE, spacing = 10, container = NULL, ...)

## S3 method for class 'GLayout'
x[i, j, ..., drop = TRUE]

## S3 replacement method for class 'GLayout'
 x[i ,j, ...] <- value

Arguments

See Also

gformlayout for a more convenient means to layout forms.

Examples

## Not run: 

w <- gwindow("glayout example", visible=FALSE)
g <- gvbox(container=w)
lyt <- glayout(container=g)
lyt[1,1] <- "a label"
lyt[1,2] <- gedit("A widget", container=lyt)
lyt[2, 1:2] <- gcombobox(state.name, cont=lyt)
g1 <- ggroup(container=g)
addSpring(g1)
gbutton("values", container=g1, handler=function(h, ...) {
  print(sapply(lyt[,2], svalue))
})
visible(w) <- TRUE


## End(Not run)

Description

A menu may be viewed as a heirarchical collection of buttons, each invoked by clicking on the button. These buttons are exposed through submenus. More generally, a widget may replace the button. This widget intends to support buttons (gactions), separators (gseparator), radio button (gradio) and checkbutton (gcheckbox), but this may be toolkit independent. When using a radio button or checkbox, one should pass in a parent argument to the constructor – not a container.

For a menubar, svalue returns the list of action items etc. that defined the menubar. This can be useful to access the underlying item being proxied. (For gaction items the enabled<- method may be used on the item, but this may not extend to gradio and gcheckbox items)

for a menubar, svalue<- replaces the menubar items with new ones specified by value.

Usage

gmenu(menu.list, popup = FALSE, container = NULL, ..., toolkit = guiToolkit())

.gmenu(toolkit, menu.list = list(), popup = FALSE, container = NULL, ...)

## S3 method for class 'GMenuBar'
add(obj, child, expand = FALSE, fill = NULL, anchor = NULL, ...)

## S3 method for class 'GMenuBar'
svalue(obj, index = NULL, drop = NULL, ...)

## S3 replacement method for class 'GMenuBar'
 svalue(obj, index=NULL, ...) <- value

Arguments

Description

Constructor for modal message dialog

generic for toolkit dispatch

Usage

gmessage(
  msg,
  title = "message",
  icon = c("info", "warning", "error", "question"),
  parent = NULL,
  ...,
  toolkit = guiToolkit()
)

.gmessage(toolkit, msg, title = "message", icon = "", parent = NULL, ...)

Arguments

See Also

gmessage, gconfirm, gbasicdialog, galert

Description

The tabbed notebook container allows one to hold many different pages with a mechanism – tabs – to switch between them. In gWidgets2 new pages are added through the add method. This is usually called implicitly in the child object's constructor. One passes in the tab label through the extra label argument. Labels may be subsequently changed through names<-.

Children added to notebooks need a label, a position and optionally a close button (if supported). The arguments expand, fill, anchor are not specified – children expand and fill the allocated space.

Dispose deletes the current page, not the entire notebook object. To delete a specific page, a combination of svalue<- and dispose may be used.

The names of a notebook are the page tab labels. These may be retrieved and set through the names method.

The notebook object contains pages referenced by index. This allows access to underlying page.

The change handler for the notebook is called when the page changes. Tthe new page number is passed back in the page.no component of 'h', which in some cases may differ from the value given by svalue within the handler call.

Dispose deletes the current page, not the entire notebook object. To delete a specific page, a combination of svalue<- and dispose may be used.

Usage

gnotebook(tab.pos = 3, container = NULL, ..., toolkit = guiToolkit())

.gnotebook(toolkit, tab.pos = 3, container = NULL, ...)

## S3 method for class 'GNotebook'
add(obj, child, expand, fill, anchor, ...)

## S3 method for class 'GNotebook'
dispose(obj, ...)

## S3 method for class 'GNotebook'
names(x)

## S3 replacement method for class 'GNotebook'
 svalue(obj, index=TRUE, ...) <- value

## S3 method for class 'GNotebook'
x[i, j, ..., drop = TRUE]

## S3 method for class 'GNotebook'
addHandlerChanged(obj, handler, action = NULL, ...)

## S3 method for class 'GStackWidget'
dispose(obj, ...)

Arguments

Value

none. called for its side effect.

Note

In gWidgets2 the button arguments of the gWidgets constructor are removed. One passes the close button request to the add method.

To keep the signature the same as the generic, several arguments are passed in via ...:

label

A character. Label text for tab

i

An integer in 0 to length(obj) indicating the position to insert child. The new page is inserted to the right of page number i. When i=0, the page appears at the front, when i is not specified it appears at the end.

close.button

A logical. If TRUE – and the toolkit supports it – the page tab will include a close button.

See Also

gstackwidget for a similar widget without tabs.

Examples

## Not run: 

w <- gwindow("notebook example", visible=FALSE)
nb <- gnotebook(container=w)
gbutton("Page one", label="tab 1", container=nb) ## note label argument
gbutton("Page two", label="tab 2", container=nb)
svalue(nb) <- 1
addHandlerChanged(nb, handler=function(h,...) {
  message(sprintf("On page %s", h$page.no)) ## svalue(h$obj) not always right
})
svalue(nb) <- 2 ## or use "Page two"
dispose(nb)
length(nb)


## End(Not run)

Description

A container for holding two child widgets where the space allocated to each can be manipulated by the user with a pane between the widgets, or programatticaly via svalue<-. The value specified to svalue<- can be a number in $[0,1]$, in which case it is a proportion or an integer, in which case it is a pixel size (from the left or the top). The ambiguous case 1 or 1L is determined by class. The value of svalue is in proportion units.

Usage

gpanedgroup(horizontal = TRUE, container = NULL, ..., toolkit = guiToolkit())

.gpanedgroup(toolkit, horizontal = TRUE, container = NULL, ...)

Arguments

Details

Child widgets are added in the usual way, typically through the container argument of a constructor. Only two children may be added. Children expand and fill the allocated space.

Note

Setting the size is often only possible after the container has been realized on the screen. In the example, this call of svalue<- is done after the parent window is made visible for this reason. There were arguments to specify the children at construction, but these have been removed.

Examples

## Not run: 
w <- gwindow("gpanedgroup", visible=FALSE)
pg <- gpanedgroup(cont=w)
gbutton("left", cont=pg)
gbutton("right", cont=pg)

visible(w) <- TRUE
svalue(pg) <- 0.33

## End(Not run)

Description

Basic progress bar widget

S3 generic whose methods are implemented in the toolkit packages

Usage

gprogressbar(value = 10, container = NULL, ..., toolkit = guiToolkit())

.gprogressbar(toolkit, value, container, ...)

Arguments

Value

a GButton instance. While this object has its own (reference) methods, one primarily interacts with it through S3 methods defined within the package.

Examples

## Not run: 
w <- gwindow("progress bar example")
pb <- gprogressbar(cont=w)
for(i in 10:100) {Sys.sleep(.1); svalue(pb) <- i}

## End(Not run)

Description

A radio button group allows a user to select one from many items. In gWidgets2 the radio button widget shows 2 or more items. The items are coerced to characters, usually by the underlying toolkit. Use the coerce_with property to set a function, such as as.numeric, to coerce the return value during the svalue code. The items are referred to with the [ method, the selected one with svalue.

The svalue method returns the radio button label or its index if index=TRUE. Labels are coerced to character by many of the toolkits. To be sure to return a numeric value, one can assign to the coerce_with property, e.g., obj$coerce_with <- as.numeric. For all widgets, if a function is specified to coerce_with it will be called on the value returned by svalue.

For a radio button group, for svalue the value can be referred to by index or label.

Check for repeated items before passing on to set_items

Usage

gradio(
  items,
  selected = 1,
  horizontal = FALSE,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...,
  toolkit = guiToolkit()
)

.gradio(
  toolkit,
  items,
  selected = 1,
  horizontal = FALSE,
  handler = NULL,
  action = NULL,
  container = NULL,
  ...
)

## S3 method for class 'GRadio'
svalue(obj, index = NULL, drop = TRUE, ...)

## S3 replacement method for class 'GRadio'
 svalue(obj,index=NULL,drop=TRUE,...) <- value

## S3 replacement method for class 'GRadio'
 x[i, j, ...] <- value

Arguments

Examples

if(interactive()) {
  w <- gwindow("Selection widgets")
  g <- gvbox(cont=w)

  fl <- gformlayout(cont=g)
  gcheckbox("checkbox", checked=TRUE, cont=fl, label="checkbox")
  gradio(state.name[1:4], selected=2, horizontal=TRUE, cont=fl, label="gradio")
  gcheckboxgroup(state.name[1:4], horizontal=FALSE, cont=fl, label="checkbox group")

  bg <- ggroup(cont=g)
  gbutton("ok", cont=bg, handler=function(h,...) print(sapply(fl$children, svalue)))



}

Description

The gseparator widget provides a horizontal or vertical line to visually divide child components of its parent container. In addition to box containers this can be used within toolbars (where one uses parent and not container).

Usage

gseparator(horizontal = TRUE, container = NULL, ..., toolkit = guiToolkit())

.gseparator(toolkit, horizontal = TRUE, container = NULL, ...)

Arguments

Examples

## Not run: 

w <- gwindow("Within page", visible=FALSE)
g <- gvbox(container=w)
glabel("Lorem ipsum ...", cont=g)
gseparator(cont=g)
bg <- ggroup(cont=g); addSpring(bg)
gbutton("dismiss", container=bg, handler=function(h,...) dispose(w))
visible(w) <- TRUE

w1 <- gwindow("within layout", visible=FALSE)
lyt <- glayout(container=w1)
lyt[1,1] <- "label"
lyt[2,1:2] <- gseparator(container=lyt)
lyt[3,2] <- "asdf"
visible(w1) <- TRUE

w2 <- gwindow("Within toolbar", visible=FALSE)
l <- list(file=gaction("File", parent=w2),
          sep=gseparator(parent=w2),
          quit=gaction("quit", parent=w2))
gtoolbar(l, cont=w2)
glabel("Lorem ipsum ...", container=w2)
visible(w2) <- TRUE

## End(Not run)