09. Parameter logic

Example file for this lesson can be downloaded here.

A GDL library part usually has some editable parameters open to user-settings, even if the objective of the creator was to model a real-life object. These parameters need to be set and maintained according to user interactions or the change of the environment.
The Parameter Script is the interface for setting up valid ranges, value lists and working connections between the parameters of an object.
By setting up rules in the parameter script, the complete coherency of all parameter values within an object at all times can be achieved. ARCHICAD helps maintaining the order by running and re-running the parameter script every time it is needed:

  • opening the Settings Dialog of an object
  • changing a parameter’s value in the settings dialog
  • editing a parameter via editable hotspots
  • stretching the object using conventional hotspots
  • loading step-by-step migration libraries
  • placing an object

The script re-runs every time parameter value is changed: if the change of a parameter changes the value of another parameter, the script runs again. This cycle is limited, but the creator of the script must pay special attention to keep it linear and as simple as possible. If an accidental loop is implemented, ARCHICAD stops the process automatically.
There is a way to force the parameter script to run only once: by checking the Run the parameter script only once option in the object’s Compatibility Options panel. This is only recommended in every object with clear parameter connections.

The script is not running when:

  • moving the object
  • changing scale
  • changing story
  • rebuilt

The actual parameter set of a placed object is stored in the planfile.
On the other hand, the parameters of a macro are not stored in the planfile and not accessible directly for the user, so the statements used in the parameter script of a macro affect the parameters of the caller object only (of course the Parameter Script of the macro has to be called from the caller object).

The following commands are used to manage the parameter set of a placeable object.

Value list definition
A parameter usually can not work with infinite number of valid values, so to keep your object in one piece, set up working value lists and ranges for your parameters.
The command for all this is VALUES.

Simple list: the user can choose from the preset list

values "paramName" value_1, value_2, value_3, ...value_n

If you want to use integer type as parameter (integers are evaluated faster in the script than string type expressions), but you want to have a description to represent the values (users prefer text to numbers), use the extended command (available from ARCHICAD 18):

values{2} "paramName" integerValue_1, "descriptionText_1",
	integerValue_2, "descriptionText_2",
	integerValue_3, "descriptionText_3",
	...
	integerValue_n, "descriptionText_n"

Example for integer type with description:

values{2} "chairType" 1, `Designer`,
	2, `Office`

Result value list in parameter list:
GDL_Basics_ParamLogic_V2
Used in 2D script:

if chairType = 1 then
	! do something for designer form
else
	!do something for office form
endif

More about strings and integer relations here.

Define ranges for parameter values using the range keyword and parenthesis/bracket combinations and step values:

  • ( – starting from but not including
  • ) – up to but not including
  • [ – starting from and including
  • ] – up to and including
values "paramName" range [leftThresholdLimit, rightLimit)
values "paramName" range (leftLimit, rightThresholdLimit] step startingValue, stepSize

An example of a pretty complex, but working value list:

values "par4" 4, range (5, 10], 12, range (,20] step 14.5, 0.5, CUSTOM

Notice the keyword CUSTOM here. It is an indicator for ARCHICAD to keep the value list open for custom user value input.

The best way to set up common value lists for font type parameters is to use a Library Master object (see the corresponding subtype). The value list should be declared in such object, and every other loaded library part will automatically inherit the value list if the parameter names are the same. This way you can save the repeated request of font type list of the current operation system:

! in Library_Master object
dim fontNames[]
request ("FONTNAMES_LIST", "", fontNames)
values "stFont" fontNames, CUSTOM

In any object containing the “stFont” parameter (string type), the value list will be filled automatically.

Changing the value of a parameter
The current values of parameters are stored for every placed object in the planfile. Since the parameter is represented by a variable in scripts, the value-change of the variable is not affecting the parameter itself unless deliberately forced to. To force-overwrite a stored value, use the PARAMETERS command:

parameters paramName = value

parameters paramName2 = value_2,
	paramName3 = value_3

This command does not change the variable representing the parameter, so make sure you keep the consistent:

paramName = value1
parameters paramName = paramName

Connections between parameters
The parameters of a geometric object are often linked to keep the proportion of the object (or any other required feature). To avoid loop-dependancy, use the GLOB_MODPAR_NAME global variable. This variable always contains the name of the parameter last modified by the user (case sensitive, so pay attention to capitals), and it is only available in parameter script context (settings dialog, hotspot editing, etc). Using this method you will be able to create connections between equally important parameters.
Lets say we have a stair we want to use 3 parameters:

  • hTread – height of tread
  • nTread – number of treads
  • ZZYZX – level difference for the stair

The height of the stair will be the most flexible parameter (which in not always true, we know). The number and height of treads will be used for the calculations:

values "ZZYZX" range (0, ) step hTread
if GLOB_MODPAR_NAME = "nTread" then
	ZZYZX = nTread * hTread
	parameters ZZYZX = ZZYZX
else
	nTread = ZZYZX / hTread
	parameters nTread = nTread
endif

How this script works:

  • the height of the whole stair (ZZYZX) always equals the tread height multiplied by a whole number (values command). So, if it is modified, it will always “jump” to the nearest value according to this rule
  • if the user modifies the number of treads (GLOB_MODPAR_NAME condition), the total height is recalculated according to the new number parameter
  • on the other hand, if the user is not editing the number of treads (else part of the condition), the nTread is always calculated from the actual height of total stair and individual tread (and always a whole number, thanks to values command)

Basically, there is some sort of preference in the parameters. The “strongest” one is hTread, both other parameters are calculated regarding its actual value.
The number of treads is somewhat “equal” to the whole height parameter, because one sets the other.

Lock, hide parameters dynamically
Depending on the complexity of the object, hiding parameters completely or just locking them may be necessary: some parameters only have meaning if other parameters are set to a specific value, or some parameters are only giving information of the current situation, but not eligible for change. To help user orientation, always make it clear if some option is available or not in the All Parameters list.
This is even more important in regard of user interface design. You can choose not to display something, or display, but locked, depending on the type of information the action provides.

To lock a parameter (and the connected UI element) use the LOCK command:

lock "newParam"

The connected display items will be inactive, but visible both on UI and All Parameters list.

To make a parameter completely disappear from the parameter list, use the HIDEPARAMETER command:

hideparameter "newParam"

On user interface, write conditions for the display/hide option.

To make the All Parameters list completely disappear from the Settings Dialog (except A-B-ZZYZX parameters on the info-box and the Preview and Positioning palette):

hideparameter all "A", "B", "ZZYZX"

This should be used only if the user interface contains all relevant parameters, so the provided simple list is not necessary.
Hidden parameters are always visible in the GDL editor. Lock affected parameters are visible and locked in the GDL editor as well.

Read more in The Parameter Script section of the GDL Manual.