Class Widget
- java.lang.Object
-
- org.csstudio.display.builder.model.Widget
-
- Direct Known Subclasses:
DisplayModel
,VisibleWidget
public class Widget extends java.lang.Object
Base class for all widgets.A Widget has properties, supporting read access, subscription and for most properties also write access.
Properties can be accessed in a most generic way based on the property name:
getPropertyValue("text") setPropertyValue("text", "Hello") getPropertyValue("x") setPropertyValue("x", 60)
While this is ideal for access from scripts, Java code that deals with a specific widget can access properties in the type-safe way:
LabelWidget label; label.positionX().getValue(); label.positionX().setValue(60);
Widgets are part of a hierarchy. Their parent is either the
DisplayModel
or another widget with aChildrenProperty
-
-
Field Summary
Fields Modifier and Type Field Description static org.csstudio.display.builder.model.Version
BASE_WIDGET_VERSION
Initial version for all Display Builder widgets.static java.lang.String
USER_DATA_REPRESENTATION
Reserved widget user data key for storing the representation.static java.lang.String
USER_DATA_RUNTIME
Reserved widget user data key for storing the runtime.static java.lang.String
USER_DATA_SCRIPT_SUPPORT
Reserved widget user data key for storing script support.static java.lang.String
USER_DATA_TOOLKIT_PARENT
Reserved user data key for Widget that has 'children', i.e.
-
Method Summary
All Methods Static Methods Instance Methods Concrete Methods Modifier and Type Method Description DisplayModel
checkDisplayModel()
Locate display model, i.e.<PT> java.util.Optional<WidgetProperty<PT>>
checkProperty(java.lang.String name)
Check if widget has a given property.<PT> java.util.Optional<WidgetProperty<PT>>
checkProperty(org.csstudio.display.builder.model.WidgetPropertyDescriptor<PT> property_description)
Check if widget has a given property.<TYPE> TYPE
clearUserData(java.lang.String key)
Remove a user data entrystatic java.util.List<java.lang.String>
expandPropertyNames(WidgetProperty<?> property)
Helper for obtaining the complete property name 'paths'org.csstudio.display.builder.model.WidgetConfigurator
getConfigurator(org.csstudio.display.builder.model.Version persisted_version)
Obtain configurator.DisplayModel
getDisplayModel()
Locate display model, i.e.Macros
getEffectiveMacros()
Determine effective macros.java.lang.String
getID()
Unique runtime identifier of a widgetMacroValueProvider
getMacrosOrProperties()
java.lang.String
getName()
java.util.Optional<Widget>
getParent()
java.util.Set<WidgetProperty<?>>
getProperties()
Get all properties of the widget.WidgetProperty<?>
getProperty(java.lang.String name)
Get widget property.<PT> WidgetProperty<PT>
getProperty(org.csstudio.display.builder.model.WidgetPropertyDescriptor<PT> property_description)
Get widget property.WidgetProperty<?>
getPropertyByPath(java.lang.String path_name, boolean create_elements)
Get property via path<TYPE> TYPE
getPropertyValue(java.lang.String name)
Get widget property value.<PT> PT
getPropertyValue(org.csstudio.display.builder.model.WidgetPropertyDescriptor<PT> property_description)
Get widget property value.DisplayModel
getTopDisplayModel()
Locate top display model.java.lang.String
getType()
<TYPE> TYPE
getUserData(java.lang.String key)
org.csstudio.display.builder.model.Version
getVersion()
java.lang.String
getWidgetClass()
boolean
isClean()
WidgetProperty<org.csstudio.display.builder.model.properties.ActionInfos>
propActions()
WidgetProperty<java.lang.String>
propClass()
WidgetProperty<java.lang.Integer>
propHeight()
WidgetProperty<java.lang.String>
propName()
WidgetProperty<java.util.List<org.csstudio.display.builder.model.rules.RuleInfo>>
propRules()
WidgetProperty<java.util.List<org.csstudio.display.builder.model.properties.ScriptInfo>>
propScripts()
WidgetProperty<java.lang.Integer>
propWidth()
WidgetProperty<java.lang.Integer>
propX()
WidgetProperty<java.lang.Integer>
propY()
void
setConfiguratorResult(org.csstudio.display.builder.model.WidgetConfigurator configurator)
void
setPropertyValue(java.lang.String name, java.lang.Object value)
Set widget property value.<PT> void
setPropertyValue(org.csstudio.display.builder.model.WidgetPropertyDescriptor<PT> property_description, PT value)
Set widget property value.void
setUserData(java.lang.String key, java.lang.Object data)
Set user datajava.lang.String
toString()
-
-
-
Field Detail
-
BASE_WIDGET_VERSION
public static final org.csstudio.display.builder.model.Version BASE_WIDGET_VERSION
Initial version for all Display Builder widgets.Legacy used 1.0.0 for most widgets, so 2.0.0 indicates an update. Selected legacy widgets had incremented to a higher version, which needs to be handled for each such widget.
-
USER_DATA_REPRESENTATION
public static final java.lang.String USER_DATA_REPRESENTATION
Reserved widget user data key for storing the representation.The WidgetRepresentation for each
Widget
is stored under this key.- See Also:
- Constant Field Values
-
USER_DATA_TOOLKIT_PARENT
public static final java.lang.String USER_DATA_TOOLKIT_PARENT
Reserved user data key for Widget that has 'children', i.e. is a parent, to store the toolkit parent item- See Also:
- Constant Field Values
-
USER_DATA_RUNTIME
public static final java.lang.String USER_DATA_RUNTIME
Reserved widget user data key for storing the runtime.The WidgetRuntime for each
Widget
is stored under this key.- See Also:
- Constant Field Values
-
USER_DATA_SCRIPT_SUPPORT
public static final java.lang.String USER_DATA_SCRIPT_SUPPORT
Reserved widget user data key for storing script support.ScriptSupport is attached to the top-level root of the widget tree, i.e. the
DisplayModel
that is obtained by traversing up viaEmbeddedDisplayWidget
s to the top-level model.- See Also:
- Constant Field Values
-
-
Constructor Detail
-
Widget
public Widget(java.lang.String type)
Widget constructor.- Parameters:
type
- Widget type
-
Widget
public Widget(java.lang.String type, int default_width, int default_height)
Widget constructor.- Parameters:
type
- Widget typedefault_width
- Default widthdefault_height
- .. and height
-
-
Method Detail
-
getID
public final java.lang.String getID()
Unique runtime identifier of a widgetAt runtime, this ID can be used to construct PVs that are unique and specific to this instance of a widget. Even if the same display is opened multiple times within the same JVM, the widget is very likely to receive a new, unique identifier.
- Returns:
- Unique Runtime Identifier for widget
-
getVersion
public org.csstudio.display.builder.model.Version getVersion()
- Returns:
- Widget version number
-
getType
public final java.lang.String getType()
- Returns:
- Widget Type
-
getName
public final java.lang.String getName()
- Returns:
- Widget Name
-
getWidgetClass
public final java.lang.String getWidgetClass()
- Returns:
- Widget class to use for updating properties that use the class
-
getParent
public final java.util.Optional<Widget> getParent()
- Returns:
- Parent widget in Widget tree
-
getDisplayModel
public final DisplayModel getDisplayModel() throws java.lang.Exception
Locate display model, i.e. root of widget treeNote that for embedded displays, this would return the embedded model, not the top-level model of the window. Compare
getTopDisplayModel()
- Returns:
DisplayModel
for widget- Throws:
java.lang.Exception
- if widget is not part of a model
-
checkDisplayModel
public final DisplayModel checkDisplayModel()
Locate display model, i.e. root of widget tree- Returns:
DisplayModel
for widget ornull
- See Also:
version that throws exception
-
getTopDisplayModel
public final DisplayModel getTopDisplayModel() throws java.lang.Exception
Locate top display model.For embedded displays,
getDisplayModel
only provides the embedded model. This method traverses up via theEmbeddedDisplayWidget
to the top-level display model.- Returns:
- Top-level
DisplayModel
for widget - Throws:
java.lang.Exception
- if widget is not part of a model
-
setConfiguratorResult
public final void setConfiguratorResult(org.csstudio.display.builder.model.WidgetConfigurator configurator)
-
isClean
public boolean isClean()
- Returns:
true
if this widget was loaded without errors,false
if there were errors
-
propName
public final WidgetProperty<java.lang.String> propName()
- Returns:
- 'name' property
-
propClass
public final WidgetProperty<java.lang.String> propClass()
- Returns:
- 'class' property
-
propX
public final WidgetProperty<java.lang.Integer> propX()
- Returns:
- 'x' property
-
propY
public final WidgetProperty<java.lang.Integer> propY()
- Returns:
- 'y' property
-
propWidth
public final WidgetProperty<java.lang.Integer> propWidth()
- Returns:
- 'width' property
-
propHeight
public final WidgetProperty<java.lang.Integer> propHeight()
- Returns:
- 'height' property
-
propActions
public final WidgetProperty<org.csstudio.display.builder.model.properties.ActionInfos> propActions()
- Returns:
- 'actions' property
-
propRules
public final WidgetProperty<java.util.List<org.csstudio.display.builder.model.rules.RuleInfo>> propRules()
- Returns:
- 'rules' property
-
propScripts
public final WidgetProperty<java.util.List<org.csstudio.display.builder.model.properties.ScriptInfo>> propScripts()
- Returns:
- 'scripts' property
-
getConfigurator
public org.csstudio.display.builder.model.WidgetConfigurator getConfigurator(org.csstudio.display.builder.model.Version persisted_version) throws java.lang.Exception
Obtain configurator.While typically using the default
WidgetConfigurator
, widget may provide a different configurator for reading older persisted date.- Parameters:
persisted_version
- Version of the persisted data.- Returns:
- Widget configurator for that version
- Throws:
java.lang.Exception
- if persisted version cannot be handled
-
getProperties
public final java.util.Set<WidgetProperty<?>> getProperties()
Get all properties of the widget.Properties are ordered by category and sequence of definition.
- Returns:
- Unmodifiable set
-
expandPropertyNames
public static final java.util.List<java.lang.String> expandPropertyNames(WidgetProperty<?> property)
Helper for obtaining the complete property name 'paths'For a scalar property, this method simply returns that property name.
For arrays or structures, it returns names for each array resp. structure element.
- Parameters:
property
- The widget property.- Returns:
- List of property names
-
checkProperty
public final <PT> java.util.Optional<WidgetProperty<PT>> checkProperty(java.lang.String name)
Check if widget has a given property.This is called by code that needs to test if a widget has a certain property.
Only checks for direct properties of the widget, neither mapping legacy property names nor allowing for complex property paths.
- Type Parameters:
PT
- Type of the property's value.- Parameters:
name
- Property name- Returns:
- Optional
WidgetProperty
- See Also:
getProperty(String)
-
checkProperty
public final <PT> java.util.Optional<WidgetProperty<PT>> checkProperty(org.csstudio.display.builder.model.WidgetPropertyDescriptor<PT> property_description)
Check if widget has a given property.- Type Parameters:
PT
- Type of the property's value.- Parameters:
property_description
- Property descriptor- Returns:
- Optional
WidgetProperty
- See Also:
checkProperty(WidgetPropertyDescriptor)
-
getProperty
public final <PT> WidgetProperty<PT> getProperty(org.csstudio.display.builder.model.WidgetPropertyDescriptor<PT> property_description)
Get widget property.Property access based on property description allows type-safe access.
- Type Parameters:
PT
- Type of the property's value.- Parameters:
property_description
- Property description- Returns:
WidgetProperty
- Throws:
java.lang.IllegalArgumentException
- if property is unknown- See Also:
checkProperty(WidgetPropertyDescriptor)
-
getProperty
public WidgetProperty<?> getProperty(java.lang.String name) throws java.lang.IllegalArgumentException, java.lang.IndexOutOfBoundsException
Get widget property.Meant for rules, scripts and similar code which does not know the exact widget type and thus fetches properties by name.
Supports access to complex properties by path name, for example "y_axes[1].minimum" to get the minimum property of the second Y axis of a plot.
To allow use of legacy scripts and rules, the widget implementation may override to handle deprecated property names.
Caller presumes that the widget actually has the requested property, otherwise throwing Exception.
- Parameters:
name
- Property name- Returns:
WidgetProperty
- Throws:
java.lang.IllegalArgumentException
- if property is unknownjava.lang.IllegalArgumentException
- if path includes invalid elements, IndexOutOfBoundsException for access to array beyond sizejava.lang.IndexOutOfBoundsException
- See Also:
checkProperty(String)
-
getPropertyByPath
public WidgetProperty<?> getPropertyByPath(java.lang.String path_name, boolean create_elements) throws java.lang.IllegalArgumentException, java.lang.IndexOutOfBoundsException
Get property via path- Parameters:
path_name
- "struct_prop.array_prop[2].element"create_elements
- Create missing array elements?- Returns:
- Property for "element"
- Throws:
java.lang.IllegalArgumentException
- if path includes invalid elements, IndexOutOfBoundsException for access to array beyond sizejava.lang.IndexOutOfBoundsException
-
getPropertyValue
public final <PT> PT getPropertyValue(org.csstudio.display.builder.model.WidgetPropertyDescriptor<PT> property_description)
Get widget property value.Property access based on property description allows type-safe access.
- Type Parameters:
PT
- Type of the property's value.- Parameters:
property_description
- Property description- Returns:
- Value of the property
- Throws:
java.lang.IllegalArgumentException
- if property is unknown
-
getPropertyValue
public final <TYPE> TYPE getPropertyValue(java.lang.String name)
Get widget property value.Property access based on property name returns generic WidgetProperty without known type. Data is cast to the receiver type, but that cast may fail if actual data type differs.
- Type Parameters:
TYPE
- Data is cast to the receiver's type- Parameters:
name
- Property name, may also be path like "struct_prop.array_prop[2].element"- Returns:
- Value of the property
- Throws:
java.lang.IllegalArgumentException
- if property is unknownjava.lang.IndexOutOfBoundsException
- for array access beyond last element
-
setPropertyValue
public final <PT> void setPropertyValue(org.csstudio.display.builder.model.WidgetPropertyDescriptor<PT> property_description, PT value)
Set widget property value.Property access based on property description allows type-safe access.
- Type Parameters:
PT
- Type of the property's value.- Parameters:
property_description
- Property descriptionvalue
- New value of the property- Throws:
java.lang.IllegalArgumentException
- if property is unknown
-
setPropertyValue
public final void setPropertyValue(java.lang.String name, java.lang.Object value) throws java.lang.Exception
Set widget property value.Property access based on property name returns generic WidgetProperty without known type.
- Parameters:
name
- Property namevalue
- New value of the property- Throws:
java.lang.IllegalArgumentException
- if property is unknownjava.lang.Exception
- if value is unsuitable for this property
-
getEffectiveMacros
public Macros getEffectiveMacros()
Determine effective macros.Default implementation requests macros from parent.
Macros will be
null
while the widget is loaded until it is included in a model.- Returns:
Macros
-
getMacrosOrProperties
public MacroValueProvider getMacrosOrProperties()
- Returns:
- Macro provider for effective macros, falling back to properties
-
setUserData
public final void setUserData(java.lang.String key, java.lang.Object data)
Set user dataUser code can attach arbitrary data to a widget. This data is _not_ persisted with the model, and there is no change notification.
User code should avoid using reserved keys which start with an underscore "_...".
- Parameters:
key
- Keydata
- Data
-
getUserData
public final <TYPE> TYPE getUserData(java.lang.String key)
- Type Parameters:
TYPE
- Data is cast to the receiver's type- Parameters:
key
- Key- Returns:
- User data associated with key, or
null
- See Also:
setUserData(String, Object)
-
clearUserData
public final <TYPE> TYPE clearUserData(java.lang.String key)
Remove a user data entry- Type Parameters:
TYPE
- User data is cast to the receiver's type- Parameters:
key
- Key for which to remove user data- Returns:
- User data associated with key that has been removed, or
null
-
toString
public java.lang.String toString()
- Overrides:
toString
in classjava.lang.Object
-
-