View source for ChangeNodeVisibility

[[category:User-interface functions]]

''new to [[Analytica 5.0]]''

== ChangeNodeVisibility(obj, option'', what'') ==

This function can hide or show a node  in its Diagram, or display it as "disabled" -- i.e. grayed out to show it is not currently available. For example:
  ChangeNodeVisibility(A, 'Hidden')
hides the node for object A in its Diagram.  You can use it to create a dynamic user interface in which certain user inputs or user outputs appear or disappear based on the state of other user inputs. In such cases, you might use ChangeNodeVisibility() in the [[OnChange]] attribute of a checkbox or Choice menu user input to control whether other user inputs or outputs are shown. 

You can also use this function to query the current visibility state of the node. For example:
  ChangeNodeVisibility(A, 'Is Visible?')
returns true if node A is currently visible. 

=== «obj» parameter ===

The «obj» parameter is a handle to the node that you want to change or query. 

=== «option» parameter ===

Change the visibility state by setting the «option» parameter to:
* <code>"Hidden"</code>: The node is not visible in its parent diagram.  
* <code>"Disabled"</code>: The node is visible but disabled. It appears "grayed out" and does not respond to user input.
* <code>"Visible"</code>: The node is visible in the diagram user interface.
* <code>"Enabled"</code>: Synonymous with ''Visible'', but this parameter definition may be clearer to a reviewer if your interface is disabling and enabling user inputs (rather than making them visible or hidden).


While a "Hidden" node is invisible in its diagram, the object will still appear and its [[Object Window]] accessible in the [[Outline window]],  [[Find Dialog]], and links to it that might appear in results, or in inputs and outputs of other variables, etc. It also remains selectable on the diagram in edit mode, even though it is invisible. These options let you hide it more securely:
* <code>"Very hidden"</code>: Node is invisible in its diagram, the [[Outline window]], hierarchy stripe, [[Find Dialog]], etc. However, you can still hyperlink to it if a hyperlink exists.
* <code>"Extremely hidden"</code>: Set so that you can't reach the node via existing hyperlinks get to it from the Analytica UI in general. At this level, it appears to the end-user as if it doesn't exist

It is sometimes useful to hide (or disable) a node in Browse mode but enable it in Edit mode. Hence these options:
* <code>"Hidden in browse"</code>: Make the node is present and visible is edit mode, but does not appear on the diagram in browse mode.
* <code>"Disabled in browse"</code>: Make the node disabled in browse mode. It is enabled in edit mode.

These options let you query a nodes visibility state. (Note that they all end with a question mark.):
* <code>"Is Visible?"</code>: Returns true if the node is visible, and true if disabled but visible. False if not visible on influence diagram.
* <code>"Is Hidden?"</code>: Returns true if the node is hidden (not visible), true otherwise.
* <code>"Is Disabled?"</code>: Returns true if the node is hidden or disabled. True if visible and enabled.
* <code>"Is Enabled?"</code>: Returns true if the node is visible and enabled. False otherwise.
* <code>"How hidden?"</code>: Returns the option text describing the visibility state; <code>"Visible", "Hidden", "Hidden in browse", "Very Hidden", "Extremely hidden", "Disabled", </code> or <code>"Disabled in browse"</code>.

When you query the visibility state and specify «what» to be <code>'UserInputs'</code> or <code>'UserOutputs'</code>, the result is a 1-D array with a local index, where the local index contains the handles of each user input or each user output node, and the value is the result for that node.

=== «what» parameter ===

By default, if you omit «what», the functions changes (or queries) the visibility of the node for «obj».  But, you can also change the visibility of the user inputs or outputs for a Variable. You set «what» to <code>'UserInputs'</code> or <code>'UserOutputs'</code> to change the visibility of all inputs or all outputs of the variable. If you want to changed the visibility of a single user input or user output node, then you should ensure that this is a handle to the user input node, not a handle to the original variable node, and that «what» is omitted. You can also pass <code>'Original'</code> to «what» to change the visibility of the original (not the alias) of «obj».

== Examples ==

Hide, show, disable or re-enable the user inputs for variable <code>Gender</code>:
:[[ChangeNodeVisibility]]( [[Handle]](Gender), 'Hidden', 'UserInputs' )
:[[ChangeNodeVisibility]]( [[Handle]](Gender), 'Visible', 'UserInputs' )
:[[ChangeNodeVisibility]]( [[Handle]](Gender), 'Disabled', 'UserInputs' )
:[[ChangeNodeVisibility]]( [[Handle]](Gender), 'Enabled', 'UserInputs' )

Hide your model details module node from your end user:
:[[ChangeNodeVisibility]]( Handle(Model_details), 'Hidden in browse' )

Make visible user input nodes only when the user makes the choice to edit them. In this example, we augment the car cost model which begins in [[Tutorial: Create a model]]. With the following addition to the OnChange field, the user may change the estimated annual maintenance cost and the estimated miles driven per year:<br>
:<code>Variable := Choice(Self, 2, 0)</code><br>
:[[ChangeNodeVisibility]]( [[handle]](  Maintenance_cost  ), IF Self = 'No' THEN 'Hidden' ELSE 'Visible', 'UserInputs' );
:[[ChangeNodeVisibility]]( [[handle]](  Mpy  ), IF Self = 'No' THEN 'Hidden' ELSE 'Visible', 'UserInputs' )

:[[image:Onchange_example1.gif]]
:[[image:Onchange_example2.gif]]

== Example Video ==

<center>
<iframe width="640" height="360" src="https://www.youtube.com/embed/LshPSRoTl7o" frameborder="0" allowfullscreen></iframe>

'''Video:''' [https://youtu.be/LshPSRoTl7o Hiding and disabling UI elements] (5 minutes)
</center>

== See Also ==

* [http://lumina.com/blog/analytica-5.0-video-short-hiding-and-disabling-model-user-interface-control Analytica Video Short: Hiding and Disabling Model User-Interface Controls] on the Lumina Blog
* [[NodeInfo]] attribute
* [[OnChange]]
* [[OnClick]]