tutorial 03: Dialog Interaction
A recipe often needs extra user input. The dialog interactions in this tutorial will allow a recipe to ask the user for selections and text.
In this tutorial you will learn to:
- Create a default dialog
- Create a custom dialog
- Use the item cache to store temporary data
To begin, use the base recipe from Tutorial 02
Add an onAbout() function which is called when the user clicks the about question mark button. You can use this function to display a basic dialog with just an okay button, using the dialog function. This function takes in the title and description from the header of the recipe, as well as an icon type ("i" for information).
function onAbout()
{
dialog(header.title, header.description, "i");
}Now to create a custom dialog, you can use the <C><s></s>onConfig()<e></e></C> function, which is called when the user clicks the config button. To create a form for the dialog, you can create an object with keys and objects that describe the form. For example, to create a simple label, you can use the following object:
var form = {
"my_label" : {
"type" : "text",
"label" : "instruction text"
},
};The key name can be custom, and the value is an object with a "type" value ("text" in this case) and a "label" value, which is the text displayed to the user.
To create a combo box, you can add the following object to the form:
"my_combobox" : {
"type" : "combobox",
"label" : "items test:",
"items" : [ "item 1","item 2","item 3" ],
"default" : "item 3"
},The "items" value is an array with the options for the combo box, and the "default" value is the item that is selected when the dialog is opened.
To allow the user to input text, you can use the following object:
"my_text" : {
"type" : "textedit",
"label" : "text input:",
"default" : "enter your text here"
},To add buttons to the form, you can use the following objects:
"my_okbutton" : {
"type" : "button",
"label" : "ok",
"returns" : 1
},
"my_cancelbutton" : {
"type" : "button",
"label" : "cancel",
"returns" : 0
}The "returns" value can be used later to check the button selection.
This is the complete form. Note that you can pick your own name for each "my_combobox" ect. But each name should be unique.
Check the dialog syntax for more details.
To open the dialog, you can use the dialog function with the form as an argument:
var r = dialog("the title", "main message", "i", form);The r result object contains the user's selections and input from the form.
You can print the dialog result to the console using the echo function echo(objectToString(r));
The console will then show the current results. ie.
{
"returns": 1,
"my_combobox": "item 3",
"my_text": "enter your text here",
"my_okbutton": "1",
"my_cancelbutton": "0"
}Cache
To store temporary data, you can use the getItems() function to retrieve the items object, which is used to store data as key-value pairs. For example, to retrieve the saved text if it exists, you can use the following code:
var items = getItems();You can then use this saved data as the default value for a form object, as shown in the following example:
"my_text" : {
"type" : "textedit",
"label" : "text input:",
"default" : (items.mytext ? items.mytext : "enter your text here"),
},To save the user's input, you can use the </s>setItems() function at the end of the onConfig() function, like so:
if (r.my_okbutton == 1)
{
items.mytext = r.mytext;
setItems(items);
}This will save the user's input in the items object, which can then be accessed in future calls to this dialog.
To call the onConfig() function, you can use the F9 key or the Run > onConfig menu option.
To test the dialog and item cache functionality, you can run the onConfig() function multiple times, entering different values and pressing the OK button each time. The items object should contain the latest saved data, which will be used as the default value for the form elements.
Here is the complete example code:
function onAbout()
{
dialog(header.title, header.description, "i");
}
function onConfig()
{
var items = getItems();
var form = {
"my_label" : {
"type" : "text",
"label" : "instruction text"
},
"my_combobox" : {
"type" : "combobox",
"label" : "items test:",
"items" : [ "item 1","item 2","item 3" ],
"default" : "item 3"
},
"my_text" : {
"type" : "textedit",
"label" : "text input:",
"default" : (items.mytext ? items.mytext : "enter your text here"),
},
"my_okbutton" : {
"type" : "button",
"label" : "ok",
"returns" : 1
},
"my_cancelbutton" : {
"type" : "button",
"label" : "cancel",
"returns" : 0
}
};
var r = dialog("the title", "main message", "i", form);
echo(objectToString(r));
if (r.my_okbutton == 1)
{
items.mytext = r.mytext;
setItems(items);
}
}
function main()
{
setProgress(50);
setMainMessage("waiting for cancel action");
sleepMs(5000);
if (isCanceled())
{
abort("Canceled");
}
setProgress(100);
setMainMessage("stopped normally");
}Now that you have learned how to create and customize dialogs, as well as how to use the item cache to store temporary data, you can use these techniques to create more interactive and user-friendly recipes.
For example, you could use a dialog to prompt the user for specific input or settings, and use the item cache to store those values for later use in the recipe. You could also use the isCanceled() function to allow the user to cancel the recipe at any point, and use the abort() or quit() functions to end the recipe or close the application accordingly.
As you continue to develop your skills in creating recipes, you may want to explore additional features and functions that are available, such as file and folder manipulation, system commands, and more. You can find more information on these topics and more in the documentation at magnetron.dev/docs.