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

Common methods to all container widgets

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

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.

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.

getPVByName

public org.csstudio.utility.pv.PV getPVByName(java.lang.String pvName)
Get PV attached to this widget by pv name. It includes the PVs in Rules and Scripts.

Parameters:
pvName - name of the PV.
Returns:
the PV. null if no such PV exists.

setVar

public void setVar(java.lang.String varName,
                   java.lang.Object varValue)
Set variable value. If the variable does not exist, it will be added to this widget first. *

Parameters:
varName - name of the variable.
varValue - value of the variable, which can be any type.
Since:
2.0.0

getVar

public java.lang.Object getVar(java.lang.String name)
Get the value of a Variable.

Returns:
the variable value. null if no such a variable 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.getVar(flagName) == null){
	widget.setVar(flagName, false);	
}

var b = widget.getVar(flagName);

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

getMacroValue

public java.lang.String getMacroValue(java.lang.String macroName)
Get macro value from the widget.
Parameters:
macroName - The name of the macro.
Returns:
the value of the macro. null if no such macro exist.
Example:
var macroValue = widget.getMacroValue("m1"); //get the macro value of "m1"

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.

setEnabled

public void setEnabled(boolean enable)
Set this widget to be enabled.

Parameters:
enable - true if the widget should be enabled.

setVisible

public void setVisible(boolean visible)
Set this widget's visibility.

Parameters:
enable - true if the widget should be visible.

setX

public void setX(java.lang.Number x)
Set X position of the widget

Parameters:
x - x position in pixel which is relative to its parent.
Since:
2.0.0

setY

public void setY(java.lang.Number y)
Set Y position of the widget

Parameters:
y - y position in pixel which is relative to its parent.
Since:
2.0.0

setWidth

public void setWidth(java.lang.Number width)
Set widget's width

Parameters:
width - width in pixel.
Since:
2.0.0

setHeight

public void setHeight(java.lang.Number height)
Set widget's height

Parameters:
height - height in pixel.
Since:
2.0.0

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.

removeChild

public void removeChild(AbstractBaseEditPart child)
Remove a child widget.
Parameters:
child - the child widget.

removeChild

public void removeChild(int index)
Remove the child at index.
Parameters:
index - index of the child.

removeAllChildren

public void removeAllChildren()
Remove all children.


performAutosize

public void performAutosize()
Automatically set the container size according to its children's geography size.

getValue

public java.lang.Object getValue()
By default, it returns an Object Array of its children's value. If setValue(Object) was called with a non Object[] input value, it will return the value of its first child.
Overrides:
getValue in class AbstractBaseEditPart
Returns:
The value of the widget.

setValue

public void setValue(java.lang.Object value)
If input value is instance of Object[] and its length is equal or larger than children size, it will write each element of value to each child according children's order. Otherwise, it will write the input value as an whole Object to every child.
Overrides:
setValue in class AbstractBaseEditPart
Parameters:
value - the value to be set. It must be the compatible type for the widget. For example, a boolean widget only accept boolean or number.

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 this widget. Since setting value to a widget usually results in figure repaint, this method should be called in UI thread. To call it in non-UI thread, see setValueInUIThread(value).

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.

setValueInUIThread

public void setValueInUIThread(Object value)
Call setValue(value) in UI Thread. This method can be called in non-UI thread.

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.