Create a dialog

DESCRIPTION:

Creates a dialog window in the dialog handling system program and returns an S-PLUS object that can be used to refer to that dialog.

Note: This function is deprecated. For more information, see .

USAGE:

dialog.create(values=list(), labels=names(values), 
              widgets="", options="", 
              xnames=labels, xdialog="", 
              buttons=c("OK", "Cancel"), title="S-PLUS Dialog") 

REQUIRED ARGUMENTS:

values
a list where each component forms a description of a widget to be created in the new dialog.

OPTIONAL ARGUMENTS:

labels
a character vector of up to length(values) elements specifying the labels for each widget. If specified as a non-empty string, a label string appears before the corresponding widget in the resulting dialog. This vector will be padded with empty strings, if necessary, to extend it.
widgets
a character vector of up to length(values) elements specifying the type of widget to be used for each component of values. If specified as an empty string, the widget type will be determined based on the type of the corresponding values component. A non-empty string in widgets can be used to override the default specification. This vector will be padded with empty strings, if necessary, to extend it. Currently, legitimate widget types are "textfield", "radiobox", "check", "pulldown", "list", and "slider". Refer to the DETAILS section that follows and the options description for more information about the individual widget types.

Factors and character vectors with more than one element use "radiobox" by default. They can also use "list", "pulldown", or "textfield".

Logical vectors use "check" by default. They can also use "textfield".

Integer vectors with more than one element use "slider" by default. The range of the data (as determined by the pretty function) will determine the default "min" and "max" values. They can also use "textfield".

Other types of values components use "textfield" by default.
options
a character vector of up to length(values) elements specifying the widget-specific options to be used. This vector will be padded with empty strings, if necessary, to extend it. Each string is composed of a series of blank separated tokens that are used in the creation of the corresponding widget.

The "slider" widget type accepts the options "horizontal" and "vertical" to control the orientation of the slider. It also accepts "showvalue" and "noshowvalue" to control the display of the current numerical value of the slider along with the slider. The options "min" and "max" accept integer arguments specifying the end points for the slider. Default values are determined using the pretty function. This widget type also supports a "scale" option. The "scale" option specifies the power of 10 by which to divide the integer values for display purposes on the slider. For example, an option string of "min 0 max 100 scale 1" will display as a slider ranging from "0.0" to "10.0", even though the numeric values are still integers in the range 0 to 100.

The "radiobox" widget type accepts the option "width" to specify the number of columns of buttons in the button area of the widget. It expects a single integer argument as the next token in the option string.

The "list" widget type accepts the option "height" to specify the number of list items that should be visible at once. It expects a single integer argument as the next token in the option string.
xnames
a character vector of up to length(values) elements specifying the X11 widget names to use for each widget. These names locate resources in the X resource database for the corresponding widget. The names may be modified to produce usable resource names if they contain certain characters (e.g. "."). This vector will be padded with empty strings, if necessary, to extend it. An empty string has the effect of having the dialog handling system generate an arbitrary name.
xdialog
a character string giving the X11 widget name to use for the top-level window for the dialog. An empty string causes the dialog handling system to generate its own name. Using this can be useful if X resources need to be overridden for specific dialogs. See the examples for a use of this.
buttons
character vector of labels for buttons to be created for the bottom of the dialog window. The buttons trigger actions from the dialog. The dialog.getbutton function returns the label string for the pressed button.
title
character string specifying the title of the dialog window. Most window managers show this string in the title bar of the dialog window.

VALUE:

Returns an object that can be used by the other dialog handling routines to refer to the created dialog. It should be a list with a class of "dialog".

SIDE EFFECTS:

Causes the dialog handling system program to create some windows with the X11 system, but not display them.

DETAILS:

Normal usage would be to use dialog.create to describe and create the dialog window, then to use dialog.display to display the dialog and wait for the user to press one of the buttons along the bottom of the dialog. A dialog can also be re-created from an existing S-PLUS object of class "dialog". This can be useful to create a copy of a current dialog or to reuse a dialog from a previous run of the dialog handler. Refer to the dialog.recreate for information.

The "textfield" widget is a single line text field. If numeric data is being input using this widget, the validation of the entry is done by the as.numeric function called from dialog.getvalues. This is created in Motif with the XmCreateTextField() routine.

The "radiobox" widget is a collection of toggle buttons contained within and managed by a container widget. Exactly one of the buttons should be pressed at any one time. Under Motif, the XmCreateRadioBox() routine is used.

The "check" widget is just a single toggle button used to represent a simple logical value (on/off; true/false). It is an XmToggleButtonGadget in Motif.

The "pulldown" widget is a widget that displays the current selection as a button in the dialog with a "pulldown" arrow indicator and label on the button. Clicking the button displays a pulldown menu with the available selections. In Motif, this corresponds to what is created with the XmCreateSimpleOptionMenu() routine.

The "list" widget is a scrolling list of available choices and a text field that shows the current selection. If the RETURN key is pressed in the text field, the current contents are compared with the available choices. If the text field value exactly matches one of the choices, that choice will be selected. Otherwise, the first choice for which the text field value is an initial prefix will be selected (i.e. the text field value can be an abbreviation of one of the choices). Note that the RETURN key must be pressed to accept any entry into one of these text fields. Clicking on one of the dialog buttons will not cause this to happen. With Motif, this corresponds to a call to XmCreateScrolledList() and one to XmCreateTextField() to create the widgets.

The "slider" widget is a numerical input widget where the minimum and maximum values are represented by endpoints of a line segment. The current value is represented by a box that slides between the endpoints with the current value displayed along with the box, by default. In Motif, this corresponds to an XmScale class widget.

SEE ALSO:

, , ,

EXAMPLES:

dialog.start('-xrm "SdlgMotif*purpleDialog*background: purple"') 
purple.dialog <- dialog.create(list("Pick a number"=0:10), 
                               xdialog="purpleDialog") 
answers <- dialog.display(purple.dialog) 
# Ask the user to pick some options for PostScript printing 
#  (NOTE: the 'lpr' command & its '-P' option are machine-specific items.) 
lpr.dialog <- dialog.create ( 
   values=list("Pick a printer"=c("dev","admin","colorps"), 
               "Print command"="lpr -r -h", dialog.decor("separator"), 
               "Default font size"=120, "Use RGB Colors"=T), 
   widgets = c("pulldown", "", "", "slider"), 
   options = c("", "", "", "min 50 max 300 scale 1")) 
answers <- dialog.display(lpr.dialog) 
if(answers$button == "OK") { 
   ps.options(command=paste(answers$values$"Print command", " -P", 
                            answers$values$"Pick a printer", sep=""), 
              pointsize = 0.1 * answers$values$"Default font size", 
              setcolor = if(answers$values$"Use RGB Colors") 
                         ps.setcolor.rgb else ps.setcolor.hsb) 
} 
dialog.destroy(dialog1) 
# Do an operation on a specified object. 
obj.dialog <- dialog.create ( 
   values=list("Object"=objects()), options='ncolumns 6', 
   buttons=c('Cancel', 'summary', 'range', 'length')) 
answers <- dialog.display(obj.dialog) 
if(answers$button != "Cancel") 
   do.call(answers$button, list(get(answers$values$Object)))