RPGM 2.0 Docs

Graphical User Interfaces (.pgui file)

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.

Client GUI

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.

Field list

On the left of the screen, a list shows all the widgets added to the form:

GUI Editor

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.

Preview

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.

Field properties

This section will describe each properties available for the widgets.

Common properties

Those properties are available for all (or almost all) widgets:

Common properties

Type
This is the type of the widget. Pretty straightforward.

  • Text area is a multi-line version of Text.
  • File allows the user to open a “Select file” dialog and select a file.
  • Folder is the same as File, but the user must select a folder instead of a file.
  • Drop-down list and Radio are both a single-choice control. We recommend using Drop-down list over Radio although both are working.
  • Multi-select list allows the user to select more than one choice. You get the result in R as a vector of strings populated with the selected IDs/Values.

ID
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 gui.setValue().

Label
This is a text on the left of the field for explaining what is its purpose.

Value
This is the default value of the field.

  • For Drop-down list and Radio, this must be the ID of the selected option.
  • For Checkbox, this must be either TRUE or FALSE.
  • For Image, you can either write a relative path to the output folder of the user (like images/graph.png), or write an absolute path through R (rpgm.pgmfilepath("image.png")). Several image formats are accepted: BMP, GIF, JPG, JPEG, PNG, PBM, PGM, PPM, XBM and XPM.
  • For Textarea, writing \n will create a new line.
  • For Multi-select list, you must supply a vector of strings (of IDs/Values) if you use a R expression. If you don’t use a R expression, you must write the values you want to be selected separated by a comma. For example: 1,y,4 will select the options with “1”, “y” and “4” as values.

R expr.
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.

Required
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.

R Condition
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.

Label properties

The label widget has additional properties:

Label properties

  • Full width will hide the label and expand the text on the whole width of the GUI.
  • Margin top is the top margin in pixels of the label. If you want to create a small text for a previous widget, set the margin to 0. If you want to create a title and create a huge space, set a high value. Default is 10.
  • Font color is the color of the text.
  • Font size is the size of the font in pixels. Default is 20.
  • Font family is the family of the font.

Image properties

Image 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 properties

Text and Text area have another property:

Text properties

This allows to limit the number of characters entered in the field. Letting this property empty or setting it to 0 removes any limitations.

Integer, Double and Slider properties

Numbers properties

Those properties will limit the minimum and the maximum number that can be entered.


Leave this property empty for no limits.

### Lists and Radio properties

Lists properties

You can add here options for the control. This works as the same as the list of the widgets: you can drag & drop to reorder, the first text is the value and the second one is the displayed text in the field. The value can be a number or a string. In the Default and R expression field, you must write one of those values, not the text.

The List of values can be a R vector containing a list of values to add in the widget before showing the GUI. The List of texts is a R vector containing a list of texts to add in the widget before showing the GUI.

Button properties

Button properties

R on press is a special R code which will be executed when the user press the button.