GUI related functions

This chapter will deal with the different GUIs (Graphical User interfaces) used to interact with the user of your script.

Currently, ScanaStudio uses (and needs) a GUI for decoder scripts and trigger sequence builder scripts. Users of those two kinds of scripts may very well have absolutely no experience in programming and/or JavaScript, so the GUI is here to allow those users to configure different parameters that will affect the operation of the script.

Here are the main groups of GUI related functions:

• Functions to construct (draw) the GUI
• Functions to evaluate (and validate) the choices set by the user in the GUI (optional)
• A function to retrieve the choices set by the user in the GUI

Note on writing convention: Through all this document, a function’s parameter is considered to be numerical values unless it’s written in “quotation_marks”, which means the function expects a text string for this parameter.

GUI entry-point functions

As described in previous chapters, ScanaStudio will search for special “entry-point” functions in your script to perform certain actions. There are several entry-point functions used to construct a GUI, depending on what it will be used for:

function on_draw_gui_decoder()
{
  // function called when ScanaStudio needs to display the protocol decoder GUI
}

function on_draw_gui_trigger()
{
  // Function called when ScanaStudio needs to display the trigger sequence generator GUI
}

function on_draw_gui_signal_builder()
{
  // Function called when ScanaStudio needs to display the signal builder GUI
}

Any script that builds a GUI must be in one of these functions (or in a function that is only called from one of these functions).

Optionally, the script may implement other entry level functions used to evaluate the choices set by the user in the GUI, and prevent him from going further if some choices are incoherent or unlogic. The evaluation function can even display a message to the user explaining what choice is incoherent.

The GUI evaluation entry point functions (which will be discussed in detail later in this chapter) are:

• on_eval_gui_decoder()
• on_eval_gui_trigger()
• on_eval_gui_signal_builder()

Those functions are optional: If one is omitted, the corresponding GUI will always be considered to be valid, which may be the case for some scripts.

GUI construction

Below is the exhaustive list of functions exposed by the ScanaStudio object that can be used to build a GUI. Please note that GUI is drawn in the same order as the functions used to append different elements to it.

ScanaStudio.gui_add_ch_selector(“id”,”caption”,”new_channel_name”)

Description: this function appends a channel selector to the GUI, that is, a combo box with a list of channels. The exact number of channels in that combo box will depend on the logic analyzer device being used. This is probably the most used GUI elements.

Parameters

• “id” : a unique text string used to identify this GUI item (not displayed to the user)
• “caption” : a caption to describe (in a few words) what the channel will be used for. (e.g. You could use “Clock” to let the user select the channel to be used a clock input for some protocol.)
• “new_channel_name”: the default (new) channel name. A decoder can prompt the user to rename the labels of logic analyzer channels to something more meaningful than the standard “Channel n” label.

Context : Global

ScanaStudio.gui_add_text_input(“id”,”caption”,”default_value”)

Description: This function appends a text input field to the GUI.

Parameters:

• “id” : a unique text string used to identify this GUI item (not displayed to the user)
• “caption” : a caption to describe this GUI item.
• “default_value” the value to be filled in the text box by default.

Context : Global

ScanaStudio.gui_add_baud_selector(“id”,”caption”,default_value)

Description: This function appends a BAUD rate selector element. The baud rate selector is an enhanced text box; the user can manually type a BAUD rate (like 115200), but he can also click on the “Auto detect” button as show in the image below.

Clicking the Auto detect button shows a dialog like in the image below:

For each channel in the drop down list, ScanaStudio will offer two options to the user: the exact baud rate measured (guessed) from the signals on that channel, and the nearest standard baud rate (picked from a list of well known BAUD rates like 115200 for serial UART, or 1000000 for CAN bus). Clicking on one of those two baud rate would autofill the BAUD rate text box in the initial GUI item.

Parameters:

• “id” : A unique text string used to identify this GUI item (not displayed to the user)
• “caption” : A caption to describe this GUI item.

Context : Global

ScanaStudio.gui_add_check_box(“id”,”caption”,is_checked)

Description: This function appends a checkbox to the GUI.

Parameters:

• “id” : A unique text string used to identify this GUI item (not displayed to the user)
• “caption” : A caption to describe this GUI item.
• is_checked : A boolean indicating if the checkbox is checked by default. You can either use the keyword true/false or an integer 1/0.

Context : Global

ScanaStudio.gui_add_combo_box(“id”,”caption”)

Description: This function appends a combo box to the GUI. The content of the combo box is added using the function ScanaStudio.gui_add_item_to_combo_box. Here is an example code that appends a combo box to the GUI, then inserts 3 elements to that combo box:

ScanaStudio.gui_add_combo_box("my_combo","Select an option");
  ScanaStudio.gui_add_item_to_combo_box("Option 1");
  ScanaStudio.gui_add_item_to_combo_box("Option 2");
  ScanaStudio.gui_add_item_to_combo_box("Option 3");

Parameters:

• “id” : A unique text string used to identify this GUI item (not displayed to the user)
• “caption” : A caption to describe this GUI item.

Context : Global

ScanaStudio.gui_add_item_to_combo_box(“item_txt”,is_selected)

Description: This function appends a new line (new item) to the combo box that was last appended to the GUI.

Parameters:

• “item_txt” : The text to display for that item
• is_selected : a boolean value that defines weather an item is selected by default. If this parameter is ignored, the value false will be used by default. If no any element as the parameter is_selected set to true, then the very first element will be selected by default.

Context : Global

ScanaStudio.gui_add_engineering_form_input_box(“id”, “caption”, min_value, max_value, default_value, “unit”)

Description: This function adds an input box specifically made for numbers that need to be entered in engineering format (e.g.: 2 ms or 25 MHz). By engineering format, we mean a number that is composed of:

• a value,
• a prefix
• and a unit.

For example, the following line of code:

ScanaStudio.gui_add_engineering_form_input_box("rate","Bit rate",100,1e6,125e3,"Bit/s");

will create this GUI item:

Parameters:

• “id”: A unique text string used to identify this GUI item (not displayed to the user).
• “caption”: A caption to describe this GUI item.
• min_value: along with max_value, this parameter lets ScanaStudio calculate the most suitable prefixes for the unit (the prefixes are “n” for nano, “u” for micro, “m” for milli, “k” for kilo, etc.).
• default_value: the default value to be displayed in the input box when the GUI item is created
• “unit”: a text, usually composed of one or a few characters. The prefix and the unit will be combined together on the GUI item, to form engineering values like “KHz” or “mS”.

Context: Global

ScanaStudio.gui_add_info_label(“text”)

Description: This function appends an information label. This GUI element is not used to get input from the user, but rather to give him some instructions. There is no “id” parameter for this GUI element, for the simple reason that it does not need to be?? addressed later, neither can this GUI element hold an information to be retrieved later.

Parameters:

• “text”: This parameter hold the text to be displayed.

Context : Global

ScanaStudio.gui_add_separator(“title”)

Description: This function simply adds a separator (horizontal ruler) between two sections in the GUI. This function has no “id” parameter, and cannot be addressed later by the script.

Parameters:

• “title”: This optional parameter hold the title to be displayed on the ruler.

Context : Global

File system GUI elements

Some scripts can access files either for reading or writing. For example, an I2S protocol decoder (used to transmit audio signals) can output decoded data to a *.wav file. Similarly, a protocol decoder script may refer to some local configuration file - for example - to adjust various parameters that would be complex and tedious to set in GUI. Please note that for security reasons, ScanaStudio scripts cannot have access to the actual file path set by the user in the GUI, nor can it arbitrarily read or write files on the user’s computer. Only the files selected by the user via the provided GUI items are accessible to the script (but without exposing the file path to the script).

ScanaStudio.gui_add_file_save(“id”,”caption”,”extension”)

Description: This function adds a GUI item that prompts the user to select a file path for writing. If the file already exists, ScanaStudio will ask the user to confirm if the file can be overwritten.

Parameters:

• “id”: Unique ID of this GUI item. This ID is used by the script to select the file to be opened. As stated before, the script will never has access to the file’s path; file system operation are only carried via this ID, which effectively limits the scope of the files read/write operation to the file(s) specified by the user of the script in the GUI.
• “caption”: Text that will appear next to the save file item. This is a good place to describe what this file will be used for.
• “extension”: A text string that defines the extension to be used by ScanaStudio’s file dialog to filter the files. use “.” or leave empty to show all files. use “*.csv” to show only CSV files, for example.

Context: Global

ScanaStudio.gui_add_file_load(“id”,”caption”,”extension”)

Description: This function is similar to the ScanaStudio.gui_add_file_save with the exception that a “load file” dialog will be used. That also means that this GUI item cannot be used to create a new file, it can only be used to select an existing file.

Hidden GUI elements

Hidden GUI elements can be treated like any other elements, with the difference that it wont be visible to the user. They exist for one particular purpose: sub-decoders.

