R: Methods for gWidgets instances

gWidgets-methods {gWidgets} | R Documentation

## Methods for gWidgets instances

### Description

Methods introduced by the gWidgets API.

### Details

The base class for this gWidgets implentation are `gWidget` and its subclass `gComponent` and `gContainer`. However, it is expected that the toolkit implementations have several classes of their own. The following methods defined in gWidgets simply dispatch to a similarly named widget in the toolkit. For instance, the method svalue is defined like

`svalue(obj,...) <- .svalue(obj@widget, obj@toolkit, ...)` where `.svalue()` and `obj@widget` are in toolkit, and `obj@toolkit` is used for dispatching in the appropriate toolkit.

The gComponent methods are:

`svalue(obj, index=NULL, drop=NULL, ...)`:

  This method returns the "selected" value in a widget. Selection varies from widget to widget, but should generally is what can be added to the widget by mouse click or typing. For some widgets, the extra argument `index=TRUE` will return the index of the selected value, not the value. For some widget, the argument `drop` is given to either prevent or encourage dropping of information.

`svalue<-(obj, index=NULL, ... ,value)`:

  This method is used to set the selected value in a widget programaticaly. The `index` argument is used when the value is set by index.

`[(x,i,j,...,drop=TRUE)]`:

  For widgets where selection is a choice from a collection of items, the `svalue` method refers to the choice and the square bracket notation refers to the items. For instance, in a radio button (`gradio`) the svalue method returns the selected value, the `"["` method refers to the vector of possible values. Whereas in a notebook (`gnotebook`), the `svalue` method refers to the currently opened page and the `"["` refers to all the pages.

`"[<-"(x, i, j, ..., value)` :

  In those cases where it makes sense assignment to pieces of the widget can be made with the square bracket notation. For instance, for the radio widget, this can be used to change the labels.

`size(obj, ...)` or `size<-(obj, ..., value)`:

  Returns or sets the size of the object. For setting the size, the value is given in terms of width and height of widget in pixels.

`visible(obj ...)` or `visible<-(obj,..., value)`:

  Used to check if widget is visible or not. When setting the visibility, `value` should be a logical. "Visibility" differs from widget to widget. For `gwindow`, like most other widgets, it refers to whether the base container is shown or not. For the dataframe-like widgets `gdf` and `gtable` visibility refers to which rows are shown. For `gexpandgroup` it sets whether the container displays its children or not.

`isExtant(obj ...)`

  Used to check if a gwindow object is extant (not been destroyed). An R object can point to a window that can no longer be shown, as it may have been closed by the window manager.

`enabled(obj,...)` or `enabled<-(obj,..., value)`

  When a widget is disabled, the toolkit makes it unresponsive to user input and changes the color of it, usually by graying it out, to indicate it is disabled. This method is used to change the state.

`editable(obj,...)` or `editable<-(obj,..., value)`

  For some widgets, e.g. `gedit` one may wish to query or change whether the area could be edited.

`focus(obj,...)` or `focus<-(obj,...,value)`:

  method to check if a widget has focus (for keyboard input), or to force focus on a widget.

`tooltip<-(obj,value)`

  Add a tooltip to the widget. Tooltips are toolkit, OS, and event loop dependent.

`defaultWidget(obj,...)` or `defaultWidget<-(obj,...,value)`

  Sets the widget to be activated when the parent window has focus and the enter key is pressed.

`font(obj, ...)` or `font<-(obj,...,value)`:

  Can be used to check or set font attributes in a widget. In gWidgetsRGtk, the font attributes are given as a named vector. The available names are

  `family` with a value of "normal","sans","serif",or "monospace"; `style` with a value of "normal","oblique", or "italic";

  `weight` with a value of "ultra-light","light","normal","bold","ultra-bold", or "heavy";

  `size` with a value of "xx-small", "x-small", "small", "medium", "large","x-large", and "xx-large". In some tollkits this can also be an integer, as in 16 for 16point font.

  and `color` which for gWidgetsRGtk is any of the values returned by `colors`. [Prior to version 0.0-22 the weight and style were switched. Old code needs to be changed.]

  For gWidgetstcltk the above should work as well.

