Open Parameter Visibility
In trCAD, open parameters are variables that can be interactively set by the user through a user interface (UI) or a controlling application. The visibility of an open parameter determines whether its value is communicated to the UI and preserved during consecutive calls.
The visibility of open parameters is controlled using the expose_opar attribute for individual open parameters and the document.expose_opar variable for packages. These can have one of three values:
- -1: Do not expose open parameters.
- 0: Expose only those open parameters that have been requested (see below) during execution. This is the default value if no other value is given.
- 1: Expose open parameters.
Requests and Automatic Visibility
By default, the expose_opar value is set to 0. This means that only open parameters whose values have been requested during execution are exposed. A request is generated by the system when a value of an open parameter that has not been set earlier is used (read) within the script. If the value was set in the script explicitly, no request is generated.
This concept of automatic visibility ensures that the UI is not cluttered with parameters that are not actively used.
Example
open int param1 {
name = "Parameter 1"
descr = "This parameter's visibility depends on its usage."
value = 10
}
open int param2 {
name = "Parameter 2"
descr = "This parameter's visibility depends on its usage."
value = 10
}
param1 = 7 // Parameter 1 is set
int j = param1 // Parameter 1 is used but not requested. The parameter stays invisible.
int k = param2 // Parameter 2 is used and needs to be requested. It gets visible.
Note
Open parameters that have been shown in a session once will remain visible until the end of the session. This ensures that their set values are not forgotten, even if they are set to "not visible".
Hiding and Exposing Open Parameters
Open parameters can be actively hidden or made visible by setting the expose_opar value to -1 or 1, respectively. This value can be set using the document.expose_opar variable or as an expose_opar attribute of the open parameter. If both settings are present with different values, the attribute value takes precedence. The following example makes parameter param1 invisible and param2 visible:
Example
open int param1 {
name = "Parameter 1"
descr = "This parameter is invisible due to the 'document.expose_opar' value."
value = 10
}
open int param2 {
name = "Parameter 2"
descr = "This parameter is visible due to its 'expose_opar' attribute."
value = 10
expose_opar = 1
}
document.expose_opar = -1
Bubbling and Overriding Visibility
The visibility of an open parameter within an imported package follows the same principle. The open parameter will be visible if either its expose_opar value is set to 1, or if this value is set to 0 (or not set at all, as this is the default value) and the open parameter is requested at least once during execution. This behavior of showing lower-level open parameters in the program output is called "bubbling."
Overriding Visibility Rules
To allow more control over the visibility of lower-level open parameters, the document.expose_opar variables and expose_opar attributes of imported packages can be overridden by higher-level packages. The rules for overriding are as follows:
- A higher-level package can override the document.expose_opar variable of a lower-level package.
- A higher-level package can override the expose_opar attribute of a lower-level open parameter.
- If either the document variable or the attribute of a lower-level package is overridden by different higher-level packages, the value set by the package of the highest level takes precedence.
- A value of -1 cannot be overridden by higher-level packages.
The following is an example of overriding.
File "lvl1.sps":
Example
open int myparam
{
name = "My parameter"
descr = "Example parameter"
value = 0
expose_opar = 0 // Setting open parameter attribute 'expose_opar'
}
document.expose_opar = 1 // Setting document variable 'expose_opar'
File "main.sps":
Example
#import ("lvl1.sps")
lvl1::expose_opar = 0 // Overriding document variable 'expose_opar'
lvl1::myparam.expose_opar = 1 // Overriding open parameter attribute 'expose_opar'
By understanding and utilizing the visibility rules, developers can effectively control which parameters are exposed to the user. This ensures that their values are preserved as needed while still adhering to the stateless nature of the system.
Usage Example 1: Cloaking a Package
In this example, a package is imported that generates a solid based on two open parameters param1 and param2. The solid is generated multiple times with different values of param1. The package is not allowed to make either open parameter visible.
Example
#import ("pack.sps")
pack::expose_opar = -1 // Do not show any open parameters of "pack.sps"
pack::param1 = 20.0 // Set one open parameter of "pack.sps"
make pack::main // Create pack solid with previously set parameter
pack::param1 = 10.0 // Set open parameter of "pack.sps" to another value
make pack::main // Create pack solid with second set value
Usage Example 2: Exposing a Package with Exceptions
The following script exposes all but one open parameter of an imported package and cloaks all open parameters of the main package:
Example
#import ("pack.sps")
document.expose_opar = -1 // Do not show any open parameters of this package
pack::expose_opar = 1 // But show all open parameters of the imported package
pack::param1.expose_opar = 0 // Except one whose visibility depends on its requested state
Note
The former functions get(), set(), and the do / catch construct for controlling open parameters have been marked deprecated. The mechanism presented on this page should be used instead.
