Masking code cells of interactive scripts¶
This example demonstrates the ability to add masks to code cells of interactive scripts.
Masking allows to simplify code parameterisation in scripts by creating visual graphical interfaces. Users who work with such scripts will not have to understand the contents of code cells; instead, they will be able to customise the values of variables in the code using familiar controls.
An example of a graphical interface created using code cell masking is shown on the screenshot:
Code cell masks - Engee script editor functionality. To familiarise yourself with masking in interactive mode, we recommend opening this example in the script editor (not in the Engee documentation or community, as code cell masks are not displayed there).
Basics of use¶
A mask is a customised user interface of a code cell.
A code cell is masked if at least one special comment like # @param or # @markdown is added to it.
Comments # @param are intended for adding interactive parameters to the code cell:
- Text fields (input);
- Checkboxes (checkbox);
- Dropdown lists (dropdown);
- Sliders (slider).
The interactive parameters are linked to a variable with a special comment added at the end of the definition line.
Two-way communication is organised between the code editor and mask elements:
- When you change the value of a variable in the GUI, the value in the code cell will automatically change as well;
- And vice versa, if the value of a variable in the code cell is changed, the value in the GUI will change.
The # @markdown comments are designed to add Markdown markup to the code cell (this is the language used in the text cells of the Engee script editor). By using the simple and clear Markdown syntax right after a special comment, you can make the mask even more visible.
By default, the code editor and the GUI are displayed simultaneously. To hide the code display, double-click on the mask. To display the code again, you can click on the "Show Code" button or double-click on the cell again.
Interactive parameters¶
To add a string variable input text box, use the special comment # @param {type:"string"}:
input_string = "Hello, world!" # @param {type:"string"}
To add an arbitrary number input text box, use the special comment # @param {type:"number"}:
input_number = -0.123456789 # @param {type:"number"}
A text field for entering an integer variable can be added using the special comment # @param {type:"integer"}:
input_integer = 42 # @param {type:"integer"}
To add a free-format text input field (the most flexible option, as the variable data type is not limited), you must use the special comment # @param {type:"raw"}:
input_raw = input_string # @param {type:"raw"}
To add a flag button, use the special comment # @param {type:"boolean"}:
input_boolean = false # @param {type:"boolean"}
A calendar with date selection option (will be written to a string variable in the format YYYY-MM-DD) can be added using the special comment # @param {type:"date"}:
input_date = "2024-09-03" # @param {type:"date"}
To add a drop-down list of string variable selections, use the special comment # @param [""], listing all possible options inside the array:
dropdown_string = "Первый" # @param ["Первый", "Второй", "Третий"]
If you want to combine a string variable selection drop-down list with an input option, you can use the special comment # @param [""] {allow-input:true}
dropdown_string_editable = "Нулевой" # @param ["Первый", "Второй", "Третий"] {allow-input:true}
To add a free-format variable selection drop-down list, use the special comment # @param [""] {type:"raw"}, listing all possible choices inside the array:
dropdown_raw = "Engee" # @param [""Engee"", "input_raw", "false", "42"] {type:"raw"}
If you want to combine a free-format variable selection drop-down list with an input option, you can use the special comment # @param [""] {type:"raw", allow-input:true}
dropdown_raw_editable = true # @param [""Engee"", "input_raw", "false", "42"] {type:"raw", allow-input:true}
To add a slider, use the special comment # @param {type:"slider", min:x, max:y, step:z}, substituting instead:
x- minimum value;y- maximum value;z- step:
slider_number = 0.5 # @param {type:"slider", min:-1, max:1, step:0.01}
slider_integer = 50 # @param {type:"slider", min:1, max:100, step:1}
Markdown markup language¶
Headings:
# @markdown # Заголовок 1
# @markdown ## Заголовок 2
# @markdown ### Заголовок 3
# @markdown #### Заголовок 4
# @markdown ##### Заголовок 5
# @markdown ###### Заголовок 6
Paragraphs and line breaks:
# @markdown Чтобы создать новый параграф, вставьте пустую строку между двумя строками текста.
# @markdown
# @markdown Для переноса строки внутри одного параграфа
# @markdown используйте два пробела в конце строки.
Text Highlighting:
# @markdown *курсив*
# @markdown _italic_
# @markdown
# @markdown **жирный**
# @markdown __bold__
# @markdown
# @markdown ***жирный курсив***
# @markdown ___bold italic___
# @markdown
# @markdown ~~зачёркнутый strikethrough~~
Numbered list:
# @markdown 1. Первый пункт
# @markdown 2. Второй пункт
# @markdown 3. Третий пункт
Marked list:
# @markdown - Первый пункт
# @markdown - Второй пункт
# @markdown - Третий пункт
Nested list:
# @markdown 1. Первый пункт
# @markdown - Первый подпункт
# @markdown - Второй подпункт
# @markdown 2. Второй пункт
Reference:
# @markdown [Telegram-канал Engee](https://t.me/engee_com)
Image:
# @markdown 
Line of Code:
# @markdown `using Plots`
Code Block:
# @markdown ```Julia
# @markdown x = range(0, 10, length=100)
# @markdown y = sin.(x)
# @markdown plot(x, y)
# @markdown ```
Quote:
# @markdown > Первый уровень
# @markdown >> Второй уровень
# @markdown >>> Третий уровень
Horizontal Line:
# @markdown ---
Table:
# @markdown | Заголовок 1 | Заголовок 2 |
# @markdown | ----------- | ----------- |
# @markdown | Ячейка 1 | Ячейка 2 |
# @markdown | Ячейка 3 | Ячейка 4 |
Emoji:
# @markdown :smile:
# @markdown :laughing:
# @markdown :blush:
HTML Tags:
# @markdown <kbd>CTRL</kbd> + <kbd>V</kbd>
Conclusions¶
This example demonstrates the ability to mask code cells. It is a simple yet functional way to make interactive scripts even more responsive and accessible!