`undo(obj, ...)` or `redo(obj,...`:

  For toolkits that support undo/redo operations. (Qt and the `gtext` and `gedit` widgets.)

`tag(obj,i, drop=TRUE, ...)` or `tag<-(obj,i, replace=TRUE, ...,value)`:

  These functions work like the `attr` function – they set values within an object. In RGtk, these are carried with the pointer which is passed into functions – not a copy. This allows values to be set without worrying about the scope of the assignment.

  When setting a tag, the argument `replace` can be set to `FALSE` so that the value appends.

  The tags are stored internally in a list. Calling `tag(obj)` will return this list.

`id(obj,...)` or `id<-(obj,..., value)`:

  An id is a name for a widget. This is primarily used internally with the spread-sheet like widgets so that columns can have values – the data in the column, and an id – the column name. Objects can be given an id like a name. For non-widget items, the id is an attribute.

`update(object,...)`:

  Some classes use this method to update the state of the widget

`add(obj, value, ...)`:

  This widget is used to add something to a widget. What "adding" means varies from widget to widget.

  For this method, there are several different arguments that can be passed in via the `"..."` argument. When the API is cleaned up this should change.

  For the containers (`gwindow`, `ggroup`, ...) adding adds a widget to be packed in. For the parent container produced by `gwindow` only one item can be added. For groups, this is not the case.

  For `ggroup`, `gframe` and `gexpandgroup` the extra argument `expand=TRUE` will cause the widget to take up all possible space within the container. The widget can grow to fill the space. The argument `fill`, with values `"x"`, `"y"`, or `"both"` indicate which direction the widget should grow. The argument `anchor` takes a value with x-y coordinates in -1,0,1 by -1,0,1) indicating where to anchor the widget if it does not grow in both directions.

  For the components, `add` has different meanings. For notebooks (`gnotebook`, ...) `add` is used to add pages. In this case the extra arguments are:

  `label`

    to assign the label. This may be a text string or a gWidget

  `override.closebutton`

    To override the placing of a close button

  For the text buffer widget (`gtext`) `insert` (origally called `add` which still works but is deprecated) is used to insert text into the buffer. In this case, extra arguments are available:

  `font.attr`

    can be used to specify font attributes for the text

  do.newline

    a logical indicating if a newline should be added after the text

  where

    An indicator of where to place the text: "beginning", "ending", or "at.cursor", although the latter may not be implemented.

`delete(obj, widget,...)`:

  For gContainers this method is used to delete a widget that has been added with `add`. In RGtk, the widget is actually detached and can be added at a later time. Any handler assigned by `addhandlerunrealize` is called when the widget is detached

  For notebooks, the `delete` method removes a page in the notebook.

`dispose(obj,...)`:

  This method is used to remove an object.

  For top-level windows it destroys the window.

  For notebooks, it removes the current page.

  In RGtk2, for other objects it will destroy the top-level window.

`addSpace(obj, value, horizontal=TRUE,...)`:

  Used to add space between widgets in a container

`addSpring(obj, ...)`:

  When packing widgets into a group the widget abut each other filling in from left to right or top to bottom. This puts a "spring" between two widgets forcing the ones to the right of (or below) the spring to be pushed as far as possible to the right (or bottom).

To access the underlying toolkits the `getToolkitWidget` will return the main widget associated with a component. The `$` method can be used to dispatch to an underlying method call in the toolkit. The `[[` and `[[<-` method can be used to inspect and set properties of the underlying object.

### Note

See package vignette for more examples

### See Also

`gWidgets-handlers` for methods related to handlers.

[Package gWidgets version 0.0-54 Index]