The main feature of RPGM is the ability to easily create GUIs. A GUI contains several fields, also called widgets. A submit button is automatically added to the end of the form in the Client.
The end-user, through the Client, can enter texts, numbers, files and other type of inputs with the widgets. Those inputs will then be available in R scripts.
On the left of the screen, a list shows all the widgets added to the form:
Each line represents an added widget. The icon on the left represents the type of the widget (Label, Text, Image, Drop-down list…). The first text is the ID of the field, and the second text is the text label in front of the widget. By selecting a row in this list, the properties for the corresponding field appears on the right. You can also drag and drop to reorder the fields in the form. Widgets can be added by selecting a widget type on the top and then click Add. A right click on a row will show a context menu for duplicating or removing a field.
On the middle of the tab, a real-time preview of the GUI is displayed. The widgets will not works and this is only for convenience.
This section will describe each properties available for the widgets.
Those properties are available for all (or almost all) widgets:
This is the type of the widget. Pretty straightforward.
This is a unique name representing the field. This is also the name of the R variable in the next script. For example if a field has
nmbr for its ID, then after submitting the form, a R variable named
nmbr will exist in R with the value of the field. For widgets of type Title, Label or Image, which do not generate a R variable, the ID is optional but can be supplied, to be use later with some R functions like
mynumber, or more complex expressions like
This is a text on the left of the field for explaining what is its purpose.
This is the default value of the field.
rpgm.pgmfilepath("image.png")). Several image formats are accepted: BMP, GIF, JPG, JPEG, PNG, PBM, PGM, PPM, XBM and XPM.
\nwill create a new line.
1,y,4will select the options with “1”, “y” and “4” as values.
If set to TRUE, the text in the Value field is considered to be a R expression and will be executed when the user enters the GUI. The result of this R command will represent the value of the field. You can either write a single variable name
my_variable or you can write a more complex expression, for example
(result > i*20+5) for a Checkbox or
paste("Your name is", input_name) for a Text field.
If checked, the field must be filled before the form is submitted. For Checkbox, this forces the user to check the box. If the user omits filling the field, the form will show an error below the empty field.
Is a special R code executed when the user submit the form and which must return either TRUE or FALSE. If the returned value is FALSE, an error message is displayed under the widget and the user will not be able to continue in the program.
R on change
Is a special R code executed when the value of the widget is changed by the user. This is where special GUI function can be called for creating dynamic GUIs.
The label widget has additional properties:
Images have one additional property, Full width, which hide the label and expand the image on the whole width of the GUI, like for the text widget.
Text and Text area have another property:
This allows to limit the number of characters entered in the field. Letting this property empty or setting it to 0 removes any limitations.
Those properties will limit the minimum and the maximum number that can be entered.
R on press is a special R code which will be executed when the user press the button.