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:
labelto assign the label. This may be a text string or a gWidget
override.closebuttonTo 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.attrcan be used to specify font attributes for the text
a logical indicating if a newline should be added after the text
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.
gWidgets-handlers for methods related to handlers.