User Interaction and Error Handling

User Interaction

There are three classes in the Script interface used to show the user an interactive window during the execution of the script. These are used to obtain an input or to choose between options:

• QInputDialog: Used to obtain input.
• GAnyObjectChooser: Used to choose an option from a list.
• GKTask: Used to show progress on a lengthy task.

QInputDialog

The QInputDialog class has methods that show a dialog to get input from the user. Each method is appropriate for one type of data the user is to provide and produces a different kind of input dialog:

• getDouble: produces a spin box to edit a floating-point number.
• getInt: produces a spin box to edit an integer number.
• getItem: produces a drop down list.
• getText: produces a text input box.

All the methods return a tuple whose first element is the input from the user and the second is True if the user pressed OK and False if the user pressed Cancel or closed the window. It is good practice to check if the user pressed OK rather than cancelled the selection before using the value obtained.

An example that produces the input dialog below is shown here.

dialog = QInputDialog.getText( None, "Geocode", "Project location:" )
if dialog[1] == True:
    location = str(dialog[0])

GAnyObjectChooser

GAnyObjectChooser presents a list of all the objects of a certain type present in the model so the user can choose one or more objects.

Create a new GAnyObjectChooser object by calling the constructor, then define the objects type of objects to be shown and whether to allow the user to choose only one or more using the setType method.

Next, show the dialog by calling execDialog. This method returns 1 if the user pressed OK and 0 if the user pressed Cancel or closed the window. It is good practice to check if the user pressed OK and interrupt the code execution otherwise.

Finally, obtain the user input calling getObject or getObjects. Note that one of the options presented to the user is None and this option must be included in the actions taken.

An example that produces the input dialog below is shown here:

dialog = GAnyObjectChooserEditor()
type = model.getType( "GKODMatrix" )
dialog.getChooser().setType( model, type, GAnyObjectChooser.eOneObject )
if dialog.execDialog():
    matrix = dialog.getObject()
    if matrix != None:
        # A matrix was chosen ( i.e. not the none option)
        # We can now do whatever was intended with the *matrix* object

GKTask

If a script performs sequence of operations that takes some time, create a task (GKTask) to show a progress dialog that gives the user feedback on the amount of time required to complete the operation and allows the process to be cancelled.

An example that produces the dialog below is shown here.

task=GKSystem.getSystem().createTask(model)
task.setName("MyTask")
totSteps = 10000000
task.setTotalSteps(totSteps)

task.start()
step=0
cancelled=False

while step < totSteps and not cancelled:
    # Do something that takes some time
    step+=1
    cancelled=task.stepTask( step )

task.end()

Errors and Logging

To report critical errors, the GKModel::reportError method can be used. When a GUI is present, a message box will be displayed. If no GUI is present (when using Aimsun Next Console mode), the message is written in the command prompt window.

model.reportError("Aaaargh!", "Something bad has happened")

More general logging functionality is available through GKLog. Both the model and the system maintain their own logs. Logging is available at four levels, these being Text, Info, Warning and Error

#log info in the model log
model.getLog().addInfo("Task Done")

#log an error in the model log
model.getLog().addError("Something is wrong")

#place a warning system log
GKSystem.getSystem().getLog().addWarning("Error logged in the model")

The system log is always available (as it is the ANGConsole log), the model log is only available when a model has been loaded

Troubleshooting

If the following error or a similar one is displayed when launching a script:

Python Error (): No module named xlrd

Add the following code before the import line.

SITEPACKAGES = "C:\\Python37\\lib\\site-packages"

if SITEPACKAGES not in sys.path:
sys.path.append(SITEPACKAGES)

from xlrd import *
from win32com.client import Dispatch