GDForms is a plugin for Godot that allows the creation of interactive forms for collecting information from the user.
GDForms comes with a number of custom (and customizable) form widgets for creating forms. The widgets can be styled using Godot themes.
For instance, GDForms Checkbox widgets encapsulate standard Godot Checkboxes, but you can position the label to the left, above or below the button.
The Options widget can be used for displaying several options to the user. You can select whether multiple choices are allowed or not.
The options can be presented either vertically or horizontally. A line can also be optionally drawn in the background to suggest a scale.
The OptionGrid presents several options in a grid with labels for each row and column.
The TextInput widget is simply a wrapper for the standard TextInput element. The ValidatedInput widget on the other hand allows you to limit the input to specific characters, and you can provide a regular expression that will be used for determining if the input text is "valid".
There are also a number of standard buttons that can be used for interacting with the form: CancelButton, SubmitButton, NextButton, BackButton, as well as a generic FormButton.
Longer forms can be split into several FormPage containers. These are Vertical Box Containers that are recognized as pages by their parent form. Simply by placing NextButton and BackButton widgets to your form, the user can navigate from one page to the next.
Branch nodes can be added to any GDForms widget, to implement branching behaviour.
These Branch node can potentially affect three other CanvasItem nodes. The target node's visibility will be turned on and off depending on whether the branch's condition is met. The alternate target branch's visibility will be set to the opposite of the target, allowing you to toggle between two messages, or two buttons, for instance. Lastly, the disabled target will be disabled when the branch condition is met. You can use this to prevent users from editing their choices.
The Branch inspector will only show you the parameters relevent to its parent widget. For instance, here we see options for a Branch attached to an Options widget.
The condition type can be set to any value, in which case the target is made visible as soon as the user interacts with the widget. If instead, this value is set to specific value, then the branch will only activate if the condition is met. For Options, we provide an array of valid indices. We can specify whether we want the user to chose all the specified options or only some of them. OptionGrid branches work in the same way, but we can provide "answer keys" for each row.
Several Branch nodes can be added to the same widget to allow for relatively complex branching patterns.
gdforms_screengrab.mp4
When you enable the GDForms plugin, a new dock panel is added to the bottom-left of the screen. This provides a number of useful shortcuts for creating forms.
In GDForms, forms are simple CanvasItem nodes that can be easily integrated into any GUI. You can have more than one form displayed at the same time and each form can have several pages.
On the scripting side, all you need to do to use GDForms is to connect to the submit and cancel signals. Everything else is taken care of.
The submit signal will provide you with a form id (which you provide) and a Dictionary containing the state of all widgets. (In order for a widget to report its state to its parent form, you must provide an identifier that will be used as a key in the Dictionary.)
Here is a sample of GDForm data, formatted as JSON, with JavaScript comments, that shows the structure of the data for each widget type.
{
// Checkbox: bool
"agreement": true,
// Options (single selection): both the index and the label is reported.
"colors": [
{
"index": 2,
"label": "Option grids"
}
],
// Options (multiple selections): the selected indices and the labels are reported.
"programming languages": [
{
"index": 1,
"label": "GDScript"
},
{
"index": 3,
"label": "C#"
}
],
// Another Option item. Note that you can specify an index offset. Here 'disagree' would have an index of -1.
"likert": [
{
"index": 1,
"label": "Agree"
}
],
// OptionGrid: much like Options, but every row has its own Dictionary
"grid": [
{
"label": "Service",
"selection": [
{
"index": -1,
"label": "Poor"
}
]
},
{
"label": "Food",
"selection": [
{
"index": 1,
"label": "Good"
}
]
},
{
"label": "Mood",
"selection": [
{
"index": 0,
"label": "Average"
}
]
}
],
// TextInput and ValidatedInput: all values are strings.
"Free text": "Hello! How are you?",
"user_id": "1234"
}