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.
Open parameters are not visible by default if they are not used within the script. This helps to maintain a clean and user-friendly interface. In complex projects, where numerous open parameters are defined, exposing all parameters by default could lead to a cluttered and overwhelming UI. This could be particularly problematic when multiple packages are imported, each with its own set of numerous open parameters that are only used in parts. By making open parameters invisible by default, trCAD ensures that only those parameters that are pertinent to the script's execution are presented to the user, thereby enhancing the overall user experience by avoiding unnecessary complexity and confusion.
A consequence of the stateless design of trCAD is that values of open parameters are not preserved between consecutive calls if they are not made visible. When an open parameter is visible, its value is communicated to the UI or the controlling application, which then provides it back to the script in the subsequent call.
The following example demonstrates how to manage the visibility and preservation of open parameters:
Example
open bool toggle {
name = "Switch"
descr = "Used to switch between program flows."
value = true
}
open int myParameter {
name = "Parameter"
descr = "This parameter's visibility depends on the toggle state."
value = 10
}
int j = 0;
if( toggle )
{
j = myParameter; // myParameter is used and visible, its value is preserved.
}
else
{
j = 15; // myParameter is not used and thus not visible, its value is not preserved.
}
// Ensuring visibility and preservation of myParameter regardless of the toggle state
get( myParameter );
Note
It is important to note that if an open parameter is not made visible, its value is not preserved and changes previously made by the user will get lost.
By understanding and utilizing the visibility rules, developers can effectively control which parameters are exposed to the user and ensure that their values are preserved as needed, while still adhering to the stateless nature of the system.
Visibility Rules
The visibility of open parameters is governed by the following rules:
- An open parameter is not visible by default if it is not used within the script.
- Reading the value of an open parameter during script execution automatically makes it visible.
- The get() function can be used to explicitly request the value of an open parameter, making it visible even if it is not otherwise accessed in the script.
- Writing to an open parameter without reading it does not make it visible. To write to an open parameter and make it visible simultaneously, use the set() function.
- To make all open parameters visible, set the document variable document.expose_opar to true .
The get() Function
The get() function is used to ensure that an open parameter is visible and its value is preserved throughout the session. It is commonly called immediately after the open parameter definition.
Example
open int myParameter {
name = "My Parameter"
descr = "An example open parameter"
value = 10
}
get( myParameter ) // Ensures visibility and preservation of value
The set() Function
The set() function allows you to set the value of an open parameter and ensure its visibility. It is particularly useful when you want to assign a new value to an open parameter and make it visible in one step.
Example
open int myParameter {
name = "My Parameter"
descr = "An example open parameter"
value = 10
}
set( myParameter, 20 ) // Sets the value to 20 and ensures visibility
