## Access Widget in Script

### widget object

The widget to which a script is attached can be accessed in the script via widget object. It is the controller(or EditPart in GEF) of the widget. widget object provided the methods to get or set any of its properties, store external objects or provide special methods for a particular widget.

### display object

The widget controller of the display is accessible in all scripts as display object. To get the controller of any widget in the display, you can call its method getWidget(name). For example:

    display.getWidget("myLabel").setPropertyValue("x", 20); //set x position of the widget myLabel to 20.

### Common methods to all widgets

- getPropertyValue(prop_id)
- setPropertyValue(prop_id, value)
- setPropertyValue(prop_id, value, forceFire)
- setExternalObject(name, var)
- getExternalObject(name)
- executeAction(index)

### Common methods to all container widgets

Container widgets includes Display, Grouping Container, Linking Container and Tabbed Container.

- getChild(name)
- getWidget(name)
- addChild(model)
- addChildToRight(model)
- addChildToBottom(model)
- removeChildByName(name)
- removeAllChildren()

### Common methods to all PV widgets

Any widget that has `PV Name` property is PV widget. For example, Text Update, Combo Box, XY Graph and so on.

- getPV()
- getPV(pvPropId)
- getValue()
- setValue(value)

### Special methods to each widget

Some widget may have special methods. See the document for each widget.

### getPropertyValue

    public java.lang.Object getPropertyValue(java.lang.String prop_id)

  Get property value of the widget.
  Parameters:
    `prop_id` - the property id. In most cases, it is the lower case of the property name.
  Returns:
    the property value.
  Example:

      var x = widget.getPropertyValue("x"); //get x position of the widget

### setPropertyValue

    public void setPropertyValue(java.lang.String prop_id,
                                 java.lang.Object value)

  Set the property value of the widget.

  Parameters:
    `prop_id` - the property id. In most cases, it is the lower case of the property name.
    `value` - the value. It must be the allowed input type corresponding to the property type. See Property Type
  Example:

      widget.setPropertyValue("x", 20); //set x position of the widget to 20.

### setPropertyValue

    public void setPropertyValue(java.lang.String prop_id,
                                 java.lang.Object value,
                                 boolean forceFire)

  Set the property value of the widget.

  Parameters:
    `prop_id` - the property id.
    `value` - the value.
    `forceFire` - If true, the property will be set again even if the new value is same as old value. If false and the new value is same as the old value, it will be ignored.
  Example:

      widget.setPropertyValue(
      	"opi_file", widget.getPropertyValue("opi_file"), true); //reload OPI in linking container.

### setExternalObject

    public void setExternalObject(java.lang.String name,
                                  java.lang.Object var)

  Add/modify an external object from javascript.

  Parameters:
    `name` - the name of the object.
    `var` - the object.

### getExternalObject

    public java.lang.Object getExternalObject(java.lang.String name)

  Get the external object by name.

  Returns:
    the external object. null if no such an object was set before.
  Example:

  This is an example which uses these two methods to remember if the dialog has been poped before.

      importPackage(Packages.org.eclipse.jface.dialogs);
      importPackage(Packages.org.csstudio.platform.data);
      importPackage(Packages.java.lang);

      var flagName = "popped";

      if(widget.getExternalObject(flagName) == null){
      	widget.setExternalObject(flagName, false);
      }

      var b = widget.getExternalObject(flagName);

      if(ValueUtil.getDouble(pvs[0].getValue()) > 80){
      		if( b == false){
      			widget.setExternalObject(flagName, true);
      			MessageDialog.openWarning(
      				null, "Warning", "The temperature you set is too high!");
      		}

      }else if (b == true){
      	widget.setExternalObject(flagName, false);
      }

### executeAction

    public void executeAction(int index)

  Run a widget action which is attached to the widget.

  Parameters:
    `index` - the index of the action in the actions list.

## Common methods to all container widgets

### getChild

    public AbstractBaseEditPart getChild(java.lang.String name)

  Get the direct child of this container by name. Depreciated: Use getWidget(name) instead.

  Parameters:
    `name` - the name of the child widget
  Returns:
    the widget contrller of the child. Or null if the widget doesn't exist.
  Example:

      var child = widget.getChild("gauge_2"); //get the gauge widget whose name is gauge_2
      child.setPropertyValue("enable", false); //child is a widget

### getWidget

    public AbstractBaseEditPart getWidget(java.lang.String name)

  Get a widget which is a descendant of this container by name.

  Parameters:
    `name` - the name of the widget which is a descendant of the container
  Returns:
    the widget controller of the widget. Throws exception if the widget doesn't exist.
  Example:

      var gauge2 = widget.getWidget("gauge_2"); //get the gauge widget whose name is gauge_2
      gauge2.setPropertyValue("enable", false); //child is a widget

### addChild

    public void addChild(org.csstudio.opibuilder.model.AbstractWidgetModel widgetModel)

  Add a child widget to the container.

  Parameters:
    `widgetModel` - model of the widget to be added.
  See Also:
    `WidgetUtil.createWidgetModel(String)`

### addChildToRight

    public void addChildToRight(org.csstudio.opibuilder.model.AbstractWidgetModel widgetModel)

  Add a child widget to the right of the container.

  Parameters:
    `widgetModel` - model of the widget to be added.
  See Also:
    `WidgetUtil.createWidgetModel(String)`

### addChildToBottom

    public void addChildToBottom(org.csstudio.opibuilder.model.AbstractWidgetModel widgetModel)

  Add a child widget to the bottom of the container.

  Parameters:
    `widgetModel` - model of the widget to be added.
  See Also:
    `WidgetUtil.createWidgetModel(String)`

### removeChildByName

    public void removeChildByName(java.lang.String widgetName)

  Remove a child widget by its name.

  Parameters:
    `widgetName` - name of the widget.
  Throws:
    `java.lang.RuntimeException` - if the widget name does not exist.

### removeAllChildren

    public void removeAllChildren()

  Remove all children.

## Common methods to all PV widgets

### getPV

    public PV getPV()

  Get the PV corresponding to the `PV Name` property. It is same as calling `getPV("pv_name")`.

  Returns:
    the PV corresponding to the `PV Name` property. null if PV Name is not configured for this widget.
  Example:

      importPackage(Packages.org.csstudio.opibuilder.scriptUtil);
      var pv = widget.getPV();
      var value = PVUtil.getDouble(pv); //Get its double value

### getPV

    public PV getPV(java.lang.String pvPropId)

  Some widgets may have more than one PV attached to it. This method can help to get the pv by its property id.

  Parameters:
    `pvPropId` - the PV property id. For example, `pv_name`, `trace_0_y_pv` for XY Graph.
  Returns:
    the corresponding pv for the pvPropId. null if the pv doesn't exist.

### getValue

    public Object getValue()

  The value that is being displayed on the widget. It is not the value of the attached PV even though they are equals in most cases if there is PV configured for the widget. The value type is specified by the widget, for example, boolean for boolean widget, double for meter and gauge, String for combo.

  Returns:
    The value of the widget.

### setValue

    public void setValue(Object value)

  Set the value of the widget. This only takes effect on the visual presentation of the widget and will not write the value to the PV attached to the widget.

  Parameters:
    `value` - the value to be set. It must be compatible with the widget. For example, a boolean widget only accept boolean or number.
  Throws:
    `java.lang.RuntimeException` - if the type of the value is not an acceptable type.