gbutton {gWidgets2} | R Documentation

## Basic button widget

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

S3 generic whose methods are implemented in the toolkit packages

Change handler for a button is called when a button is activated (e.g., a mouse click)

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

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

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

[Package gWidgets2 version 1.0-8 Index]