.. currentmodule:: taurus.qt.qtgui.panel Use Taurus forms ================ This page describes common tasks when working with :class:`TaurusForm`. For an explanation of the form layout and how widgets are selected for each model, see :doc:`../explanation/forms`. .. _standalonetaurusform: Launch a TaurusForm application ------------------------------- You can use :class:`TaurusForm` as a standalone application for controlling attributes or devices from the control system. Launch it with:: taurus form [options] [] The model list is optional and is a space-separated list of Taurus models. Run the following command for the complete set of options:: taurus form --help The available item factories can also be listed, enabled and excluded using CLI arguments. See ``taurus form --help`` for the available options. Change the contents of a form ----------------------------- If the application allows user modifications, you can change both **what** is shown and **how** it is shown in the form. To change what is shown: * Right-click in the form and select **Modify contents**. A :ref:`TaurusModelChooser ` lets you modify the list of Taurus models represented by the form. * Drop models dragged from another Taurus widget, typically another :class:`TaurusForm` or a :ref:`TaurusModelChooser `. To change how an item is shown: * Right-click its label and select **Change Read Widget** or **Change Write Widget** to select another widget. * Enable or disable compact mode. * Use **Change Label** in the label context menu to customize the label text. Use **Change Labels** in the form context menu to change labels for all values in a form. .. tip:: You can also use **Modify contents** to reorder the items shown by the form. Use drag and drop ----------------- Each item represented in a form is associated with a :ref:`Taurus model `. Dragging the label of an item copies its model. Many Taurus widgets can accept dropped models, including :class:`TaurusForm`, Taurus plot widgets, and Taurus trend widgets. When a :class:`TaurusForm` receives one or more models from a drop, it appends them to its current list of displayed models. .. tip:: If you accidentally drop a model and want to remove the new item, use **Modify contents** from the form context menu. Use compact mode ---------------- In compact mode, a value is shown using one column for both the read and write widgets. Normally the read widget is visible. The write widget is shown only while editing. Typical edit triggers are: * pressing :kbd:`F2` * double-clicking the read widget Editing ends when the write widget loses focus or the changes are applied. In many cases, pressing :kbd:`Esc` also leaves edit mode. Enable or disable compact mode for one value by right-clicking its label and selecting **Compact mode**. You can set compact mode for all values from the form context menu. Write attribute values ---------------------- Writable Taurus attributes have both a **read value** and a **write value**. The read widget displays the current value from the control system, while the write widget lets you modify the requested value. The two values are not necessarily equal. The write value is a set point or desired value, while the read value reflects the actual value reported by the control system. For example, the measured voltage of a power supply may oscillate around its configured set point. Because writing an incorrect value may be dangerous for some equipment, Taurus write widgets do not normally apply a new value immediately while you type or move a control. Instead, the item is marked as having a **pending operation**. The label is highlighted with a blue frame and some write widgets provide additional feedback. You can inspect the tooltip to see the pending operation. .. figure:: /_static/forms-pendingops01.png :align: center Example of a pending operation: the write value has been changed but has not yet been applied. Apply or discard pending operations ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ Pending operations can be applied individually or for the whole form: * To apply the value for a single item, press :kbd:`Enter` in the write widget. This is the behavior of the default Taurus write widgets. * To apply all pending operations in a form, use the form **Apply** button when it is available. * Use **Reset** to discard all pending operations when the form provides this button. .. _forcedapply: Force a write of the same value ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^ If a write value has not changed, there is normally no pending operation and the value is therefore not written again. To force a write of the same value, press :kbd:`Ctrl+Enter` in the write widget. This can be useful, for example, when hardware needs an additional write of the same set point. Handle external changes ^^^^^^^^^^^^^^^^^^^^^^^ When an attribute read value changes in the control system, its read widget is updated according to the control system event or refresh configuration. If the write value is changed externally, for example by another client, Taurus notifies the item but does not overwrite the value currently displayed in your write widget. Instead, the item reports a pending operation. This prevents a concurrent edit from silently replacing your own input while still making you aware that the value changed elsewhere. .. tip:: Check the write widget tooltip to inspect the cause of a pending operation.