gbutton: Basic button widget
In gWidgets2: Rewrite of gWidgets API for Simplified GUI Construction

Description Usage Arguments Value Examples

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

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, ...)

`text`	label text. If text matches a stock icon name, that is used as well
`handler`	A handler assigned to the default change signal. Handlers are called when some event triggers a widget to emit a signal. For each widget some default signal is assumed, and handlers may be assigned to that through `addHandlerChanged` or at construction time. Handlers are functions whose first argument, `h` in the documentation, is a list with atleast two components `obj`, referring to the object emitting the signal and `action`, which passes in user-specified data to parameterize the function call. Handlers may also be added via `addHandlerXXX` methods for the widgets, where `XXX` indicates the signal, with a default signal mapped to `addHandlerChanged` (cf. `addHandler` for a listing). These methods pass back a handler ID that can be used with `blockHandler` and `unblockHandler` to suppress temporarily the calling of the handler.
`action`	User supplied data passed to the handler when it is called
`container`	A parent container. When a widget is created it can be incorporated into the widget heirarchy by passing in a parent container at construction time. (For some toolkits this is not optional, e.g. gWidgets2tcltk or gWidgets2WWW2.)
`...`	These values are passed to the `add` method of the parent container. Examples of values are `expand`, `fill`, and `anchor`, although they're not always supported by a given widget. For more details see add. Occasionally the variable arguments feature has been used to sneak in hidden arguments to toolkit implementations. For example, when using a widget as a menubar object one can specify a parent argument to pass in parent information, similar to how the argument is used with gaction and the dialogs.
`toolkit`	Each widget constructor is passed in the toolkit it will use. This is typically done using the default, which will lookup the toolkit through `guiToolkit`.
`obj`	object receiving event and emitting a signal to the handler
`index`	NULL or logical. If `TRUE` and widget supports it an index, instead of a value will be returned.
`drop`	NULL or logical. If widget supports it, drop will work as it does in a data frame or perhaps someother means.

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

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
}