Setting up GUI Options

The Netlist Exporter manual describes the netlist exporting dialog. The dialog has a command button labeled Modify Option List . When you click it, a file named cnexOptions loads in the location specified by the path in CNEX_EXPORT_FILE_PATH. The GUI Option dialog creates this file, the content of which depends on the tool you have chosen. The cnexOptions file loaded by the GUI dialog overrides the default version of cnexOptions that comes with Front End Flow.

Note A working knowledge of AEL programming is required to setup GUI options.

Option List Global Variable

The Front End Flow API function cnexExportNetlistHeader outputs netlist lines at the beginning of the netlist file. The header lines include comment lines, file includes, and global option statements.

The function cnexExportNetlistHeader collects the global option statements from the global variable cnexExportOptionList . This variable contains one text entry for each option line that appears in the netlist.
The following list shows some netlist options for various tools:

• Dracula: *.BIPOLAR
• HSpice: .TEMP 25
• ADS: Options ResourceUsage=yes
  To output an option into the netlist file, the global option variable, cnexExportOptionList must have a line that specifies the option.

For example, to get the *.BIPOLAR option to appear in the header of a Dracula netlist file, write the following line:

cnexExportOptionList=list("*.BIPOLAR");

This causes a single option, *.BIPOLAR , to be output in the netlist header.
You can also add more options to the cnexExportOptionList variable by using the ADS append command as follows:

cnexExportOptionList=append(cnexExportOptionList, list("*.CAPVAL"));

This adds the option, *.CAPVAL , to the list.
The following method is recommended to build up your option list:

1. Read all of your options from a configuration file.
2. Use the append function to build up the final cnexExportOptionList.

Option List Global Variable for Dracula

In the cnexOptions file, Dracula has a function, cnexSetupDraculaOptions , that uses the ADS AEL function getenv to retrieve configuration file values. It then checks the values of the configuration variables and determines how to set up the global option variable, cnexExportOutputList .

The following code is an example of the use of cnexSetupDraculaOptions for conditional loading of options. The Dracula options used depend on the options in the global options list.

Making an Options List for Dracula

