GUI Control Types

Attributes in a class define the properties of the objects in the class. In SansGUI, a property is an attribute-value pair. Variables are used to implement attributes in the class for what types of values they can accept. An example is the hair color of people. In this case, people is the class, hair color is an attribute, and blonde, red, black, etc. are the possible values of the attribute, which may be implemented as an integer variable in the simulator. SansGUI supports the following graphical user interface control types for users to enter and view data: number, string, URL / file, date, time, on-off, tri-state switches, enumerated items, object reference, quality, and symbolic parameter. An Input Assistant can be obtained by right clicking on a data input field, except for special controls such as date, time, on-off, tri-state switches, or enumerated items, and select Input Assistant from the context menu. There is also a Qualitative Input Assistant, available by clicking on the Quality... button in the Input Assistant, for users to specify values in qualitative terms, such as small-medium-large, and then map the selected rank to a range in the numerical scale. More on the Input Assistants can be found in the Entering Values section of the User's Guide.


Numbers supported in SansGUI are integers and single or double precision floating point real numbers. There may be validation rules defined by the simulation developer for default, minimum, maximum values, non-zero checking, and currency format display. Numbers can be entered in regular decimal format (such as 1, -1.0, or .5) or with scientific notation (for example, 1.0e3, or -2.3e-2).

Some fields may allow short vectors or matrices of numbers. They are entered with enclosing brackets [ ] and with numbers separated by spaces or commas (,). For two-dimensional matrices, a semi-colon (;) is used to start a new row. A matrix can be ended with a single quote character (') for automatic transposition. Examples are:


Strings may be regular, masked or encrypted. The masks of strings, such as phone number (###)###-#### for (123)456-7890 or social security number ###-##-#### for 123-45-6789, are defined by the simulation developer. Encrypted strings, as in password fields, are not displayed nor are they saved in their original values. Instead, they are displayed with asterisks (*) and saved with encrypted values. Regular strings can be entered by typing in the string itself, or starting with a double quote (") or a single quote (') character. Entering the end quote for a string is optional. The begin and end quotes will not be included in the value of the string. When a string is entered with a starting double quote character, all the double quote characters in the string are converted to hyphens (-). Same rule applies to a single quote started string. One special case in handling double quote characters in a string is when the string is written out to a textual Model File, which uses double quotes for string encapsulation at all times. In such cases, all double quotes in strings are turned into single quotes.

URL / File

Uniform Resource Locators (URLs, such as, file names, or file paths (local or network, absolute or relative) are entered by starting with a < character. The ending > character is optional and will be appended if not entered. The value is displayed in green, indicating that it is a hyperlink to the URL or file. Double clicking on the value or selecting the Open menu item from the right click context menu will open the URL or file using the associated Windows program. The user can browse through the network or local directory structure via the Input Assistant. Entering *.* in the file name field of the File Dialog will select the directory into the field instead of a file.

Date / Time

When a date field is active, a set of up-down arrow buttons and a bigger down arrow button are displayed at the right end of the field. The set of up-down arrow buttons controls each of the highlighted sub-field of the date, such as month, day, or year. Clicking on the bigger down arrow button to invoke a date chooser in a drop down window.

When a time field is active, a set of up-down arrow buttons is displayed at the right end of the field. Use these two buttons to adjust the time in hour, minute, second, or AM/PM when each of these sub-fields are highlighted.

The keyboard short-cut for entering the first sub-field in a date or time control is the space bar. After entering the first sub-field, use left and right arrows to move between the sub-fields and up and down arrows to adjust the value. To drop down the calendar in the date field, use the Alt-DownArrow keyboard short-cut.

On-Off Switch

An on-off switch is represented by a check box. A checked box represents the on state and an unchecked box represents the off state. One can click directly on the check box or use the space bar to toggle between the on and off states.

Tri-State Switch

A tri-state switch is also represented by a check box. It has, however, three possible values: -, 0, +; for negative, neutral, and positive states, respectively. One can click directly on the check box or use the space bar to toggle among the three states.

Enumerated Items

Enumerated items are a list of items for users to select from. SansGUI supports single selection only. The list of items is specified by the simulation developer. The list can be expanded by clicking on the down arrow to the right of the field when the field is active. The keyboard short-cut for dropping down the selection list is Alt-DownArrow.

Object Reference

An object reference is the name string of a reference object without any enclosing characters. When the object name is unique in the whole Project Model, the name by itself is sufficient. When the name is not unique, then the whole object name with its deriving class path has to be entered. An easier way to specify an object reference is to use the Reference Object... button in the Input Assistant. However, the reference object has to exist before it can be listed in the selection. The object reference is displayed in blue. Double clicking on the value will jump to the Object Properties dialog for the reference object, if it exists; otherwise, a new Object Properties dialog will be displayed for creating the reference object. Circular references may exist and is not detected by SansGUI.


A quality value is represented by a vector of [Rank ConfidenceFactor] pair. The Rank of a quality is an integer from -3 to +3 (totaling 7 ranks) and the ConfidenceFactor is a real number from 0.5 to 1.0, inclusively. The ranks are identified by three thresholds, low, neutral and high, defined by the simulation developer. For example, the temperature of a room can be cold, normal and hot with the rank value -2, 0, and +2, respectively. The other rank values are for out of range and in-between phases:

The confidence factor indicates how much confidence the rank is decided. The value cannot be less than 0.5 because it would indicate another rank with a more than 0.5 confidence factor. The 1.0 confidence factor implies 100% sure about the rank being present. The quality space definition of an attribute can be found in the Quality Input Assistant accessed via the Input Assistant. When the thresholds are defined with numerical values, the Quality Input Assistant helps the user choose a numerical value from a range mapped by the selected rank and confidence factor.

Symbolic Parameter

The symbolic parameter is a powerful feature in SansGUI. When the simulation developer specifies a field to allow a symbolic parameter, the simulation user can enter a name string enclosed by a pair of curly braces { } as its value. It serves three purposes:

When the user types in a symbolic parameter in a value field, SansGUI will check if it conflicts with any existing parameter. One compatibility rule is that the new parameter and the existing parameter should have the same unit of measure and the same value ranges required by the simulator. Circular reference of symbolic parameters is not allowed and will be detected by SansGUI whenever the user introduces a new parameter.

Cell and Array Attributes

An attribute that allows its value to occupy a single cell in the graphical user interface is a cell attribute. An array attribute occupies more than one cell. For example, attributes in matrices or tables are array attributes. An attribute that allows the user to type in a vector or matrix, but still confined in a single cell, is a cell attribute.


C:\FH_Suite\htmlgifs\home.gif Components and References User Extensible Unit Conversion

SansGUI Modeling and Simulation Environment Version 1.2

Copyright 2000-2003 ProtoDesign, Inc. All rights reserved.