Class 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 a ChildrenProperty

    • 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 via EmbeddedDisplayWidgets 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 type
        default_width - Default width
        default_height - .. and height
    • Method Detail

      • getID

        public final java.lang.String getID()
        Unique runtime identifier of a widget

        At 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 tree

        Note 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
      • 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 the EmbeddedDisplayWidget 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 unknown
        java.lang.IllegalArgumentException - if path includes invalid elements, IndexOutOfBoundsException for access to array beyond size
        java.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 size
        java.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 unknown
        java.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 description
        value - 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 name
        value - New value of the property
        Throws:
        java.lang.IllegalArgumentException - if property is unknown
        java.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 data

        User 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 - Key
        data - 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 class java.lang.Object