defun draculaConvertToBoolean(value)
{
   if(value == "1")
return(TRUE);
else
return(FALSE);
}
defun cnexCreateNetlistOptionList(value)
{
  cnexExportOptionList=append(cnexExportOptionList, list(value));
}
defun cnexSetupDraculaOptions()
{
cnexExportOptionList=NULL;
decl bipolar=draculaConvertToBoolean(getenv("bipolar", "dracula"));
if(bipolar)
{
cnexCreateNetlistOptionList\("\*.BIPOLAR");
decl capa=draculaConvertToBoolean(getenv("capa", "dracula"));
if(capa)

The function getenv(<option>, <file>) receives the specified option from the specified file name.
The function draculaConvertToBoolean checks to see if the value returned for a configuration variable is 1 . If it is, the value returned is the boolean TRUE value; otherwise, FALSE is returned. This function is needed because the getenv function will return strings, even if a value could be interpreted as a number.

Note If you request a configuration variable that does not exist with the getenv function, it will return NULL . Otherwise, the text value of the variable will be returned.

It is usually recommended that your option configuration file have the same name as the Front End Flow configuration file. However, this is not required because the configuration file name can be hard coded

It is recommended that you write a function that retrieves the options settings from a configuration file. That way, you can set the global options list up by calling the function anywhere within your own code.

Overriding the cnexNetlistDialogOptions_cb Function

Clicking the Modify Option List button in the GUI Option dialog calls the function cnexNetlistDialogOptions_cb . The default of this function that comes with the Front End Flow installation returns the following message:
There are no options for the tool <tool>

If you want the user to be able to see and modify available options for a tool, you will need to create a new cnexNetlistDialogOptions_cb function that provides a dialog window that allows the user to set up options graphically.

Note If you want end users to always use the same options, set up a file that is automatically included (see Setting Up Automatically Included Files). Put the options in the file with which you want the end user to work.

Function Prototype

Dialog windows are created in ADS using an extension to the AEL language called Layered API (LAPI). LAPI is a C++ based library that has wrappers to allow you to create dialog windows.
The prototype for the API callback function for dialog options is: cnexNetlistDialogOptions_cb(<object handle>,<data handle>, <window instance handle>) .
Example of the API callback function for the Netlist dialog options window :
cnexNetlistDialogOptions_cb(buttonH, mainDlgH, winInst)

• The first argument passed is the handle of the object that initiated the callback function. For this function, the object is the Modify Option List button.
• The second argument in an API callback is a data item. For this function, the handle to the Front End Flow netlist dialog has been passed.
• The third argument for a LAPI callback is a window instance handle. Dialogs are associated to certain windows. In this case, winInst will point back to the schematic window that was used to bring up the Front End Flow netlist exporting dialog.

  Note You must use this exact protoype.The Front End Flow netlist exporting dialog always calls the function cnexNetlistDialogOptions_cb which always uses the same three arguments.

  Note To get further information on LAPI, contract Agilent for a special training class with Agilent Technologies Solution Services group.

Creating a Dialog Box

The command api_dlg_create_dialog creates a new dialog box and returns the dialog handle. The command has eight arguments. You must specify the first two, the remaining six are optional.The optional arguments specify elements of the dialog box.

Example of the Function Call

decl dlgH=api_dlg_create_dialog (dlgName, winInst, ...<the six optional 
arguments>)

Required Arguments

dlgName

This argument assigns the name for the dialog box.

winInst

This argument specifies the window instance. Use the instance passed in the cnexNetlistDialogOptions function.

Optional Arguments

API_RN_CAPTION

This specifies the text displayed in the dialog banner. It must be a text value.

Usage: API_RN_CAPTION, "My Option Dialog",

API_RN_ORIENTATION

This specifies whether the dialog is laid out horizontally or vertically. Horizontal layout means that when you specify a new dialog item it is placed next to the prior dialog element. Vertical layout means it is placed below.
A vertical layout is recommended for a dialog.

• Specify API_RV_VERTICAL for a vertical layout.
• Specify API_RV_HORIZONTAL for a horizontal layout.

Usage: API_RN_ORIENTATION, API_RV_VERTICAL

API_RN_DEFAULT_OPTIONS

This allows you to specify what table options the dialog box elements inherit from the parent dialog.
It is recommended to always specify this as API_RV_TBL_LEFT .

Usage: API_RN_DEFAULT_OPTIONS, API_RV_TBL_LEFT,

API_RN_TBL_OPTIONS

This specifies the table options for the dialog box. Dialog box elements also inherit these options.
It is recommended to use API_RV_TBL_LK_HEIGHT|API_RV_TBL_SM_HEIGHT . This forces the dialog to use the smallest height possible, and does not stretch dialog elements to fit the dialog space.

Usage: API_RN_TBL_OPTIONS,API_RV_TBL_LK_HEIGHT|API_RV_TBL_SM_HEIGHT,

API_RN_RESIZE_MASK

This specifies the resizing mask.
It is recommended to specify API_RV_DLG_MIN_WIDTH|API_RV_DLG_MIN_HEIGHT , so that the dialog is created with the minimum possible width and height.

Usage: API_RN_RESIZE_MASK,API_RV_DLG_MIN_WIDTH|API_RV_DLG_MIN_HEIGHT,

API_RN_MODE_TYPE

This specifies whether the dialog is modal or non-modal.
For the Front End Flow options dialog box specify API_RV_MODAL_DIALOG so that the dialog box is modal.

Usage: API_RN_MODE_TYPE, API_RV_MODAL_DIALOG,

Creating Dialog Box Elements

Dialog box elements are objects. Dialog box elements, or objects, include labels and tables, which can also be used to help make command buttons.The Layered API functions used to create dialogs and dialog elements are described in Layered API Functions.

The command to create dialog elements is the Layered API function api_dlg_create_item .

Syntax

api_dig_create_item(name, type, [resource, value, ...], [itemH, ...])

• The first argument is the name of the dialog element. Use a unique name for the dialog so that you can retrieve the element by name in other code.
• The second argument is an enumerated integer that defines the type of dialog component. There is a list of the dialog element types in Layered API Dialog Elements.

• The last argument space, [itemH, ...] is used an option argument used for placing children in the dialog object, if that object supports them. It is not treated in this discussion.
• The third argument space, [resource, value, ...] , defines the dialog elements or objects. Some examples of making dialog elements follow.

An Empty Label Dialog Element

To create an empty line label, in order to space a dialog out vertically, the following code could be used:

api_dlg_create_item("labelSpace1", API_LABEL_ITEM, API_RN_CAPTION, "")

Table Elements

Use table elements when you want to group several elements of a dialog box on the same row, or several elements in the same column.
There are three basic steps to defining table elements using the api_dlg_create_item call.

1. Set the orientation of the table elements.
   If you items to appear in the same table row, specify a horizontal orientation by entering API_RN_ORIENTATION, API_RV_HORIZONTAL . If you want elements to be in a column, specify a vertical orientation by using API_RN_ORIENTATION, API_RV_VERTICAL.
2. Add dialog elements to the table.
3. Put a framing box around the dialog.
   This increases legibility. If you specify API_RN_CAPTION, the table will automatically have a framing box drawn around it. If API_RN_CAPTION is empty, you must specify API_RN_FRAME_VISIBLE, TRUE to have the framing box drawn.
   The following code creates a table that contains OK and Cancel command buttons at the bottom of the dialog box:

   api_dlg_create_item ("actTabl", API_TABLE_GROUP,API_RN_ORIENTATION, 
   API_RV_HORIZONTAL,API_RN_EQUALIZE_ALL, TRUE,API_RN_DEFAULT_OPTIONS,
   API_RV_TBL_FIX_SIZE,API_RN_TBL_OPTIONS,API_RV_TBL_FIX_HEIGHT,
   pbOkay = api_dlg_create_item ("pbOkay", API_PUSH_BUTTON_ITEM,
   API_RN_CAPTION, "OK"),
   pbCancel = api_dlg_create_item ("pbCancel", API_PUSH_BUTTON_ITEM,
   API_RN_CAPTION, "Cancel")
   )

   

The Result of the Call to the api_dlg_create_item Function

• The orientation of the table is set to API_RV_HORIZONTAL , which causes the two command buttons to be placed on the same row.
• Two buttons are created in the table by making calls to api_dlg_create_item .
• The variables pbOkay and pbCancel are set as the return values of api_dlg_create_item .

Adding Callback Functions to Dialog Elements

Callback functions add an action to the dialog elements or objects. For example, if you click on the OK button, you want a callback function to be executed that will save the options and dismiss the dialog box.
The command to create dialog elements is the Layered API function api_dlg_add_callback .

Syntax

api_dig_add_callback(itemH, functionName, callbackType, callabckData)

Example

This api_dig_add_callback function adds action to the OK command button object created on page 5-7. The OK action saves the options and dismisses the dialog.
api_dig_add_callback(pbOkay, "cnexOptionDialogOkay_cb", API_ACTIVATE_CALLBACK, list(dlgH, tool))

• The first argument is the handle to the dialog element to which you want to add the action. The variable pbOkay contains the handle to the OK command button item.
  The pbOkay handle is the first argument passed passed to the callback function specified in the second argument.

  Note You cannot specify the text name of your dialog item as the first parameter. Layered API functions will not automatically search for your dialog element in memory based on the name.

• The second argument is a string value that designates the name of the callback function to be called when the object is activated. In the example it is cnexOptionDialogOkay_cb .
• The third argument is an enumerated integer that specifies how the object is activated. Each Layered API dialog element supports different triggers.

In the example, API_ACTIVATE_CALLBACK is specified for the pbOkay button. The callback function is activated whenever the OK command button is clicked.

Note Refer to Layered API Dialog Elements for more information on which triggers are available for certain dialog elements.

• The final argument is a pointer to an AEL data list that is the second argument passed to the callback function.
  The data list contains dlgH , which is a handle to the option dialog, and tool, which is a variable that is set when you choose the tool for this dialog. You can retrieve the values in this list with the following code which uses the nth function:

  defun cnexOptionDialogOkay_cb(buttonH, cbData, winInst)
  {
     decl dlgH=nth(0, cbData);
     decl tool=nth(1, cbData);
  .
  .
  .
  }

  Displaying the Dialog

  After the dialog has been created, and all of the callback functions have been added to the dialog, the dialog can be displayed using the following command:

  api_dlg_manage(dlgH)

  This should be the last function call.The dialog box is modal, therefore no commands will be executed after the api_dlg_manage function has been called. All callbacks must be set up prior to displaying the dialog.

Closing the Dialog

The options dialog box is modal. A modal dialog box takes the input focus and does not allow you to work on anything else until the dialog box is dismissed.
The command to close the dialog box is the function api_dlg_unmanage .

Syntax

api_dlg_unmanage(dlgH)
The one argument, dlgH , is the handle to the dialog box to be closed.
The dialog box does not allow you to type in commands, therefore you must set up one or more dialog elements to have callback functions that will call the api_dlg_unmanage command. Typically, you use the OK and Cancel buttons for this.
The following code adds the close action to the Cancel command button in the dialog elements created in Table Elements:

api_dlg_add_callback(pbCancel, "cnexOptionDialogCancel_cb", 
API_ACTIVATE_CALLBACK, dlgH);

This causes the function cnexOptionDialogCancel_cb to be called any time the Cancel button is clicked. The data argument passed to the function cnexOptionDialogCancel_cb will be the dialog handle.

The definition for the cancel function is then set up as follows:

defun cnexOptionDialogCancel_cb(buttonH, dlgH, winInst)
{
api_dlg_unmanage(dlgH);
}

When the api_dlg_unmanage function is called, the dialog box is closed.

Saving Options to a Configuration File

Once the user has chosen the options they wish to set, perform the following steps:

1. Make certain that the global options list gets set up properly.
   This is discussed in Option List Global Variable.
2. Store the settings into a configuration file.

   Note If stored in the configuration file, the user will not need to set up the options each time they make a netlist.

Getting the Values of the Dialog Box Elements

You need to be able to get the value of a dialog box element in order to know the state of that element. For example, the value of a text box is the text that has been entered. The value of an option button object, or element, tells you if that button has been selected or not.

There are two parts to getting the value. First, you must get the handle of the object whose value you want. The Layered API function for this is api_dig_find_item . Second, after you have the object handle, you must get the value from the object. The Layered API function for this is api_dig_get_resources .

Note Once you get the object handle, you can also use it in other commands such as api_dlg_add_callback .

The syntax for the function to get the object is as follows:
api_dig_find_item(dlgH, name)

• The first argument, dlgH , specifies that you are requesting the object handle.
• The second argument, name , specifies the name of that object.
  The syntax for the function to retrieve the value is as follows:
  api_dig_get_resources(itemH, resource, value)
  The first argument, itemH , is the object handle.
  The second argument, resource , an an enumerated integer value that designates the resource value you want to retrieve.
  The third argument, value , gets the value of the specified resource by going to the address of the value.

  Note AEL, like C, uses an ampersand ( & ) prefix to designate the address of a variable.Thus, to pass the address of a variable to a function, you use the code &name and not name .

Retrieving the Value of a Dialog Box

The following code retrieves the toggle state an option check box named bipolar :

decl itemVal;

decl bipolarH=api_dlg_find_item(dlgH, "bipolarH");

api_dlg_get_resources(bipolarH, API_RN_TOGGLE_STATE, &itemVal);

• In the first line, the itemVal variable is declared which will hold the value retrieved from the dialog element.
• In the second line, the handle to the dialog object is retrieved using the api_dlg_find_item function.
  When the bipolar check box item was created, it was named bipolarH . This is the name used to retrieve the handle to that object. Once the handle to the object has been retrieved, that handle is used to get the value of API_RN_TOGGLE_STATE by using the function api_dlg_get_resources .
• In the third line, the address of itemVal is passed into the function. After the function returns, the variable itemVal can be accessed to determine whether the check box was checked or not.

Writing a Value to a Configuration File

You can save retrieved values to a configuration file by using the setenv command. This command writes a configuration file in the current working directory. For ADS, the current working directory is always the directory that contains the currently open project.

The setenv command has four arguments:

• The first argument is the name of the configuration variable. The name you use must match the name of the object from which you retrieved the value. In the example above, the name is bipolar . The argument must be a text string.
• The second argument is the value. In the above example, the value is stored in itemVal . This value must be a string.
  Use the is_string function to determine if the value is a string.
  If the value is not a string, use the identity_value function to convert it to a string.
• The third argument is the name of the configuration file where you want to store the value. This is a text name, and should not include the .cfg extension. The extension is added automatically.
• The fourth argument specifies the directory where you want to save the configuration file. However, for options, it is recommended that you save the file in the directory that contains the current object. The file is stored there automatically if you leave out this argument. Therefore, do not fill in this space.

  Note If the configuration file does not exist, setenv will make it automatically. If a value already exists in the configuration file, the setenv command will overwrite it.

Writing a Value to a Configuration File

The code in Retrieving the Value of a Dialog Box Element got the state of the bipolar check box. The code below stores that value in a configuration file using the name bipolar .

if(is_string(itemVal))
setenv("bipolar", itemVal, "dracula");
else
setenv("bipolar", identify_value(itemVal), "dracula");

The first line uses the is_string function to see if itemVal is a string. In this case it is not because it is a Boolean value, a integer value of either 0 or 1 .

Control branches to the last line. The setenv command goes to the object named bipolar . The command then reads the value in itemVal and, using the identify_value command, converts it to a string.

The command sends the value to a configuration file named dracula . The command automatically adds the file extension .cfg which denotes a configuration file.

Summary

These are the steps to make your own custom options dialog:

1. Create an cnexOptions.ael file in a directory appropriate for your tool.
2. Write a function that can retrieve option settings from an ADS configuration file.
3. Write a customized cnexNetlistDialogOptions_cb function.
4. Write a function that can save the data in the dialog to an ADS configuration file.
5. Write a function that can close the dialog.