BoardSurfers: Creating GUIs Using Allegro SKILL

19 Sep 2023 • 12 minute read

The Allegro SKILL coding language offers capabilities to create user-friendly graphical user interfaces (GUIs) for an enhanced user experience. The extensive collection of Allegro SKILL widgets enables the creation of sophisticated GUI components for various design tasks. Using Allegro SKILL, PCB, and package, you can extend the design environments. Creating a GUI using Allegro SKILL requires the use of associated Allegro SKILL APIs, which are an integral part of Allegro SKILL. So, you don't even need to install anything else to begin creating GUIs. This post covers detailed steps to create a GUI using Allegro SKILL.

Sample Allegro GUI

An example of the Allegro SKILL GUI is shown in the following image. The image displays the Extract Selector form created using Allegro SKILL.

sample Allegro SKILL GUI

Extract Selector GUI contains a list of the extracta command files available in the Cadence installation location at <Cadence_installation_directory>/share/pcb/text/views

You can select any of the files in theView File field and start the extracta process, which pulls out specific data in an ASCII Text format from the design database of the Allegro layout editor.

Creating a GUI Using Allegro SKILL

The steps to create a GUI with Allegro SKILL are listed in the following table:

Action	SKILL Code
STEP 1: Write a Form file - Define the GUI elements, including their location and options, in a Form file.	NA
STEP 2: Write a callback - Set up callbacks for responding to the inputs specified for various fields.	afCallback
STEP 3: Invoke the Form using the axlFormCreate function, which returns the database ID (dbid) of the form created. A user can access all the fields and values using the dbid of the form.	fw = axlFormCreate('f1s "axlform" position '_afCallback t nil )
STEP 4: Initialize the fields using the axlFormSetField function.	axlFormTitle(fw "--F1-- Skill Test Form" ) axlFormBuildPopup(fw "enum" '(("item1") ("item2") ("item3")) )
STEP 5: Display the form using the axlFormDisplay function. You must place a Done or OK button (default field name is Done) and, optionally, a Cancel button (default field name is Cancel).	axlFormDisplay(fw)
STEP 6: Click the Done or OK button to close the form using the axlFormClose function.	NA

Let us look at these steps in detail:

Step 1: Writing a Form File

A Form file defines the GUI elements, their location, and default values or options. The filename has a .form extension. The name of the Form file is used to invoke the form using the axlFormCreate function in Step 3 as explained later in the post.

The Form file is expected to be in the same directory as the SKILL file or in one of the directories specified in the Allegro PCB Editor environment variable, FORMPATH.

The GUI elements are defined in a Form file using the following format:

Keyword FIELD <fieldName>: The field name is used to handle the user interactions in the callback, as explained in Step 2.
Location: The location is defined by FLOC <x coordinate> <y coordinate>.
Keyword: Type of field is specified by keywords. A label or static text is defined using the keyword, TEXT.

Here’s an example of a Form file:

TEXT "View File:"
TLOC 1 12
ENDTEXT
FIELD cancel
FLOC 5 15
MENUBUTTON "Cancel" 8 3
ENDFIELD

Sample Allegro SKILL generated GUI

Form Specification Language

To fully comprehend the contents of a Form file, it is recommended to familiarize yourself with the Forms Specification Language, Backus Naur Form (BNF). BNF is a formal notation used to describe the syntax of a language. The following example illustrates the BNF definition of the Form file:

specification language

To delve deeper into this topic, refer to the Allegro User Guide: SKILL Reference guide.

Excerpt from BNF for Field Definition

The following example is an excerpt from the Form file created using BNF:

field_definition

Visualizing a Form File

You can view the form to check how the objects are visually placed by using the function axlFormTest "<form file>", as shown in the following image:

visualize_form_files

At this stage, you can only view the form. The GUI elements, such as buttons and fields, are not interactive.

Step 2: Writing a Callback

Whenever a user interacts with a GUI element by clicking a button or entering a value in a form, the Callback function is invoked. The Callback function is the core of the GUI and defines the actions needed to be performed based on user interactions.

The format of the Callback function is a case statement for various field values in the form. It is similar to the switch statement in other programming languages. In each case statement, corresponding to a GUI element, you must specify what needs to be done after the value is changed.

The following is an example code of a form Callback function, showing the output when the Done, Cancel, or View File buttons are clicked:

In this example:

The curField attribute of the form specifies the name of the GUI element the user interacted with. This attribute is specified in the Form file. For example, the Close or Cancel buttons.
The curValue attribute of the form specifies the current value of the field after the user has made the change. If you set g_stringOption to 't' in your call to axlFormCreate, curValue is considered a string. Else, curValue corresponds to the type specified for that field in the Form file, which is also the default setting.
Most interactions with the controls are through the APIs, such as axlFormSetField, axlFormGetField, axlFormSetFieldEditable, and axlFormSetFieldVisible. Certain controls have additional APIs, which are specified in the description of the control. For example, if the value in the text variable is changed, you can store it in a SKILL variable (axlFormSetField form "view_file" form->curValue) or invoke a dialog box (axlUIYesNo("fillin")).

Steps 3, 4, and 5: Displaying a Form

The next three steps involve writing the main function that ties up everything and is called to bring up the GUI. For example, in the following sample code, myExtract is the main function:

(defun myExtract ()
ilename = (cdr (cdr (getDirFiles car(last( parseString( axlGetVariable(“TEXTPATH”)))))))
printf(“ilename is %L” ilename)
form = axlFormCreate( (gensym)
“extract_selector.form” ‘(“E” “OUTER”)
‘_formAction t)
axlFormTitle( form “Extract Selector”)
axlFormSetField( form “view_file” (car ilename))
selectedFile = (car ilename)
foreach( ilename ilename
axlFormSetField( form “file_list” ilename))
axlFormDisplay( form)
); defun myExtract

The myExtract function does the following:

Creates the form and associates the callback, as specified in the Form file, using the axlFormCreate function. The syntax of the axlFormCreate function is as follows:

axlFormCreate( s_formHandle t_formfile [lt_placement] g_formAction g_nonBlock [g_stringOption] )

When the form is created, the callback procedure is specified as the g_formAction argument in the axlFormCreate function. The name of the Form file is the t_formfile argument and was defined in Step 1.

The axlFormCreate returns the database ID (dbid) of the form created. The user can access all the fields and values using this database ID. For example,

fw = axlFormCreate('f1s "axlform" position '_afCallback t nil )

Initializes the fields using the axlFormSetField function as required. For example, it sets a title and default values and builds a popup. Note that this is an optional step. If skipped, the default title and values are used.

axlFormTitle(fw "--F1-- Skill Test Form" )

axlFormBuildPopup(fw "enum" '(("item1") ("item2") ("item3")) )

Displays the form using the axlFormDisplay function.

axlFormDisplay(fw)

Example GUIs

To get started with Allegro SKILL GUI creation, you can refer to the examples located in the <Cadence_installation_directory>/share/pcb/examples/skill/form directory.

Some of the examples available in this directory include the following:

Example	Description
Basic controls: axlform.il/axlform.form	This example includes all the GUI elements that you can use in Allegro SKILL-generated GUI, including: Textboxes to specify information in string, integer, or float format Types of buttons, such as radio buttons and checkboxes Click buttons, such as OK or CancelTabs Tree view
Grid control: fgrid.il/fgrid.form	This example is for creating a GUI with a table-like control called grid control.
Multi-select grid control: fgrid-msel.il/fgrid.form	This example is for creating a GUI with table-like control called grid control with multiple elements selected.

The following images display examples of GUIs with basic controls:

skill_basic_control

skill_form_button

How to Use Example Files

To use the example files, perform the following steps:

Copy all the SKILL code files to a local directory.
Start Allegro PCB Editor.
Load the SKILL file (axlform.il) for the Basic Control GUI in the Command window. Enter the following in the Allegro PCB Editor command line:
skill load "axlform.il"
Invoke the Basic Control GUI by calling the main function formtest. Enter the following statement in the Allegro PCB Editor command line:
skill formtest

Explore other SKILL codes and the Form files to understand how the Allegro SKILL GUI works.

Sample Form File

A sample Form file to create a GUI is provided in the installation folder. For user interactions, the sample form includes Cancel, OK, Print, and Script buttons. The GUI also includes a list field to show a list of files and a field for View File to display the file selected from the list of files.

Sample Allegro SKILL form file

SKILL File

The following SKILL code uses this sample Form file:

; myExtractViews.il
; -- Displays a form with a selection list of
; the available extract definition files
; -- Lets the user select any of the files on
; the list as the “View file”
; -- Starts Allegro extract process with the
; user-selected View file when
; the user picks Done from the form.
; Function to extract user selected view to the output file.
(defun myExtractViews (viewFile outFile)
axlExtractToFile( viewFile outFile)
); defun myExtractViews

; Function to start the view extraction
(defun _extract ()
myExtractViews(
buildString(list(nth(2 parseString(axlGetVariable("TEXTPATH"))) selectedFile) "/")
"myextract.dat")
); defun _extract

; Form callback function to respond
(defun _formAction (form)
   printf("form->curField %L form->curValue %L" form->curField form->curValue)
(case form->curField
     ("done"
           (axlFormClose form)
           (axlCancelEnterFun)
           (_extract)
     t)
     ("cancel"
     (axlFormClose form)
     (axlCancelEnterFun)
nil)
("view_file"
     (if form->curValue
           (progn
           ; Accept user input only if on list
           if(member( form->curValue fileList)
                then axlFormSetField( form
                "view_file" form->curValue)
                else axlFormRestoreField(
                form "view_file"))))
         t)
     ("file_list"
     (axlFormSetField form "view_file"
form->curValue)
     selectedFile = form->curValue
     t)); case
); defun _formAction
; User-callable function to set up and
; display the Extract Selector form
(defun myExtract ()
fileList = (cdr (cdr (getDirFiles car(last( parseString( axlGetVariable("TEXTPATH")))))))
     printf("fileList is %L" fileList)
     form = axlFormCreate( (gensym)
     "extract_selector.form" '("E" "OUTER")
     '_formAction t)
     axlFormTitle( form "Extract Selector")
     axlFormSetField( form "view_file" (car fileList))
     selectedFile = (car fileList)
     foreach( fileName fileList
     axlFormSetField( form "file_list" fileName))
     axlFormDisplay( form)
); defun myExtract

Wrapping Up

The Allegro SKILL GUI APIs let you customize the design environment according to your specific requirements. By seamlessly integrating the SKILL-generated GUIs into your workflows, you can streamline complex tasks, enhance collaboration, and achieve greater design precision.

Contact Us

For any feedback or any topics you want us to include in our blogs, write to us at pcbbloggers@cadence.com.

Subscribe to stay updated about our upcoming blogs.

About BoardSurfers

The BoardSurfers series provides solutions to the various tasks related to the creation and management of PCB design using the Allegro platform products. The name and logo of this series are designed to resonate with the vision of making the design and manufacturing tasks enjoyable, just like surfing the waves. Regular, new blog posts by experts cover every aspect of the PCB design process, such as library management, schematic design, constraint management, stackup design, placement, routing, artwork, verification, and more.