Merge pull request #3648 from ControlSystemStudio/script_pvs_doc

Update documentation on accessing PVs in scripts

Author: shroffk

app/display/editor/doc/access_pv_in_script.rst

@@ -8,8 +8,17 @@ Access PV in Script
 The input PVs for a script can be accessed in script via ``pvs`` object. The order of the input PVs in the
 configuration list is preserved in ``pvs``. ``pvs[0]`` is the first input pv. If you have N input PVs, ``pvs[N-1]`` is the last input PV.
 
-A button-type widget configured to execute script(s) should instead
-reference pvs using ``widget.getPV()`` or ``widget.getPVByName(my_pv_name)``.
+When using the ``pvs`` object, the display runtime will invoke the script once all PVs connected
+and then whenever those marked as a "Trigger" change.
+Scripts might also access PVs associated with a widget like this, but the preferred way
+is using ``pvs`` for PVs listed as script inputs.
+
+.. code-block:: python
+
+    from org.csstudio.display.builder.runtime.script import ScriptUtil
+    pv = ScriptUtil.getPrimaryPV(widget)
+    pvs = ScriptUtil.getPVs(widget)
+    pv = ScriptUtil.getPVByName(widget, "SomePVName")
 
 You can read/write PV or get its timestamp or severity via the utility APIs provided in ``PVUtil``.
 
@@ -20,16 +29,18 @@ You can read/write PV or get its timestamp or severity via the utility APIs prov
 .. code-block:: python
 
     from org.csstudio.display.builder.runtime.script import PVUtil
-    value = PVUtil.getDouble(pvs[0]);
+    value = PVUtil.getDouble(pvs[0])
 
 **Write PV Value**
 
+While the ``pvs`` are configured as script inputs, they may also be used
+as outputs by writing to them.
 Several method argument types are supported, e.g. Double, Double[], Integer, String. If writing a PV is forbidden by
 PV security, an exception will be thrown and shown in console.
 
 .. code-block:: python
 
-    pvs[0].write(0);
+    pvs[0].write(0)
 
 **Get severity of PV**