gWidgets-methods: Methods for gWidgets instances
In gWidgets: gWidgets API for Building Toolkit-Independent, Interactive GUIs

Methods introduced by the gWidgets API.

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.

See package vignette for more examples

gWidgets-handlers for methods related to handlers.

gWidgets documentation built on April 29, 2020, 9:37 a.m.