Documentation of XML schema for widgets

[tynanford]

I remember at one point a few months ago there was a discussion to create an XML schema document for the widgets. Is that correct? If so, is there a status on that?

Phoebusgen is a package to auto generate the XML from python and I think a schema doc would be useful for the package instead of what I have been doing which is all manual.

https://github.com/als-epics/phoebusgen

I'd be happy to help. Thanks in advance.

[kasemir]

Just like EDM, MEDM, ... the file format has not been documented. This is in part because we provide both the editor and the runtime, and reserve the right to adjust the file format while trying to remain compatible with previous versions. The display builder is for example quite lenient when it comes to opening BOY files, re-mapping or re-interpreting that format.
Still, compared to EDM, MEDM, ... we're using XML, so it would make a lot of sense to create a schema, especially if that helps with tools like phoebusgen.

One potential issue here is that we try to keep the display file minimalist, omitting all default values. This is a valid file:

<?xml version="1.0" encoding="UTF-8"?>
<display>
  <widget type="label">
    <text>Label text</text>
  </widget>
</display>

On the other extreme, a label can look like this, and that's with empty actions, rules, scripts:

  <widget type="label" version="2.0.0">
    <name>Label 1</name>
    <class>DEFAULT</class>
    <macros>
    </macros>
    <text>Label text</text>
    <x>0</x>
    <y>0</y>
    <width>100</width>
    <height>20</height>
    <visible>true</visible>
    <font>
      <font name="Default" family="Liberation Sans" style="REGULAR" size="14.0">
      </font>
    </font>
    <foreground_color>
      <color name="Text" red="0" green="0" blue="0">
      </color>
    </foreground_color>
    <background_color>
      <color name="Background" red="255" green="255" blue="255">
      </color>
    </background_color>
    <transparent>true</transparent>
    <horizontal_alignment>0</horizontal_alignment>
    <vertical_alignment>0</vertical_alignment>
    <rotation_step>0</rotation_step>
    <auto_size>false</auto_size>
    <wrap_words>true</wrap_words>
    <actions>
    </actions>
    <rules>
    </rules>
    <scripts>
    </scripts>
    <tooltip></tooltip>
    <border_width>0</border_width>
    <border_color>
      <color name="Text" red="0" green="0" blue="0">
      </color>
    </border_color>
  </widget>

If you want to create a schema, you can start with https://github.com/ControlSystemStudio/phoebus/blob/master/app/display/model/src/test/java/org/csstudio/display/builder/model/AllWidgetsAllProperties.java
In that older command line tool, you'll have to adjust the EXAMPLE_FILE path to for example "/tmp/all_widgets.bob" and then run it. It will create a file that lists all widgets with all their (default) properties.

At the same time, it might be useful to check the widget hierarchy, for example Widget -> VisibleWidget -> MacroWidget to see how the base widget has properties x, y, width, height, .., VisibleWidget adds visible and tooltip, and so on to get a similar hierarchy in the schema.

Do you know if there's a way to do that such that sites with locally added widgets can then also add them to the schema?

[tynanford]

Thanks for the throughout reply and sorry for the delay. I had a heck of a time trying to figure out how to run AllWidgetsAllProperties.java on the command line. I actually never figured it out, tried many different iterations of mvn exec:java and also tried phoebus.sh -main. Let me know if you have a quick hint of what I should have done. In the end the solution was opening the project in an IDE and simply right-clicking on the file...

The output file of AllWidgetsAllProperties.java looks like a good starting point. I'm not a XML schema expert but I can read up about it and see how different schemas could work.

Do you know if there's a way to do that such that sites with locally added widgets can then also add them to the schema?

I don't know of a way right now but can look into that as well.

[kasemir]

I would also run it from within the IDE, and as noted you'll have to change the EXAMPLE_FILE path because its current value last worked when this was all Eclipse plugins, https://github.com/kasemir/org.csstudio.display.builder, before phoebus.

The ant build of the app-display-model-${version}.jar does include the test code, so you can run it from within the product:

phoebus.sh -main org.csstudio.display.builder.model.AllWidgetsAllProperties

A long time ago I invoked it that way as part of the nightly build, back when some where discussing display file formats, how just <widget type="label"> might be more generic than something that specifically mentions "org.csstudio.opibuilder.widgets.Label" or "Qt...". The DLS web developments have some hint of that, https://github.com/dls-controls/cs-web-proto/wiki/Loading-different-file-formats, but we've clearly not congregated onto a common "EPICS display file format" for all tools.

Instead of running AllWidgetsAllProperties, you could also use plain phoebus with the preference setting

phoebus/app/display/model/src/main/resources/display_model_preferences.properties

Line 83 in 4a5268e

# When writing a display file, skip properties that are still at default values?

org.csstudio.display.builder.model/skip_defaults = false

This way, any time you write a display file from the editor it will include all the default values, so you get the full set of values for a widget.

[lorenzo-gomez-windhover]

Thanks a lot for writing phoebusgen! This will enable all kinds of automation workflows.
What I was referring to in the dev meeting is that if we had a schema for the widgets, then we could use something like generateDS to auto-generate an object model in python. This way the code is in sync with the schema itself. So if the schema gets updated, then the only thing you'd have to do is re-generate the object model rather than having to write code by hand. But it looks like in this case all of the code is already written by hand, but I figured I'd mention it. This tool is pretty reliable to the point that we use for xtce-generator. Hope this helps.

[tynanford]

Thanks Lorenzo that is really helpful. I would like to try out the schema and generated code strategy if I get some time. It would really help future maintenance for phoebusgen. generateDS looks promising

[katysaintin]

Hello, I have just make a pull request
#2580
This one provide a class that generates a rst file that list all the Phoebus Widgets and their properties.
For instant the widget list comes from the service loader (so the list have to be maintained by the developer), but I also add code (in comment for instant) that get the list through Reflection API, but we have to add the dependency in pom.xml file to use it. So I prefer to change nothing for the moment and just add a new class.

[tynanford]

That is really nice @katysaintin!