First, let’s explain what are sub-decoders: A sub-decoder is a decoder that is called by another “high level” decoder. By “high level”, we mean a decoder that is accessed by the user, for which a GUI is displayed. A typical application of sub-decoders, is to build a temperature sensor protocol decoder that is based on a low level I2C decoder. Being able to call a sub-decoder from the high level decoder prevents the high level script from implementing the whole I2C decoding layer. Any decoder can become a sub-decoder provided that it’s called by another decoder.

Since the sub-decoder has no way of displaying a GUI, it’s the high level decoders’ job to expose hidden GUI items with the exact same IDs expected by the sub-decoder.

ScanaStudio.gui_add_hidden_field(“id”,”value”)

Description: This function appends a new hidden GUI field.

Parameters:

• “id” : A text string used to identify this GUI item (not displayed to the user). This ID needs to be exactly the same as the ID of a GUI element of a sub-decoder.
• “value” : A text or numerical value attached to that hidden GUI item. Context : Global

Examples

//create a numeric item with the value = 1.
//Note that there are no "quotation marks" around the value parameter
ScanaStudio.gui_add_hidden_field("id_num",1);
//Create a text value item
ScanaStudio.gui_add_hidden_field("id_txt","text value");
//Create a boolean value item
ScanaStudio.gui_add_hidden_field("id_bool","true");

ScanaStudio.gui_set_hidden_field(“id”,”value”)

Description: This function changes the value of a hidden field. This can be useful when a decoder needs to change the behavior of a sub-decoder.

Parameters:

• “id” : ID of the hidden field to be changed
• “value” : New value to be set for that hidden field. It can be a number or a text string

Context : Global

As with the gui_add_hidden_field function, you may set a numeric value by ignoring the “quotation mark” around the value parameter, e.g.:

ScanaStudio.gui_set_hidden_field("id_numeric",5);

Grouping GUI elements in tabs

It is possible to group GUI elements in separate accordion tabs. Each tab has a different title (defined by the “caption” parameter). Accordion tabs are great when it’s needed to toggle between hiding and showing a large amount of content.

An example for the usage of tabs is the SPI protocol script, which uses tabs to categorize advanced configuration options, and prevent cluttering the user interface. Only the most important and most used parameters are visible right from the start.

Putting GUI elements inside accordion tabs is done using the functions presented below.

ScanaStudio.gui_add_new_tab(“caption”,is_expanded)

Description: This function creates a new accordion tab element. All GUI elements appended after a call to ScanaStudio.gui_add_new_tab is added to that tab.

Parameters:

• “caption” : A title to describe this tab.
• is_expanded : A boolean value that defines weather a tab is expanded by default.

Context : Global

ScanaStudio.gui_end_tab()

Description: This function ends the tab that was previously started with the function gui_add_new_tab(...). Any GUI element added after a call to gui_end_tab() will not be grouped under a tab that can be expanded or minimized.

Context: Global

Examples:

  ScanaStudio.gui_add_new_tab("Test tab 1",true);
    ScanaStudio.gui_add_check_box("c01","Option 1",false);
    ScanaStudio.gui_add_check_box("c02","Option 2",false);
  ScanaStudio.gui_end_tab();

  ScanaStudio.gui_add_new_tab("Test tab 2",false);
    ScanaStudio.gui_add_check_box("c11","Option 1",false);
    ScanaStudio.gui_add_check_box("c12","Option 2",false);
  ScanaStudio.gui_end_tab();

  ScanaStudio.gui_add_new_tab("Test tab 3",false);
    ScanaStudio.gui_add_check_box("c21","Option 1",false);
    ScanaStudio.gui_add_check_box("c22","Option 2",false);
  ScanaStudio.gui_end_tab();

The above example would produce the GUI interface shown in the image below:

Selectable containers

Selectable containers are special GUI constructs that have three roles:

• Grouping GUI elements in containers
• Ensuring only one container is visible and selected at a given moment.
• Knowing which container is chosen by the user

In other words, selectable containers are used when only one among several GUI designs alternatives should be used, depending user choices. Each one of those alternatives can have a totally different GUI, thus, this function groups the GUI elements of each alternative in a separate exclusive container.

The script can later retrieve the state of each container (whether it’s selected or not), and decide what GUI elements to consider from which container.

Only one container in a containers group - the one that is selected - is displayed to the end user. The image below shows the vocabulary used to describe Selectable containers’ GUI.

Putting GUI elements inside containers, and putting containers inside a containers group is done using the functions presented below.

ScanaStudio.gui_add_new_selectable_containers_group(“id”,”caption”)

Description: This function creates a new selectable containers group. A call to this function must be followed by one or more calls to ScanaStudio.gui_add_new_container. Other GUI elements (like combo boxes, text input or check boxes) cannot be added “inside” the selectable_containers_group; a container must be created first, then GUI items can be added to that container.

