gWidgets (version 0.0-54.2)

ggroup: Box containers for packing in subsequent widgets

Description

Various box containers useful for laying out GUI controls. These containers pack in child widgets from left to right or top to bottom. A few arguments can be used to adjust the sizing and positioning.

Usage

ggroup(horizontal = TRUE, spacing = 5,  use.scrollwindow = FALSE, 
container = NULL, ..., toolkit = guiToolkit())
gframe(text = "", markup = FALSE, pos = 0, horizontal=TRUE, container = NULL, 
    ..., toolkit = guiToolkit()) 
gexpandgroup(text = "", markup = FALSE, horizontal=TRUE, handler = NULL, 
action = NULL, 
    container = NULL, ..., toolkit = guiToolkit())

Arguments

horizontal

Specifies if widgets are packed in left to right or top to bottom (FALSE)

spacing

Space in pixels around each widget. Can be changed with svalue

text

Text for label

markup

Optional markup. (See glabel for details.)

pos

Where to place label: 0 is to left, 1 to right, interpolates.

handler

Called when expand arrow is clicked

action

Passed to handler

use.scrollwindow

If TRUE then group is placed in a scrollwindow allowing panning with mouse.

container

Optional container to attach widget to. Not optional for gWidgetstcltk, or gWidgetsRwxwidgets

…

Passed to the add method of the container

toolkit

Which GUI toolkit to use

Details

A ggroup is the primary container for packing in subsequent widgets, either from left to right or top to bottom. Widgets are packed in using the add method and can be removed with the delete method.

The gframe container adds a decorative border and optional label to the box container.

The gexpandgroup containers has an optional label and a trigger to click on which toggles the display of the the child widgets. By default, the child widgets are not shown. Using the visible<- method to adjust.

The containers pack in child widgets from either left to right (when horizontal=TRUE) or from top to bottom (when horizontal=FALSE).

Child widgets are added to box containers through their add method or through the containers use as the parent container when a widget is constructed. This is done by using the container argument of the widget. The container argument is not optional for gWidgetstcltk. It is suggested that it always be included for portability. When it is not included, widgets are added to the new group object through its add method. Otherwise, when a widget is created, the group is specified as the container and the add method is then called implicitly, with the constructor's ... argument used to pass arguments to add.

When the parent allocates space to a child widget it be possible to allocate more space than is requested by the child widget. The child may then be positioned in the available space by specifying the anchor=c(a,b) argument to add where a and b are values in -1,0,1 and specify the position using Cartesian coordinates.

If the argument expand=TRUE to add is given, then the space available to the child expands. The child widget can be instructed to grow to fill the space. The add method's argument fill, with values "both", "x", "y" or "", instructs the child as to which direction to grow in. (The "" value says none.)

The implementation of expand, anchor, fill varies with the underlying toolkit. The basic language comes from tcltk and an attempt -- not entirely successful -- is made to implement it in the gWidgetsRGtk2 and gWidgetsQt packages.

A child component may be deleted using delete(parent, child). TYpically the child may be replaced in the GUI, using add.

The spacing argument determines the number of pixels of padding between each widget when packed in. This can be set when the group is constructed, or later using svalue<-.

The argument use.scrollwindow = TRUE will add scrollbars around the box container. When the child components require more size than is given to the container, the scroll bars allow one to position the viewable area over the child of interest. Again, not all toolkits do this equally well.

To put space between two adjoining widgets, the addSpace(obj, value, ...) method may be used where value is the number of pixels of padding between the just packed widget, and the next one to be packed.

The addSpring(obj,...) method will push the just packed widget and the next-to-be packed widget as far apart as possible.

For ggroup, in gWidgetsRGtk2 a few arguments add to the container. The argument raise.on.dragmotion = TRUE will cause the group to jump to the foreground when a drag action crosses it. For gframe and gexpandgroup the label name can be retrieved or adjusted with the names method.

For gframe and gexpandgroup the label can be adjusted through the names<- method.

For gexpandgroup the visible method can be used to toggle the display programmatically.

See Also

For top-level containers gwindow, for containers to display more than one child widget see gpanedgroup, gnotebook, glayout

Examples

# NOT RUN {
  ## basic group 
  group <- ggroup(horizontal=FALSE, container=gwindow())
  l <- glabel("widget 1")  ## not in gWidgetstcltk -- needs a container
  add(group, l)
  glabel("widget 2", container = group) ## style for all toolkits

  ## nested groups
  group <- ggroup(horizontal=FALSE, container=gwindow())
  innergroup <- ggroup(container = group)
  gtext("Text area", container=group)
  gbutton("button 1", container = innergroup)
  gbutton("button 2", container = innergroup)

  ## expand argument
  group <- ggroup(horizontal=FALSE, container=gwindow())
  gbutton("no expand", container=group)
  gbutton("expand=TRUE", container=group, expand=TRUE)

  ## anchor argument
  w <- gwindow("Anchor")
  size(w) <- c(500,500)
  group <- ggroup(container=w)
  glabel("upper left", container=group, anchor=c(-1,1))
  glabel("lower right", container=group, anchor=c(1,-1))

  ## add spring
  group <- ggroup(container=gwindow("menubar-like example"))
  gbutton("File",handler=function(h,...) print("file"), container=group)
  gbutton("Edit",handler=function(h,...) print("edit"), container=group)
  addSpring(group)				   
  gbutton("Help",handler=function(h,...) print("help"), container=group)


  ## delete and add
  w <- gwindow("Delete and add", visible=FALSE)
  g <- ggroup(container=w)
  b <- gcheckbox("hide", checked=FALSE, container=g)
  l <- gedit("click checkbox to hide me", container=g)
  addHandlerClicked(b, handler=function(h,...) {
     if(svalue(b))
       delete(g, l)
     else
       add(g, l)
  })
  visible(w) <- TRUE
# }