Parameters:

• “caption”: Title of the containers group
• “id”: A unique text string used to identify this GUI item (not displayed to the user). This unique ID can later be used to retrieve the index of the selected container in a group (See the function gui_get_value() for more information on that matter).

Context: Global

ScanaStudio.gui_end_selectable_containers_group()

Description: This function ends the containers group that was previously started with the function gui_add_new_selectable_containers_group(...).

Context: Global

ScanaStudio.gui_add_new_container(“caption”,is_selected)

Description: This function creates a new container. A container can only be created between gui_add_new_selectable_containers_group and gui_end_selectable_containers_group calls.

Parameters:

• “caption” : A title to describe this container.
• id_selected : A boolean value that defines weather a container is selected by default. Only one container in a containers group should have the property is_selected set to true.

Context: Global

ScanaStudio.gui_end_container()

Description: This function end the container that was created by gui_add_new_container.

Context: Global

GUI evaluation and validation

GUI evaluation is a process by which a GUI is tested against any incoherencies. By incoherencies, we mean choices made by the user that would yield to unexpected or wrong results. For example, choosing the same channel twice as the clock and the data for a protocol decoder is incoherent.

The GUI evaluation functions prevents the user to go any further until incoherencies are fixed, as it is described in the diagram below:

All GUI interfaces can be evaluated using one of the entry-function below:

• on_eval_gui_decoder()
• on_eval_gui_trigger()
• on_eval_gui_signal_builder()

Please note that this functions is optional: If omitted, the corresponding GUI will always be considered as valid.

All these functions behave in the same way: When called by ScanaStudio, they have to evaluate the GUI and return an empty string (“”) in case of a valid GUI, or a text string describing the problem.

Below is an example of a decoder GUI evaluation function:

function on_eval_gui_decoder()
{
  if (ScanaStudio.gui_get_value("ch_data") == ScanaStudio.gui_get_value("ch_clock"))
  {
      return "Error: Data and clock can't share the same channel";
  }
  return ""; //All good.
}

GUI data retrieval

As discussed in this chapter, each GUI element has a unique ID. This ID is used to retrieve the values set by the user in the GUI (which is the whole purpose of the GUI in the first place).

A single function allows GUI data retrieval for any GUI element:

ScanaStudio.gui_get_value(“id”)

Description: This function returns the value of the GUI element “id”. For a combo box or channel selector, this function will return the index of the element selected by the user (0 based).

For checkboxes, it will return true or false depending on the choice of the user.

For other input boxes (text or numbers), this function will return the characters as they were entered by the user.

For tab GUI element, it will return true or false depending on weather a tab is selected or not. Obviously, only one tab can be selected at a given time, hence, only one tab’s ID will return the value true.

For selectable containers group, this function will return the index of the container selected by the user.

Parameters:

• “id”: text string representing the GUI element.

Context : Global

Complete example

As an example the code below is functional (but useless) decoder script:

/* Protocol meta info:
<NAME> My Protocol </NAME>
<DESCRIPTION>
My protocol can decode pretty much any logic signal!
</DESCRIPTION>
<VERSION> 0.0 </VERSION>
<AUTHOR_NAME>  Your name </AUTHOR_NAME>
<AUTHOR_URL> your@email.or.website </AUTHOR_URL>
<HELP_URL> https://github.com/ikalogic/ScanaStudio-scripts-v3/wiki </HELP_URL>
<COPYRIGHT> Copyright your name </COPYRIGHT>
<LICENSE>  This code is distributed under the terms of
 the GNU General Public License GPLv3 </LICENSE>
<RELEASE_NOTES>
V0.0:  Initial release.
</RELEASE_NOTES>
*/

//Decoder GUI
function on_draw_gui_decoder()
{
  ScanaStudio.gui_add_ch_selector("ch","My channel selector","new_channel_name");
  ScanaStudio.gui_add_text_input("text","My text input","Write some text");
}

var ch,text;
function on_decode_signals(resume)
{
  ch = ScanaStudio.gui_get_value("ch");
  text = ScanaStudio.gui_get_value("text");

  ScanaStudio.console_info_msg("The selected channel is:" + (ch+1) +
  ", and the input text is: "+ text);
}

This example creates a simple GUI with two elements as shown in the image below:

In this examples, the GUI values are retrieved and shown in the console:

For your information, the console can be displayed by going to the setting menu in ScanaStudio (top right icon) and tick the “Show log” or “Show console” depending on your version of the software.