Widgets Helpers

Alarmable dataclass

Bases: Controllable

Represents a widget that changes appearance based on an EPICS alarm state.

Attributes

alarm_sensitive_content : bool Whether the content is alarm sensitive. alarm_sensitive_border : bool Whether the border is alarm sensitive.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Alarmable(Controllable):
    """
    Represents a widget that changes appearance based on an EPICS alarm state.

    Attributes
    ----------
    alarm_sensitive_content : bool
        Whether the content is alarm sensitive.
    alarm_sensitive_border : bool
        Whether the border is alarm sensitive.
    """

    alarm_sensitive_content: bool = ALARM_CONTENT_DEFAULT
    alarm_sensitive_border: bool = ALARM_BORDER_DEFAULT
    useDisplayBg: Optional[bool] = None

    def generate_properties(self) -> List[etree.Element]:
        """
        Generate XML properties for the alarmable widget.

        Returns
        -------
        List[etree.Element]
            A list containing geometry, channel, tooltip, and alarm properties.
        """
        properties: List[etree.Element] = super().generate_properties()
        properties.append(Bool("alarmSensitiveContent", self.alarm_sensitive_content).to_xml())
        properties.append(Bool("alarmSensitiveBorder", self.alarm_sensitive_border).to_xml())
        if self.useDisplayBg is not None:
            properties.append(Bool("useDisplayBg", self.useDisplayBg).to_xml())
        return properties

generate_properties()

Generate XML properties for the alarmable widget.

Returns

List[etree.Element] A list containing geometry, channel, tooltip, and alarm properties.

Source code in pydmconverter/widgets_helpers.py

def generate_properties(self) -> List[etree.Element]:
    """
    Generate XML properties for the alarmable widget.

    Returns
    -------
    List[etree.Element]
        A list containing geometry, channel, tooltip, and alarm properties.
    """
    properties: List[etree.Element] = super().generate_properties()
    properties.append(Bool("alarmSensitiveContent", self.alarm_sensitive_content).to_xml())
    properties.append(Bool("alarmSensitiveBorder", self.alarm_sensitive_border).to_xml())
    if self.useDisplayBg is not None:
        properties.append(Bool("useDisplayBg", self.useDisplayBg).to_xml())
    return properties

Alignment dataclass

Bases: XMLConvertible

Represents alignment properties for a widget.

Attributes

alignment : str The alignment value (e.g., 'left', 'center').

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Alignment(XMLConvertible):
    """
    Represents alignment properties for a widget.

    Attributes
    ----------
    alignment : str
        The alignment value (e.g., 'left', 'center').
    """

    alignment: str

    def to_xml(self) -> etree.Element:
        """
        Convert the alignment property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the alignment.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": "alignment"})
        set_tag: etree.Element = etree.SubElement(prop, "set")
        if self.alignment == "center":
            set_tag.text = "Qt::AlignHCenter|Qt::AlignVCenter"
        else:
            set_tag.text = f"Qt::Align{self.alignment.capitalize()}|Qt::AlignVCenter"
        return prop

to_xml()

Convert the alignment property to an XML element.

Returns

etree.Element The XML element representing the alignment.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the alignment property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the alignment.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": "alignment"})
    set_tag: etree.Element = etree.SubElement(prop, "set")
    if self.alignment == "center":
        set_tag.text = "Qt::AlignHCenter|Qt::AlignVCenter"
    else:
        set_tag.text = f"Qt::Align{self.alignment.capitalize()}|Qt::AlignVCenter"
    return prop

Bool dataclass

Bases: XMLConvertible

Represents a boolean property.

Attributes

name : str The name of the property. value : bool The boolean value.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Bool(XMLConvertible):
    """
    Represents a boolean property.

    Attributes
    ----------
    name : str
        The name of the property.
    value : bool
        The boolean value.
    """

    name: str
    value: bool

    def to_xml(self) -> etree.Element:
        """
        Convert the boolean property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the boolean.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": self.name, "stdset": "0"})
        bool_tag: etree.Element = etree.SubElement(prop, "bool")
        bool_tag.text = "true" if self.value else "false"
        return prop

to_xml()

Convert the boolean property to an XML element.

Returns

etree.Element The XML element representing the boolean.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the boolean property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the boolean.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": self.name, "stdset": "0"})
    bool_tag: etree.Element = etree.SubElement(prop, "bool")
    bool_tag.text = "true" if self.value else "false"
    return prop

BoolRule dataclass

Bases: XMLConvertible

Represents a simple boolean rule for widget properties.

Attributes

rule_type : str The type of rule (e.g., "Visible", "Enable"). channel : str The channel address used as input for the rule. initial_value : bool, optional The default value for the rule when no condition is met. Defaults to True. show_on_true : bool, optional Determines whether the rule evaluates to true when the condition is satisfied. Defaults to True. visMin : int, optional Minimum threshold value for a channel to be considered "active". Used for range-based visibility rules. visMax : int, optional Maximum threshold value for a channel to be considered "active". Used for range-based visibility rules. notes : str, optional Additional metadata or notes about the rule.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class BoolRule(XMLConvertible):
    """
    Represents a simple boolean rule for widget properties.

    Attributes
    ----------
    rule_type : str
        The type of rule (e.g., "Visible", "Enable").
    channel : str
        The channel address used as input for the rule.
    initial_value : bool, optional
        The default value for the rule when no condition is met. Defaults to True.
    show_on_true : bool, optional
        Determines whether the rule evaluates to true when the condition is satisfied. Defaults to True.
    visMin : int, optional
        Minimum threshold value for a channel to be considered "active". Used for range-based visibility rules.
    visMax : int, optional
        Maximum threshold value for a channel to be considered "active". Used for range-based visibility rules.
    notes : str, optional
        Additional metadata or notes about the rule.
    """

    rule_type: str
    channel: str
    initial_value: Optional[bool] = True
    show_on_true: Optional[bool] = True
    visMin: Optional[Union[int, float, str]] = None
    visMax: Optional[Union[int, float, str]] = None
    notes: Optional[str] = ""

    def to_string(self):
        """
        Convert the rule properties to a string.

        Returns
        -------
        str
            A string representing the rule.
        """
        if self.visMin is not None and self.visMax is not None:
            try:
                vis_min = float(self.visMin)
                vis_max = float(self.visMax)
            except (ValueError, TypeError):
                vis_min = 0.0
                vis_max = 0.0
            show_on_true_string = f"True if float(ch[0]) >= {vis_min} and float(ch[0]) < {vis_max} else False"
            show_on_false_string = f"False if float(ch[0]) >= {vis_min} and float(ch[0]) < {vis_max} else True"
        else:
            show_on_true_string = "True if ch[0]==1 else False"
            show_on_false_string = "True if ch[0]!=1 else False"
        expression = show_on_true_string if self.show_on_true else show_on_false_string

        return _json_object(
            {
                "name": f"{self.rule_type}_{self.channel}",
                "property": self.rule_type,
                "initial_value": str(self.initial_value),
                "expression": expression,
                "channels": [{"channel": self.channel, "trigger": True, "use_enum": False}],
                "notes": self.notes,
            }
        )

to_string()

Convert the rule properties to a string.

Returns

str A string representing the rule.

Source code in pydmconverter/widgets_helpers.py

def to_string(self):
    """
    Convert the rule properties to a string.

    Returns
    -------
    str
        A string representing the rule.
    """
    if self.visMin is not None and self.visMax is not None:
        try:
            vis_min = float(self.visMin)
            vis_max = float(self.visMax)
        except (ValueError, TypeError):
            vis_min = 0.0
            vis_max = 0.0
        show_on_true_string = f"True if float(ch[0]) >= {vis_min} and float(ch[0]) < {vis_max} else False"
        show_on_false_string = f"False if float(ch[0]) >= {vis_min} and float(ch[0]) < {vis_max} else True"
    else:
        show_on_true_string = "True if ch[0]==1 else False"
        show_on_false_string = "True if ch[0]!=1 else False"
    expression = show_on_true_string if self.show_on_true else show_on_false_string

    return _json_object(
        {
            "name": f"{self.rule_type}_{self.channel}",
            "property": self.rule_type,
            "initial_value": str(self.initial_value),
            "expression": expression,
            "channels": [{"channel": self.channel, "trigger": True, "use_enum": False}],
            "notes": self.notes,
        }
    )

Brush dataclass

Bases: XMLConvertible

Represents a brush property for a widget.

Attributes

red : int The red component. green : int The green component. blue : int The blue component. alpha : int, optional The alpha component, default is 255. fill : bool, optional Whether the brush is filled, default is True.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Brush(XMLConvertible):
    """
    Represents a brush property for a widget.

    Attributes
    ----------
    red : int
        The red component.
    green : int
        The green component.
    blue : int
        The blue component.
    alpha : int, optional
        The alpha component, default is 255.
    fill : bool, optional
        Whether the brush is filled, default is True.
    """

    red: int
    green: int
    blue: int
    alpha: int = 255
    fill: bool = True

    def to_xml(self) -> etree.Element:
        """
        Convert the brush property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the brush.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": "brush", "stdset": "0"})
        brush_elem: etree.Element = etree.SubElement(
            prop, "brush", attrib={"brushstyle": "SolidPattern" if self.fill else "NoBrush"}
        )
        color: Color = Color(self.red, self.green, self.blue, self.alpha)
        brush_elem.append(color.to_xml())
        return prop

to_xml()

Convert the brush property to an XML element.

Returns

etree.Element The XML element representing the brush.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the brush property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the brush.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": "brush", "stdset": "0"})
    brush_elem: etree.Element = etree.SubElement(
        prop, "brush", attrib={"brushstyle": "SolidPattern" if self.fill else "NoBrush"}
    )
    color: Color = Color(self.red, self.green, self.blue, self.alpha)
    brush_elem.append(color.to_xml())
    return prop

Channel dataclass

Bases: XMLConvertible

Represents a channel property for a widget.

Attributes

channel : str The channel name.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Channel(XMLConvertible):
    """
    Represents a channel property for a widget.

    Attributes
    ----------
    channel : str
        The channel name.
    """

    channel: str

    def to_xml(self) -> etree.Element:
        """
        Convert the channel property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the channel.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": "channel", "stdset": "0"})
        string_elem: etree.Element = etree.SubElement(prop, "string")
        string_elem.text = self.channel
        return prop

to_xml()

Convert the channel property to an XML element.

Returns

etree.Element The XML element representing the channel.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the channel property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the channel.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": "channel", "stdset": "0"})
    string_elem: etree.Element = etree.SubElement(prop, "string")
    string_elem.text = self.channel
    return prop

Color dataclass

Bases: XMLConvertible

Represents a color.

Attributes

red : int The red component (0-255). green : int The green component (0-255). blue : int The blue component (0-255). alpha : int, optional The alpha component (0-255), default is 255.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Color(XMLConvertible):
    """
    Represents a color.

    Attributes
    ----------
    red : int
        The red component (0-255).
    green : int
        The green component (0-255).
    blue : int
        The blue component (0-255).
    alpha : int, optional
        The alpha component (0-255), default is 255.
    """

    red: int
    green: int
    blue: int
    alpha: int = 255

    def to_xml(self) -> etree.Element:
        """
        Convert the color to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the color.
        """
        color_elem: etree.Element = etree.Element("color", attrib={"alpha": str(self.alpha)})
        red_elem: etree.Element = etree.SubElement(color_elem, "red")
        red_elem.text = str(self.red)
        green_elem: etree.Element = etree.SubElement(color_elem, "green")
        green_elem.text = str(self.green)
        blue_elem: etree.Element = etree.SubElement(color_elem, "blue")
        blue_elem.text = str(self.blue)
        return color_elem

to_xml()

Convert the color to an XML element.

Returns

etree.Element The XML element representing the color.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the color to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the color.
    """
    color_elem: etree.Element = etree.Element("color", attrib={"alpha": str(self.alpha)})
    red_elem: etree.Element = etree.SubElement(color_elem, "red")
    red_elem.text = str(self.red)
    green_elem: etree.Element = etree.SubElement(color_elem, "green")
    green_elem.text = str(self.green)
    blue_elem: etree.Element = etree.SubElement(color_elem, "blue")
    blue_elem.text = str(self.blue)
    return color_elem

ColorObject dataclass

Bases: XMLConvertible

Source code in pydmconverter/widgets_helpers.py

@dataclass
class ColorObject(XMLConvertible):
    name: str
    red: int
    green: int
    blue: int
    alpha: int = 255

    def to_xml(self) -> etree.Element:
        """
        Convert the color property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the color.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": self.name, "stdset": "0"})
        color: Color = Color(self.red, self.green, self.blue, alpha=self.alpha)
        prop.append(color.to_xml())
        return prop

to_xml()

Convert the color property to an XML element.

Returns

etree.Element The XML element representing the color.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the color property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the color.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": self.name, "stdset": "0"})
    color: Color = Color(self.red, self.green, self.blue, alpha=self.alpha)
    prop.append(color.to_xml())
    return prop

Column dataclass

Represents end tag for tables.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Column:
    """
    Represents end </column> tag for tables.
    """

    def to_xml(self) -> etree.Element:
        """
        Generates a Column XML element.

        Returns
        -------
        etree.Element
            The XML element representing a column.
        """
        return etree.Element("column")

to_xml()

Generates a Column XML element.

Returns

etree.Element The XML element representing a column.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Generates a Column XML element.

    Returns
    -------
    etree.Element
        The XML element representing a column.
    """
    return etree.Element("column")

Controllable dataclass

Bases: Tangible

Represents a widget that uses an EPICS PV.

Attributes

channel : Optional[str] The EPICS channel. pydm_tool_tip : Optional[str] The tooltip text for the widget.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Controllable(Tangible):
    """
    Represents a widget that uses an EPICS PV.

    Attributes
    ----------
    channel : Optional[str]
        The EPICS channel.
    pydm_tool_tip : Optional[str]
        The tooltip text for the widget.
    """

    channel: Optional[str] = None
    pydm_tool_tip: Optional[str] = None
    visPvList: Optional[List[Tuple[str, int, int, bool]]] = None
    visPv: Optional[str] = None
    visInvert: Optional[bool] = None
    rules: Optional[List[str]] = field(default_factory=list)
    extra_rules: List[Dict[str, Any]] = field(default_factory=list)
    visMin: Optional[Union[int, float, str]] = None
    visMax: Optional[Union[int, float, str]] = None
    text = None
    hide_on_disconnect_channel: Optional[str] = None
    isSymbol: Optional[bool] = None
    symbolChannel: Optional[str] = None

    def generate_properties(self) -> List[etree.Element]:
        """
        Generate XML properties for the controllable widget.

        Returns
        -------
        List[etree.Element]
            A list containing geometry, channel, and tooltip properties.
        """
        properties: List[etree.Element] = super().generate_properties()
        if self.channel is not None:
            if isinstance(self.channel, List):
                if len(self.channel) > 1:
                    logger.warning(f"This channel was given multiple pvs: {self.channel}, using the first channel")
                self.channel = self.channel[0]

            properties.append(Channel(self.channel).to_xml())
        if self.pydm_tool_tip is not None:
            properties.append(PyDMToolTip(self.pydm_tool_tip).to_xml())
        if self.visPvList is not None:
            for elem in self.visPvList:
                group_initial = False
                group_or_outside = None
                if len(elem) == 6:
                    group_channel, group_min, group_max, group_invert, group_initial, group_or_outside = elem
                elif len(elem) == 5:
                    group_channel, group_min, group_max, group_invert, group_initial = elem
                elif len(elem) == 4:
                    group_channel, group_min, group_max, group_invert = elem
                else:
                    group_channel, group_min, group_max = elem
                    group_invert = False
                self.rules.append(
                    RuleArguments(
                        "Visible",
                        group_channel,
                        group_initial,
                        not group_invert,
                        group_min,
                        group_max,
                        group_or_outside,
                    )
                )

        if self.visPv is not None:
            # EDM shows the widget while visMin <= value < visMax, reading a missing limit as 0.
            self.rules.append(
                RuleArguments(
                    "Visible",
                    self.visPv,
                    False,
                    not self.visInvert if self.visInvert is not None else True,
                    self.visMin if self.visMin is not None else "0",
                    self.visMax if self.visMax is not None else "0",
                )
            )

        is_hidden = any(self.name.lower().startswith(elem) for elem in HIDDEN_WIDGET_TYPES)
        if is_hidden:
            hidden_channel = self.channel
        elif self.isSymbol is not None:
            hidden_channel = self.symbolChannel
        else:
            hidden_channel = None
        properties.append(Rules(self.rules, hidden_channel, self.extra_rules).to_xml())
        return properties

generate_properties()

Generate XML properties for the controllable widget.

Returns

List[etree.Element] A list containing geometry, channel, and tooltip properties.

Source code in pydmconverter/widgets_helpers.py

def generate_properties(self) -> List[etree.Element]:
    """
    Generate XML properties for the controllable widget.

    Returns
    -------
    List[etree.Element]
        A list containing geometry, channel, and tooltip properties.
    """
    properties: List[etree.Element] = super().generate_properties()
    if self.channel is not None:
        if isinstance(self.channel, List):
            if len(self.channel) > 1:
                logger.warning(f"This channel was given multiple pvs: {self.channel}, using the first channel")
            self.channel = self.channel[0]

        properties.append(Channel(self.channel).to_xml())
    if self.pydm_tool_tip is not None:
        properties.append(PyDMToolTip(self.pydm_tool_tip).to_xml())
    if self.visPvList is not None:
        for elem in self.visPvList:
            group_initial = False
            group_or_outside = None
            if len(elem) == 6:
                group_channel, group_min, group_max, group_invert, group_initial, group_or_outside = elem
            elif len(elem) == 5:
                group_channel, group_min, group_max, group_invert, group_initial = elem
            elif len(elem) == 4:
                group_channel, group_min, group_max, group_invert = elem
            else:
                group_channel, group_min, group_max = elem
                group_invert = False
            self.rules.append(
                RuleArguments(
                    "Visible",
                    group_channel,
                    group_initial,
                    not group_invert,
                    group_min,
                    group_max,
                    group_or_outside,
                )
            )

    if self.visPv is not None:
        # EDM shows the widget while visMin <= value < visMax, reading a missing limit as 0.
        self.rules.append(
            RuleArguments(
                "Visible",
                self.visPv,
                False,
                not self.visInvert if self.visInvert is not None else True,
                self.visMin if self.visMin is not None else "0",
                self.visMax if self.visMax is not None else "0",
            )
        )

    is_hidden = any(self.name.lower().startswith(elem) for elem in HIDDEN_WIDGET_TYPES)
    if is_hidden:
        hidden_channel = self.channel
    elif self.isSymbol is not None:
        hidden_channel = self.symbolChannel
    else:
        hidden_channel = None
    properties.append(Rules(self.rules, hidden_channel, self.extra_rules).to_xml())
    return properties

Curves dataclass

Bases: XMLConvertible

Represents a curve for a PyDMWaveformPlot.

Attributes:

Name	Type	Description
x_channel		str The channel for x values
y_channel		str The channel for y values
plotColor		RGBA The color given to the curve

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Curves(XMLConvertible):
    """
    Represents a curve for a PyDMWaveformPlot.

    Attributes:
        x_channel : str
            The channel for x values
        y_channel : str
            The channel for y values
        plotColor : RGBA
            The color given to the curve
    """

    x_channel: Optional[str] = None
    y_channel: Optional[str] = None
    plotColor: Optional[RGBA] = None

CustomWidget dataclass

Bases: XMLConvertible

Represents a custom widget configuration.

Attributes

cls : str The class name of the custom widget. base : str The base class that this widget extends. header : str The header file for the widget. container : str, optional The container information (default is an empty string).

Source code in pydmconverter/widgets_helpers.py

@dataclass
class CustomWidget(XMLConvertible):
    """
    Represents a custom widget configuration.

    Attributes
    ----------
    cls : str
        The class name of the custom widget.
    base : str
        The base class that this widget extends.
    header : str
        The header file for the widget.
    container : str, optional
        The container information (default is an empty string).
    """

    cls: str
    base: str
    header: str
    container: str = ""

    def to_xml(self) -> etree.Element:
        """
        Convert the custom widget configuration to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the custom widget.
        """
        top: etree.Element = etree.Element("customwidget")
        cls_elem: etree.Element = etree.SubElement(top, "class")
        cls_elem.text = self.cls
        extends: etree.Element = etree.SubElement(top, "extends")
        extends.text = self.base
        header_elem: etree.Element = etree.SubElement(top, "header")
        header_elem.text = self.header
        if self.container:
            container_elem: etree.Element = etree.SubElement(top, "container")
            container_elem.text = self.container
        return top

to_xml()

Convert the custom widget configuration to an XML element.

Returns

etree.Element The XML element representing the custom widget.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the custom widget configuration to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the custom widget.
    """
    top: etree.Element = etree.Element("customwidget")
    cls_elem: etree.Element = etree.SubElement(top, "class")
    cls_elem.text = self.cls
    extends: etree.Element = etree.SubElement(top, "extends")
    extends.text = self.base
    header_elem: etree.Element = etree.SubElement(top, "header")
    header_elem.text = self.header
    if self.container:
        container_elem: etree.Element = etree.SubElement(top, "container")
        container_elem.text = self.container
    return top

Double dataclass

Bases: XMLConvertible

Represents a double/float property.

Attributes

name : str The name of the property. value : float The decimal value.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Double(XMLConvertible):
    """
    Represents a double/float property.

    Attributes
    ----------
    name : str
        The name of the property.
    value : float
        The decimal value.
    """

    name: str
    value: float = 0.0

    def to_xml(self) -> etree.Element:
        """
        Convert the float property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the float (converted to double).
        """
        prop: etree.Element = etree.Element("property", attrib={"name": self.name, "stdset": "0"})
        double_tag: etree.Element = etree.SubElement(prop, "double")  # Need to use double because float is unsupported
        double_tag.text = str(self.value)
        return prop

to_xml()

Convert the float property to an XML element.

Returns

etree.Element The XML element representing the float (converted to double).

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the float property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the float (converted to double).
    """
    prop: etree.Element = etree.Element("property", attrib={"name": self.name, "stdset": "0"})
    double_tag: etree.Element = etree.SubElement(prop, "double")  # Need to use double because float is unsupported
    double_tag.text = str(self.value)
    return prop

Drawable dataclass

Bases: Tangible

Represents a widget that can be drawn with pen and brush properties.

Attributes

penStyle : Optional[str] The style of the pen ('dash' for dashed, otherwise solid). penColor : Optional[RGBA] A tuple representing the pen color (red, green, blue, alpha). penWidth : Optional[int] The width of the pen. brushColor : Optional[RGBA] A tuple representing the brush color (red, green, blue, alpha). brushFill : Optional[bool] Whether the brush should fill. rotation : Optional[float] The rotation angle.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Drawable(Tangible):
    """
    Represents a widget that can be drawn with pen and brush properties.

    Attributes
    ----------
    penStyle : Optional[str]
        The style of the pen ('dash' for dashed, otherwise solid).
    penColor : Optional[RGBA]
        A tuple representing the pen color (red, green, blue, alpha).
    penWidth : Optional[int]
        The width of the pen.
    brushColor : Optional[RGBA]
        A tuple representing the brush color (red, green, blue, alpha).
    brushFill : Optional[bool]
        Whether the brush should fill.
    rotation : Optional[float]
        The rotation angle.
    """

    penStyle: Optional[str] = None
    penColor: Optional[RGBA] = None
    penWidth: Optional[int] = None
    brushColor: Optional[RGBA] = None
    brushFill: Optional[bool] = None
    rotation: Optional[float] = None
    # PyDM's stylesheet colours an alarm-sensitive drawing's brush itself
    # (qproperty-brush), which the drawing's own stylesheet never sets.
    alarm_content_style: ClassVar[Optional[str]] = None
    # Whether the widget stays transparent around a filled shape. Without its own
    # background-color it paints the screen's (the Form's stylesheet sets it for every
    # widget on the screen), which would hide the widgets under an ellipse's corners or
    # a line's or polygon's bounding box.
    transparent_when_filled: ClassVar[bool] = False

    def style_sheet(self) -> str:
        """The widget's own stylesheet, empty for none.

        PyDM's stylesheet gives a drawing with an alarm-sensitive border a 2 px pen
        (PyDMDrawing[alarmSensitiveBorder="true"] { qproperty-penWidth: 2; }) at every
        polish, after the .ui has set penWidth, while EDM's lineAlarm only recolours the
        line. The widget's own stylesheet applies after the application's, so the width
        is written there too. The cost: a penWidth set later in Designer's property
        editor is overridden at runtime until the declaration is removed from the
        styleSheet. PyDM's rule overrides it anyway while the border is alarm
        sensitive, so only those drawings carry it.
        """
        declarations = []
        if self.brushFill is None or self.transparent_when_filled:
            declarations.append("background-color: transparent;")
        if self.penWidth is not None and getattr(self, "alarm_sensitive_border", False):
            declarations.append(f"qproperty-penWidth: {self.penWidth};")
        return " ".join(declarations)

    def generate_properties(self) -> List[etree.Element]:
        """
        Generate XML properties for the drawable widget.

        Returns
        -------
        List[etree.Element]
            A list containing geometry, pen, brush, and rotation properties.
        """
        properties: List[etree.Element] = super().generate_properties()
        if self.penColor is not None:
            properties.append(PenColor(*self.penColor).to_xml())
        if self.penStyle is not None or self.penColor is not None:
            properties.append(PenStyle(style=self.penStyle).to_xml())
        if self.penWidth is not None:
            properties.append(PenWidth(width=self.penWidth).to_xml())
        if self.brushColor is not None:
            properties.append(Brush(*self.brushColor, fill=self.brushFill).to_xml())
        style_sheet = self.style_sheet()
        if style_sheet:
            properties.append(Text("styleSheet", style_sheet).to_xml())
        if self.rotation is not None:
            properties.append(Rotation("rotation", self.rotation).to_xml())
        return properties

generate_properties()

Generate XML properties for the drawable widget.

Returns

List[etree.Element] A list containing geometry, pen, brush, and rotation properties.

Source code in pydmconverter/widgets_helpers.py

def generate_properties(self) -> List[etree.Element]:
    """
    Generate XML properties for the drawable widget.

    Returns
    -------
    List[etree.Element]
        A list containing geometry, pen, brush, and rotation properties.
    """
    properties: List[etree.Element] = super().generate_properties()
    if self.penColor is not None:
        properties.append(PenColor(*self.penColor).to_xml())
    if self.penStyle is not None or self.penColor is not None:
        properties.append(PenStyle(style=self.penStyle).to_xml())
    if self.penWidth is not None:
        properties.append(PenWidth(width=self.penWidth).to_xml())
    if self.brushColor is not None:
        properties.append(Brush(*self.brushColor, fill=self.brushFill).to_xml())
    style_sheet = self.style_sheet()
    if style_sheet:
        properties.append(Text("styleSheet", style_sheet).to_xml())
    if self.rotation is not None:
        properties.append(Rotation("rotation", self.rotation).to_xml())
    return properties

style_sheet()

The widget's own stylesheet, empty for none.

PyDM's stylesheet gives a drawing with an alarm-sensitive border a 2 px pen (PyDMDrawing[alarmSensitiveBorder="true"] { qproperty-penWidth: 2; }) at every polish, after the .ui has set penWidth, while EDM's lineAlarm only recolours the line. The widget's own stylesheet applies after the application's, so the width is written there too. The cost: a penWidth set later in Designer's property editor is overridden at runtime until the declaration is removed from the styleSheet. PyDM's rule overrides it anyway while the border is alarm sensitive, so only those drawings carry it.

Source code in pydmconverter/widgets_helpers.py

def style_sheet(self) -> str:
    """The widget's own stylesheet, empty for none.

    PyDM's stylesheet gives a drawing with an alarm-sensitive border a 2 px pen
    (PyDMDrawing[alarmSensitiveBorder="true"] { qproperty-penWidth: 2; }) at every
    polish, after the .ui has set penWidth, while EDM's lineAlarm only recolours the
    line. The widget's own stylesheet applies after the application's, so the width
    is written there too. The cost: a penWidth set later in Designer's property
    editor is overridden at runtime until the declaration is removed from the
    styleSheet. PyDM's rule overrides it anyway while the border is alarm
    sensitive, so only those drawings carry it.
    """
    declarations = []
    if self.brushFill is None or self.transparent_when_filled:
        declarations.append("background-color: transparent;")
    if self.penWidth is not None and getattr(self, "alarm_sensitive_border", False):
        declarations.append(f"qproperty-penWidth: {self.penWidth};")
    return " ".join(declarations)

Enum dataclass

Bases: XMLConvertible

Represents an enumeration property.

Attributes

name : str The name of the property. value : str The enum value.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Enum(XMLConvertible):
    """
    Represents an enumeration property.

    Attributes
    ----------
    name : str
        The name of the property.
    value : str
        The enum value.
    """

    name: str
    value: str

    def to_xml(self) -> etree.Element:
        """
        Convert the enum property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the enum.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": self.name, "stdset": "0"})
        enum_elem: etree.Element = etree.SubElement(prop, "enum")
        enum_elem.text = self.value
        return prop

to_xml()

Convert the enum property to an XML element.

Returns

etree.Element The XML element representing the enum.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the enum property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the enum.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": self.name, "stdset": "0"})
    enum_elem: etree.Element = etree.SubElement(prop, "enum")
    enum_elem.text = self.value
    return prop

Font dataclass

Bases: XMLConvertible

Represents font properties for a widget.

Attributes

pointsize : Optional[int] The size of the font. weight : Optional[int] The weight of the font. bold : Optional[bool] Whether the font is bold. italic : Optional[bool] Whether the font is italic.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Font(XMLConvertible):
    """
    Represents font properties for a widget.

    Attributes
    ----------
    pointsize : Optional[int]
        The size of the font.
    weight : Optional[int]
        The weight of the font.
    bold : Optional[bool]
        Whether the font is bold.
    italic : Optional[bool]
        Whether the font is italic.
    """

    family: Optional[str] = None
    pointsize: Optional[int] = None
    weight: Optional[int] = None
    bold: Optional[bool] = None
    italic: Optional[bool] = None

    def to_xml(self) -> etree.Element:
        """
        Convert the font properties to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the font.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": "font"})
        font: etree.Element = etree.SubElement(prop, "font")
        if self.family is not None:
            family_tag: etree.Element = etree.SubElement(font, "family")
            family_tag.text = str(self.family)
        if self.pointsize is not None:
            pointsize_tag: etree.Element = etree.SubElement(font, "pointsize")
            pointsize_tag.text = str(self.pointsize)
        if self.weight is not None:
            weight_tag: etree.Element = etree.SubElement(font, "weight")
            weight_tag.text = str(self.weight)
        if self.bold is not None:
            bold_tag: etree.Element = etree.SubElement(font, "bold")
            bold_tag.text = "true" if self.bold else "false"
        if self.italic is not None:
            italic_tag: etree.Element = etree.SubElement(font, "italic")
            italic_tag.text = "true" if self.italic else "false"
        return prop

to_xml()

Convert the font properties to an XML element.

Returns

etree.Element The XML element representing the font.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the font properties to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the font.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": "font"})
    font: etree.Element = etree.SubElement(prop, "font")
    if self.family is not None:
        family_tag: etree.Element = etree.SubElement(font, "family")
        family_tag.text = str(self.family)
    if self.pointsize is not None:
        pointsize_tag: etree.Element = etree.SubElement(font, "pointsize")
        pointsize_tag.text = str(self.pointsize)
    if self.weight is not None:
        weight_tag: etree.Element = etree.SubElement(font, "weight")
        weight_tag.text = str(self.weight)
    if self.bold is not None:
        bold_tag: etree.Element = etree.SubElement(font, "bold")
        bold_tag.text = "true" if self.bold else "false"
    if self.italic is not None:
        italic_tag: etree.Element = etree.SubElement(font, "italic")
        italic_tag.text = "true" if self.italic else "false"
    return prop

Geometry dataclass

Bases: XMLConvertible

Represents geometry properties for a widget.

Attributes

x : Union[int, str] The x-coordinate. y : Union[int, str] The y-coordinate. width : Union[int, str] The width of the widget. height : Union[int, str] The height of the widget.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Geometry(XMLConvertible):
    """
    Represents geometry properties for a widget.

    Attributes
    ----------
    x : Union[int, str]
        The x-coordinate.
    y : Union[int, str]
        The y-coordinate.
    width : Union[int, str]
        The width of the widget.
    height : Union[int, str]
        The height of the widget.
    """

    x: Union[int, str]
    y: Union[int, str]
    width: Union[int, str]
    height: Union[int, str]

    def to_xml(self) -> etree.Element:
        """
        Convert the geometry properties to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the geometry.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": "geometry"})
        rect: etree.Element = etree.SubElement(prop, "rect")

        for field_def in fields(self):
            value = getattr(self, field_def.name)
            elem: etree.Element = etree.SubElement(rect, field_def.name)

            if value is None:
                default_values = {"x": 0, "y": 0, "width": 100, "height": 100}
                value = default_values.get(field_def.name, 0)
            else:
                try:
                    if isinstance(value, str) and "." in value:
                        value = int(float(value))
                    else:
                        value = int(value)
                except (ValueError, TypeError):
                    default_values = {"x": 0, "y": 0, "width": 100, "height": 100}
                    value = default_values.get(field_def.name, 0)

            elem.text = str(value)
        return prop

to_xml()

Convert the geometry properties to an XML element.

Returns

etree.Element The XML element representing the geometry.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the geometry properties to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the geometry.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": "geometry"})
    rect: etree.Element = etree.SubElement(prop, "rect")

    for field_def in fields(self):
        value = getattr(self, field_def.name)
        elem: etree.Element = etree.SubElement(rect, field_def.name)

        if value is None:
            default_values = {"x": 0, "y": 0, "width": 100, "height": 100}
            value = default_values.get(field_def.name, 0)
        else:
            try:
                if isinstance(value, str) and "." in value:
                    value = int(float(value))
                else:
                    value = int(value)
            except (ValueError, TypeError):
                default_values = {"x": 0, "y": 0, "width": 100, "height": 100}
                value = default_values.get(field_def.name, 0)

        elem.text = str(value)
    return prop

Hidable dataclass

Bases: Tangible

Represents a widget that can be hidden.

Attributes

visibility_pv : Optional[str] The visibility process variable. visibility_max : Optional[str] The maximum visibility value. visibility_min : Optional[str] The minimum visibility value. visibility_invert : bool Whether the visibility is inverted.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Hidable(Tangible):
    """
    Represents a widget that can be hidden.

    Attributes
    ----------
    visibility_pv : Optional[str]
        The visibility process variable.
    visibility_max : Optional[str]
        The maximum visibility value.
    visibility_min : Optional[str]
        The minimum visibility value.
    visibility_invert : bool
        Whether the visibility is inverted.
    """

    visibility_pv: Optional[str] = None
    visibility_max: Optional[str] = None
    visibility_min: Optional[str] = None
    visibility_invert: bool = False

Int dataclass

Bases: XMLConvertible

Represents an integer property.

Attributes

name : str The name of the property. value : int The integer value.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Int(XMLConvertible):
    """
    Represents an integer property.

    Attributes
    ----------
    name : str
        The name of the property.
    value : int
        The integer value.
    """

    name: str
    value: int = 0

    def to_xml(self) -> etree.Element:
        """
        Convert the integer property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the integer.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": self.name, "stdset": "0"})
        int_tag: etree.Element = etree.SubElement(prop, "number")
        # Convert through float first to handle scientific notation (e.g., '-2e+08')
        # PyQt's uic parser cannot handle scientific notation in <number> elements
        try:
            int_value = int(float(self.value))
        except (ValueError, TypeError):
            int_value = 0
        int_tag.text = str(int_value)
        return prop

to_xml()

Convert the integer property to an XML element.

Returns

etree.Element The XML element representing the integer.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the integer property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the integer.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": self.name, "stdset": "0"})
    int_tag: etree.Element = etree.SubElement(prop, "number")
    # Convert through float first to handle scientific notation (e.g., '-2e+08')
    # PyQt's uic parser cannot handle scientific notation in <number> elements
    try:
        int_value = int(float(self.value))
    except (ValueError, TypeError):
        int_value = 0
    int_tag.text = str(int_value)
    return prop

Layout

Represents a layout configuration for widgets.

This is a placeholder class for layout-related properties.

Source code in pydmconverter/widgets_helpers.py

class Layout:
    """
    Represents a layout configuration for widgets.

    This is a placeholder class for layout-related properties.
    """

    pass

Legible dataclass

Bases: Tangible

Represents a widget that displays text.

Attributes

text : Optional[str] The text to display. font : dict A dictionary containing font properties. alignment : Optional[str] The text alignment.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Legible(Tangible):
    """
    Represents a widget that displays text.

    Attributes
    ----------
    text : Optional[str]
        The text to display.
    font : dict
        A dictionary containing font properties.
    alignment : Optional[str]
        The text alignment.
    """

    text: Optional[str] = None
    font: dict = field(default_factory=dict)
    alignment: Optional[str] = None
    text_has_mnemonics: ClassVar[bool] = False

    def generate_properties(self) -> List[etree.Element]:
        """
        Generate XML properties for the legible widget.

        Returns
        -------
        List[etree.Element]
            A list containing geometry, text, font, and alignment properties.
        """
        properties: List[etree.Element] = super().generate_properties()
        if self.text is not None:
            value = escape_qt_mnemonic(self.text) if self.text_has_mnemonics else self.text
            properties.append(Text("text", value).to_xml())
        if self.font:
            properties.append(Font(**self.font).to_xml())
        if self.alignment is not None:
            properties.append(Alignment(self.alignment).to_xml())
        return properties

generate_properties()

Generate XML properties for the legible widget.

Returns

List[etree.Element] A list containing geometry, text, font, and alignment properties.

Source code in pydmconverter/widgets_helpers.py

def generate_properties(self) -> List[etree.Element]:
    """
    Generate XML properties for the legible widget.

    Returns
    -------
    List[etree.Element]
        A list containing geometry, text, font, and alignment properties.
    """
    properties: List[etree.Element] = super().generate_properties()
    if self.text is not None:
        value = escape_qt_mnemonic(self.text) if self.text_has_mnemonics else self.text
        properties.append(Text("text", value).to_xml())
    if self.font:
        properties.append(Font(**self.font).to_xml())
    if self.alignment is not None:
        properties.append(Alignment(self.alignment).to_xml())
    return properties

MultiRule dataclass

Bases: XMLConvertible

Represents a compound rule composed of multiple conditions.

Attributes

rule_type : str The type of rule (e.g., "Visible", "Enable"). rule_list : list of RuleArguments, optional A list of rule argument tuples, where each tuple contains: (rule_type, channel, initial_value, show_on_true, visMin, visMax). hide_on_disconnect_channel : str, optional An additional channel used to hide the widget if it disconnects. initial_value : bool, optional Default value for the rule when no conditions are satisfied. Defaults to False. notes : str, optional Additional metadata or notes about the rule.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class MultiRule(XMLConvertible):
    """
    Represents a compound rule composed of multiple conditions.

    Attributes
    ----------
    rule_type : str
        The type of rule (e.g., "Visible", "Enable").
    rule_list : list of RuleArguments, optional
        A list of rule argument tuples, where each tuple contains:
        (rule_type, channel, initial_value, show_on_true, visMin, visMax).
    hide_on_disconnect_channel : str, optional
        An additional channel used to hide the widget if it disconnects.
    initial_value : bool, optional
        Default value for the rule when no conditions are satisfied. Defaults to False.
    notes : str, optional
        Additional metadata or notes about the rule.
    """

    rule_type: str
    rule_list: Optional[List[RuleArguments]] = None
    hide_on_disconnect_channel: Optional[str] = None
    initial_value: Optional[bool] = False
    notes: Optional[str] = ""

    def to_string(self):
        """
        Convert the rule properties to a string.

        Returns
        -------
        str
            A string representing the rule.
        """

        channel_list = []
        expression_list = []
        if self.rule_list is not None:
            for i, rule in enumerate(self.rule_list):
                channel = rule.channel
                replacement_init = None
                if channel.startswith("loc://") and "init=${" in channel:
                    replacement_init = channel[channel.find("init=") + len("init=") :]
                    replacement_init = replacement_init[: replacement_init.find("}") + 1]
                channel_list.append({"channel": channel, "trigger": True, "use_enum": False})
                expression_list.append(
                    self.get_expression(
                        i, rule.show_on_true, rule.visMin, rule.visMax, replacement_init, rule.or_outside
                    )
                )
        if self.hide_on_disconnect_channel is not None:
            new_index = len(self.rule_list)
            replacement_init = None
            if self.hide_on_disconnect_channel.startswith("loc://") and "init=${" in self.hide_on_disconnect_channel:
                replacement_init = self.hide_on_disconnect_channel[
                    self.hide_on_disconnect_channel.find("init=") + len("init=") :
                ]
                replacement_init = replacement_init[: replacement_init.find("}") + 1]
            expression_list.append(self.get_hide_on_disconnect_expression(new_index, replacement_init))
            channel_list.append({"channel": self.hide_on_disconnect_channel, "trigger": True, "use_enum": False})
        if not expression_list:
            return ""
        expression_str = "(" + ") and (".join(expression_list) + ")"
        # Until its channels connect the widget shows the initial value: true
        # only when every condition asks for it.
        starts_true = (
            bool(self.rule_list)
            and self.hide_on_disconnect_channel is None
            and all(rule.initial_value for rule in self.rule_list)
        )

        return _json_object(
            {
                "name": self.rule_type,
                "property": self.rule_type,
                "initial_value": "true" if starts_true else "false",
                "expression": expression_str,
                "channels": channel_list,
                "notes": self.notes,
            }
        )

    def get_expression(
        self, index, show_on_true, visMin, visMax, init, or_outside=None
    ):  # TODO: Can clean up with fstrings
        """
        Build a conditional expression string for a specific channel.

        Parameters
        ----------
        index : int
            The index of the channel in the rule list.
        show_on_true : bool
            Whether the expression should evaluate to true on match.
        visMin : int, optional
            Minimum threshold value for range-based conditions.
        visMax : int, optional
            Maximum threshold value for range-based conditions.
        init : str, optional
            Replacement initialization value for the channel, if applicable.
        or_outside : tuple of (min, max), optional
            Ranges a range rule shown on true also holds outside of: it is true
            while the value is in its range or in none of these.

        Returns
        -------
        str
            A string representing the conditional expression for the given channel.
        """

        ch = f"ch[{index}]"

        if visMin is not None and visMax is not None:
            vis_min, vis_max = _range_limits(visMin, visMax)
            show_on_true_string = f"float({ch}) >= {vis_min} and float({ch}) < {vis_max}"
            show_on_false_string = f"float({ch}) < {vis_min} or float({ch}) >= {vis_max}"
            if or_outside is not None:
                # An empty range holds no value, so being outside it says nothing.
                limits = (_range_limits(*other) for other in or_outside)
                outside = [f"(float({ch}) < {low} or float({ch}) >= {high})" for low, high in limits if low < high]
                show_on_true_string = f"({show_on_true_string}) or ({' and '.join(outside) or 'True'})"
        else:
            show_on_true_string = f"{ch}==1"
            show_on_false_string = f"{ch}!=1"  # TODO: maybe need to change from specifically 1 (== 0 or != 0)?

        return show_on_true_string if show_on_true else show_on_false_string

    def get_hide_on_disconnect_expression(self, index, init):
        """
        Build an expression that ensures the widget is hidden if a channel disconnects.

        Parameters
        ----------
        index : int
            The index of the disconnect channel in the channel list.

        Returns
        -------
        str
            An expression string that evaluates true when the channel is connected.
        """

        ch = f"ch[{index}]"

        return f"{ch} is not None"

get_expression(index, show_on_true, visMin, visMax, init, or_outside=None)

Build a conditional expression string for a specific channel.

Parameters

index : int The index of the channel in the rule list. show_on_true : bool Whether the expression should evaluate to true on match. visMin : int, optional Minimum threshold value for range-based conditions. visMax : int, optional Maximum threshold value for range-based conditions. init : str, optional Replacement initialization value for the channel, if applicable. or_outside : tuple of (min, max), optional Ranges a range rule shown on true also holds outside of: it is true while the value is in its range or in none of these.

Returns

str A string representing the conditional expression for the given channel.

Source code in pydmconverter/widgets_helpers.py

def get_expression(
    self, index, show_on_true, visMin, visMax, init, or_outside=None
):  # TODO: Can clean up with fstrings
    """
    Build a conditional expression string for a specific channel.

    Parameters
    ----------
    index : int
        The index of the channel in the rule list.
    show_on_true : bool
        Whether the expression should evaluate to true on match.
    visMin : int, optional
        Minimum threshold value for range-based conditions.
    visMax : int, optional
        Maximum threshold value for range-based conditions.
    init : str, optional
        Replacement initialization value for the channel, if applicable.
    or_outside : tuple of (min, max), optional
        Ranges a range rule shown on true also holds outside of: it is true
        while the value is in its range or in none of these.

    Returns
    -------
    str
        A string representing the conditional expression for the given channel.
    """

    ch = f"ch[{index}]"

    if visMin is not None and visMax is not None:
        vis_min, vis_max = _range_limits(visMin, visMax)
        show_on_true_string = f"float({ch}) >= {vis_min} and float({ch}) < {vis_max}"
        show_on_false_string = f"float({ch}) < {vis_min} or float({ch}) >= {vis_max}"
        if or_outside is not None:
            # An empty range holds no value, so being outside it says nothing.
            limits = (_range_limits(*other) for other in or_outside)
            outside = [f"(float({ch}) < {low} or float({ch}) >= {high})" for low, high in limits if low < high]
            show_on_true_string = f"({show_on_true_string}) or ({' and '.join(outside) or 'True'})"
    else:
        show_on_true_string = f"{ch}==1"
        show_on_false_string = f"{ch}!=1"  # TODO: maybe need to change from specifically 1 (== 0 or != 0)?

    return show_on_true_string if show_on_true else show_on_false_string

get_hide_on_disconnect_expression(index, init)

Build an expression that ensures the widget is hidden if a channel disconnects.

Parameters

index : int The index of the disconnect channel in the channel list.

Returns

str An expression string that evaluates true when the channel is connected.

Source code in pydmconverter/widgets_helpers.py

def get_hide_on_disconnect_expression(self, index, init):
    """
    Build an expression that ensures the widget is hidden if a channel disconnects.

    Parameters
    ----------
    index : int
        The index of the disconnect channel in the channel list.

    Returns
    -------
    str
        An expression string that evaluates true when the channel is connected.
    """

    ch = f"ch[{index}]"

    return f"{ch} is not None"

to_string()

Convert the rule properties to a string.

Returns

str A string representing the rule.

Source code in pydmconverter/widgets_helpers.py

def to_string(self):
    """
    Convert the rule properties to a string.

    Returns
    -------
    str
        A string representing the rule.
    """

    channel_list = []
    expression_list = []
    if self.rule_list is not None:
        for i, rule in enumerate(self.rule_list):
            channel = rule.channel
            replacement_init = None
            if channel.startswith("loc://") and "init=${" in channel:
                replacement_init = channel[channel.find("init=") + len("init=") :]
                replacement_init = replacement_init[: replacement_init.find("}") + 1]
            channel_list.append({"channel": channel, "trigger": True, "use_enum": False})
            expression_list.append(
                self.get_expression(
                    i, rule.show_on_true, rule.visMin, rule.visMax, replacement_init, rule.or_outside
                )
            )
    if self.hide_on_disconnect_channel is not None:
        new_index = len(self.rule_list)
        replacement_init = None
        if self.hide_on_disconnect_channel.startswith("loc://") and "init=${" in self.hide_on_disconnect_channel:
            replacement_init = self.hide_on_disconnect_channel[
                self.hide_on_disconnect_channel.find("init=") + len("init=") :
            ]
            replacement_init = replacement_init[: replacement_init.find("}") + 1]
        expression_list.append(self.get_hide_on_disconnect_expression(new_index, replacement_init))
        channel_list.append({"channel": self.hide_on_disconnect_channel, "trigger": True, "use_enum": False})
    if not expression_list:
        return ""
    expression_str = "(" + ") and (".join(expression_list) + ")"
    # Until its channels connect the widget shows the initial value: true
    # only when every condition asks for it.
    starts_true = (
        bool(self.rule_list)
        and self.hide_on_disconnect_channel is None
        and all(rule.initial_value for rule in self.rule_list)
    )

    return _json_object(
        {
            "name": self.rule_type,
            "property": self.rule_type,
            "initial_value": "true" if starts_true else "false",
            "expression": expression_str,
            "channels": channel_list,
            "notes": self.notes,
        }
    )

OnOffColor dataclass

Bases: XMLConvertible

Represents the on/offColor property for a widget.

Attributes

onOff : str The prefix for _color (either on or off). red : int The red component. green : int The green component. blue : int The blue component. alpha : int, optional The alpha component, default is 255.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class OnOffColor(XMLConvertible):
    """
    Represents the on/offColor property for a widget.

    Attributes
    ----------
    onOff : str
        The prefix for _color (either on or off).
    red : int
        The red component.
    green : int
        The green component.
    blue : int
        The blue component.
    alpha : int, optional
        The alpha component, default is 255.
    """

    onOff: str  # TODO: Make this an enum?
    red: int
    green: int
    blue: int
    alpha: int = 255

    def to_xml(self) -> etree.Element:
        """
        Convert the onOff color property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the on//offcolor.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": f"{self.onOff}Color", "stdset": "0"})
        color: Color = Color(self.red, self.green, self.blue, alpha=self.alpha)
        prop.append(color.to_xml())
        return prop

to_xml()

Convert the onOff color property to an XML element.

Returns

etree.Element The XML element representing the on//offcolor.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the onOff color property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the on//offcolor.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": f"{self.onOff}Color", "stdset": "0"})
    color: Color = Color(self.red, self.green, self.blue, alpha=self.alpha)
    prop.append(color.to_xml())
    return prop

PageHeader

Source code in pydmconverter/widgets_helpers.py

class PageHeader:
    def create_page_header(self, edm_parser, scrollable=False, content_size=None):
        """
        Build the .ui skeleton (Form, optional scroll area, centralwidget) for a screen.

        Parameters
        ----------
        edm_parser : EDMFileParser
            Parser whose ui holds the screen's declared size and properties.
        scrollable : bool, optional
            Wrap centralwidget in a QScrollArea, by default False.
        content_size : tuple[int, int], optional
            (width, height) needed to cover the screen's widgets. centralwidget, and in
            scrollable mode scrollAreaWidgetContents, are given this size so content placed past
            the declared screen size stays reachable; Form and the scroll area keep the declared
            size. Defaults to the declared screen size.

        Returns
        -------
        tuple[ET.Element, ET.Element]
            The <ui> root element and the centralwidget element to add widgets to.
        """
        if content_size is None:
            content_size = (edm_parser.ui.width, edm_parser.ui.height)
        content_width, content_height = content_size

        ui_element = ET.Element("ui", attrib={"version": "4.0"})

        class_element = ET.SubElement(ui_element, "class")
        class_element.text = "QWidget"

        main_widget = ET.SubElement(
            ui_element,
            "widget",
            attrib={
                "class": "QWidget",
                "name": "Form",
            },
        )

        geometry = ET.SubElement(main_widget, "property", attrib={"name": "geometry"})
        rect = ET.SubElement(geometry, "rect")
        ET.SubElement(rect, "x").text = "0"
        ET.SubElement(rect, "y").text = "0"

        """
        if scrollable:  # Setting max values for the screen to be initially
            ET.SubElement(rect, "width").text = str(min(edm_parser.ui.width, 120))
            ET.SubElement(rect, "height").text = str(min(edm_parser.ui.height, 80))
        else:
            ET.SubElement(rect, "width").text = str(edm_parser.ui.width)
            ET.SubElement(rect, "height").text = str(edm_parser.ui.height)
        """

        ET.SubElement(rect, "width").text = str(edm_parser.ui.width)
        ET.SubElement(rect, "height").text = str(edm_parser.ui.height)

        screen_properties: dict[str, str] = edm_parser.ui.properties

        # Set window title from EDM screen properties if available, otherwise use default
        window_title = ET.SubElement(main_widget, "property", attrib={"name": "windowTitle"})
        title_string = ET.SubElement(window_title, "string")
        title_string.text = screen_properties.get("title", "PyDM Screen")

        self.add_screen_properties(main_widget, screen_properties)

        if scrollable:
            logger.info("Creating scrollable PyDM window")
            layout = ET.SubElement(main_widget, "layout", attrib={"class": "QVBoxLayout", "name": "verticalLayout"})
            layout_item = ET.SubElement(layout, "item")
            scroll_area = ET.SubElement(layout_item, "widget", attrib={"class": "QScrollArea", "name": "scrollArea"})

            sa_geometry = ET.SubElement(scroll_area, "property", attrib={"name": "geometry"})
            sa_rect = ET.SubElement(sa_geometry, "rect")
            ET.SubElement(sa_rect, "x").text = "0"
            ET.SubElement(sa_rect, "y").text = "0"
            ET.SubElement(sa_rect, "width").text = str(edm_parser.ui.width)
            ET.SubElement(sa_rect, "height").text = str(edm_parser.ui.height)
            widget_resizable = ET.SubElement(scroll_area, "property", attrib={"name": "widgetResizable"})
            ET.SubElement(widget_resizable, "bool").text = "false"

            scroll_contents = ET.SubElement(
                scroll_area, "widget", attrib={"class": "QWidget", "name": "scrollAreaWidgetContents"}
            )
            sc_geometry = ET.SubElement(scroll_contents, "property", attrib={"name": "geometry"})
            sc_rect = ET.SubElement(sc_geometry, "rect")
            ET.SubElement(sc_rect, "x").text = "0"
            ET.SubElement(sc_rect, "y").text = "0"
            ET.SubElement(sc_rect, "width").text = str(content_width)
            ET.SubElement(sc_rect, "height").text = str(content_height)

            central_widget = ET.SubElement(
                scroll_contents,
                "widget",
                attrib={
                    "class": "QWidget",
                    "name": "centralwidget",
                },
            )
        else:
            central_widget = ET.SubElement(
                main_widget,
                "widget",
                attrib={
                    "class": "QWidget",
                    "name": "centralwidget",
                },
            )

        # centralwidget has no layout; without an explicit geometry Qt adjustSize()s it to the
        # children visible at first show, clipping rule-hidden widgets that appear later.
        cw_geometry = ET.SubElement(central_widget, "property", attrib={"name": "geometry"})
        cw_rect = ET.SubElement(cw_geometry, "rect")
        ET.SubElement(cw_rect, "x").text = "0"
        ET.SubElement(cw_rect, "y").text = "0"
        ET.SubElement(cw_rect, "width").text = str(content_width)
        ET.SubElement(cw_rect, "height").text = str(content_height)

        return ui_element, central_widget

    """def add_screen_properties(self, main_widget: ET.Element, properties: dict[str, Any]) -> None:
        if "bgColor" in properties:
            style_prop = ET.SubElement(main_widget, "property", attrib={"name": "styleSheet"})
            style_string = ET.SubElement(style_prop, "string")
            style_string.text = f"#Form {{ background-color: rgba{properties['bgColor']} }}"  # commented code adds bg to all child widgets but for now, this is fine
            # TODO: There is a bug that the background does not show up normally but does in designer"""

    def add_screen_properties(self, main_widget: ET, properties: dict[str, Any]) -> None:
        if "bgColor" in properties:
            style_prop = ET.SubElement(main_widget, "property", attrib={"name": "styleSheet"})
            style_string = ET.SubElement(style_prop, "string")

            central_bg_dict = {"background-color": properties["bgColor"]}
            style_string.text = f"{StyleSheet(central_bg_dict).to_style_string()}"

create_page_header(edm_parser, scrollable=False, content_size=None)

Build the .ui skeleton (Form, optional scroll area, centralwidget) for a screen.

Parameters

edm_parser : EDMFileParser Parser whose ui holds the screen's declared size and properties. scrollable : bool, optional Wrap centralwidget in a QScrollArea, by default False. content_size : tuple[int, int], optional (width, height) needed to cover the screen's widgets. centralwidget, and in scrollable mode scrollAreaWidgetContents, are given this size so content placed past the declared screen size stays reachable; Form and the scroll area keep the declared size. Defaults to the declared screen size.

Returns

tuple[ET.Element, ET.Element] The root element and the centralwidget element to add widgets to.

Source code in pydmconverter/widgets_helpers.py

def create_page_header(self, edm_parser, scrollable=False, content_size=None):
    """
    Build the .ui skeleton (Form, optional scroll area, centralwidget) for a screen.

    Parameters
    ----------
    edm_parser : EDMFileParser
        Parser whose ui holds the screen's declared size and properties.
    scrollable : bool, optional
        Wrap centralwidget in a QScrollArea, by default False.
    content_size : tuple[int, int], optional
        (width, height) needed to cover the screen's widgets. centralwidget, and in
        scrollable mode scrollAreaWidgetContents, are given this size so content placed past
        the declared screen size stays reachable; Form and the scroll area keep the declared
        size. Defaults to the declared screen size.

    Returns
    -------
    tuple[ET.Element, ET.Element]
        The <ui> root element and the centralwidget element to add widgets to.
    """
    if content_size is None:
        content_size = (edm_parser.ui.width, edm_parser.ui.height)
    content_width, content_height = content_size

    ui_element = ET.Element("ui", attrib={"version": "4.0"})

    class_element = ET.SubElement(ui_element, "class")
    class_element.text = "QWidget"

    main_widget = ET.SubElement(
        ui_element,
        "widget",
        attrib={
            "class": "QWidget",
            "name": "Form",
        },
    )

    geometry = ET.SubElement(main_widget, "property", attrib={"name": "geometry"})
    rect = ET.SubElement(geometry, "rect")
    ET.SubElement(rect, "x").text = "0"
    ET.SubElement(rect, "y").text = "0"

    """
    if scrollable:  # Setting max values for the screen to be initially
        ET.SubElement(rect, "width").text = str(min(edm_parser.ui.width, 120))
        ET.SubElement(rect, "height").text = str(min(edm_parser.ui.height, 80))
    else:
        ET.SubElement(rect, "width").text = str(edm_parser.ui.width)
        ET.SubElement(rect, "height").text = str(edm_parser.ui.height)
    """

    ET.SubElement(rect, "width").text = str(edm_parser.ui.width)
    ET.SubElement(rect, "height").text = str(edm_parser.ui.height)

    screen_properties: dict[str, str] = edm_parser.ui.properties

    # Set window title from EDM screen properties if available, otherwise use default
    window_title = ET.SubElement(main_widget, "property", attrib={"name": "windowTitle"})
    title_string = ET.SubElement(window_title, "string")
    title_string.text = screen_properties.get("title", "PyDM Screen")

    self.add_screen_properties(main_widget, screen_properties)

    if scrollable:
        logger.info("Creating scrollable PyDM window")
        layout = ET.SubElement(main_widget, "layout", attrib={"class": "QVBoxLayout", "name": "verticalLayout"})
        layout_item = ET.SubElement(layout, "item")
        scroll_area = ET.SubElement(layout_item, "widget", attrib={"class": "QScrollArea", "name": "scrollArea"})

        sa_geometry = ET.SubElement(scroll_area, "property", attrib={"name": "geometry"})
        sa_rect = ET.SubElement(sa_geometry, "rect")
        ET.SubElement(sa_rect, "x").text = "0"
        ET.SubElement(sa_rect, "y").text = "0"
        ET.SubElement(sa_rect, "width").text = str(edm_parser.ui.width)
        ET.SubElement(sa_rect, "height").text = str(edm_parser.ui.height)
        widget_resizable = ET.SubElement(scroll_area, "property", attrib={"name": "widgetResizable"})
        ET.SubElement(widget_resizable, "bool").text = "false"

        scroll_contents = ET.SubElement(
            scroll_area, "widget", attrib={"class": "QWidget", "name": "scrollAreaWidgetContents"}
        )
        sc_geometry = ET.SubElement(scroll_contents, "property", attrib={"name": "geometry"})
        sc_rect = ET.SubElement(sc_geometry, "rect")
        ET.SubElement(sc_rect, "x").text = "0"
        ET.SubElement(sc_rect, "y").text = "0"
        ET.SubElement(sc_rect, "width").text = str(content_width)
        ET.SubElement(sc_rect, "height").text = str(content_height)

        central_widget = ET.SubElement(
            scroll_contents,
            "widget",
            attrib={
                "class": "QWidget",
                "name": "centralwidget",
            },
        )
    else:
        central_widget = ET.SubElement(
            main_widget,
            "widget",
            attrib={
                "class": "QWidget",
                "name": "centralwidget",
            },
        )

    # centralwidget has no layout; without an explicit geometry Qt adjustSize()s it to the
    # children visible at first show, clipping rule-hidden widgets that appear later.
    cw_geometry = ET.SubElement(central_widget, "property", attrib={"name": "geometry"})
    cw_rect = ET.SubElement(cw_geometry, "rect")
    ET.SubElement(cw_rect, "x").text = "0"
    ET.SubElement(cw_rect, "y").text = "0"
    ET.SubElement(cw_rect, "width").text = str(content_width)
    ET.SubElement(cw_rect, "height").text = str(content_height)

    return ui_element, central_widget

PenColor dataclass

Bases: XMLConvertible

Represents a pen color property for a widget.

Attributes

red : int The red component. green : int The green component. blue : int The blue component. alpha : int, optional The alpha component, default is 255.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class PenColor(XMLConvertible):
    """
    Represents a pen color property for a widget.

    Attributes
    ----------
    red : int
        The red component.
    green : int
        The green component.
    blue : int
        The blue component.
    alpha : int, optional
        The alpha component, default is 255.
    """

    red: int
    green: int
    blue: int
    alpha: int = 255

    def to_xml(self) -> etree.Element:
        """
        Convert the pen color property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the pen color.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": "penColor", "stdset": "0"})
        color: Color = Color(self.red, self.green, self.blue, alpha=self.alpha)
        prop.append(color.to_xml())
        return prop

to_xml()

Convert the pen color property to an XML element.

Returns

etree.Element The XML element representing the pen color.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the pen color property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the pen color.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": "penColor", "stdset": "0"})
    color: Color = Color(self.red, self.green, self.blue, alpha=self.alpha)
    prop.append(color.to_xml())
    return prop

PenStyle dataclass

Bases: XMLConvertible

Represents a pen style property for a widget.

Attributes

style : Optional[str] The style of the pen ('dash' for dashed, otherwise solid).

Source code in pydmconverter/widgets_helpers.py

@dataclass
class PenStyle(XMLConvertible):
    """
    Represents a pen style property for a widget.

    Attributes
    ----------
    style : Optional[str]
        The style of the pen ('dash' for dashed, otherwise solid).
    """

    style: Optional[str] = None

    def to_xml(self) -> etree.Element:
        """
        Convert the pen style property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the pen style.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": "penStyle", "stdset": "0"})
        enum: etree.Element = etree.SubElement(prop, "enum")
        enum.text = "Qt::DashLine" if self.style == "dash" else "Qt::SolidLine"
        return prop

to_xml()

Convert the pen style property to an XML element.

Returns

etree.Element The XML element representing the pen style.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the pen style property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the pen style.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": "penStyle", "stdset": "0"})
    enum: etree.Element = etree.SubElement(prop, "enum")
    enum.text = "Qt::DashLine" if self.style == "dash" else "Qt::SolidLine"
    return prop

PenWidth dataclass

Bases: XMLConvertible

Represents a pen width property for a widget.

Attributes

width : Optional[int] The width of the pen.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class PenWidth(XMLConvertible):
    """
    Represents a pen width property for a widget.

    Attributes
    ----------
    width : Optional[int]
        The width of the pen.
    """

    width: Optional[int] = None

    def to_xml(self) -> etree.Element:
        """
        Convert the pen width property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the pen width.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": "penWidth", "stdset": "0"})
        double_elem: etree.Element = etree.SubElement(prop, "double")
        double_elem.text = str(self.width)
        return prop

to_xml()

Convert the pen width property to an XML element.

Returns

etree.Element The XML element representing the pen width.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the pen width property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the pen width.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": "penWidth", "stdset": "0"})
    double_elem: etree.Element = etree.SubElement(prop, "double")
    double_elem.text = str(self.width)
    return prop

PixMap dataclass

Bases: XMLConvertible

Represents an image widget.

Attributes

filename : str The filename of the imported image.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class PixMap(XMLConvertible):
    """
    Represents an image widget.

    Attributes
    ----------
    filename : str
        The filename of the imported image.
    """

    filename: str

    def to_xml(self) -> etree.Element:
        """
        Convert the filename property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the image.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": "pixmap"})
        pixmap_tag: etree.Element = etree.SubElement(prop, "pixmap")
        pixmap_tag.text = self.filename
        return prop

to_xml()

Convert the filename property to an XML element.

Returns

etree.Element The XML element representing the image.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the filename property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the image.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": "pixmap"})
    pixmap_tag: etree.Element = etree.SubElement(prop, "pixmap")
    pixmap_tag.text = self.filename
    return prop

PyDMToolTip dataclass

Bases: XMLConvertible

Represents a tooltip for a PyDM widget.

Attributes

PyDMToolTip : str The tooltip text.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class PyDMToolTip(XMLConvertible):
    """
    Represents a tooltip for a PyDM widget.

    Attributes
    ----------
    PyDMToolTip : str
        The tooltip text.
    """

    PyDMToolTip: str

    def to_xml(self) -> etree.Element:
        """
        Convert the tooltip to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the tooltip.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": "PyDMToolTip", "stdset": "0"})
        string_elem: etree.Element = etree.SubElement(prop, "string")
        string_elem.text = self.PyDMToolTip
        return prop

to_xml()

Convert the tooltip to an XML element.

Returns

etree.Element The XML element representing the tooltip.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the tooltip to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the tooltip.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": "PyDMToolTip", "stdset": "0"})
    string_elem: etree.Element = etree.SubElement(prop, "string")
    string_elem.text = self.PyDMToolTip
    return prop

RGBABackgroundSheet dataclass

Bases: XMLConvertible

Represents a background style sheet with an RGBA (Red, Green, Blue, Alpha) color.

Attributes:

Name	Type	Description
red		int Red component of the background color (0–255).
green		int Green component of the background color (0–255).
blue		int Blue component of the background color (0–255).
alpha		int Alpha transparency value (0–255).

Source code in pydmconverter/widgets_helpers.py

@dataclass
class RGBABackgroundSheet(XMLConvertible):  # eventually combine with rgbastylesheet
    """
    Represents a background style sheet with an RGBA (Red, Green, Blue, Alpha) color.

    Attributes:
        red : int
            Red component of the background color (0–255).
        green : int
            Green component of the background color (0–255).
        blue : int
            Blue component of the background color (0–255).
        alpha : int
            Alpha transparency value (0–255).
    """

    red: int
    green: int
    blue: int
    alpha: int = 255

    def to_xml(self):
        """
        Convert the stylesheet to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the background stylesheet.
        """
        style = f"background-color: rgba({self.red}, {self.green}, {self.blue}, {round(self.alpha / 255, 2)});"
        prop = ET.Element("property", {"name": "styleSheet"})
        string_elem = ET.SubElement(prop, "string")
        string_elem.text = style
        return prop

to_xml()

Convert the stylesheet to an XML element.

Returns

etree.Element The XML element representing the background stylesheet.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self):
    """
    Convert the stylesheet to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the background stylesheet.
    """
    style = f"background-color: rgba({self.red}, {self.green}, {self.blue}, {round(self.alpha / 255, 2)});"
    prop = ET.Element("property", {"name": "styleSheet"})
    string_elem = ET.SubElement(prop, "string")
    string_elem.text = style
    return prop

RGBAStyleSheet dataclass

Bases: XMLConvertible

Represents a background style sheet with an RGBA (Red, Green, Blue, Alpha) color.

Attributes:

Name	Type	Description
red		int Red component of the background color (0–255).
green		int Green component of the background color (0–255).
blue		int Blue component of the background color (0–255).
alpha		int Alpha transparency value (0–255).

Source code in pydmconverter/widgets_helpers.py

@dataclass
class RGBAStyleSheet(XMLConvertible):
    """
    Represents a background style sheet with an RGBA (Red, Green, Blue, Alpha) color.

    Attributes:
        red : int
            Red component of the background color (0–255).
        green : int
            Green component of the background color (0–255).
        blue : int
            Blue component of the background color (0–255).
        alpha : int
            Alpha transparency value (0–255).
    """

    red: int
    green: int
    blue: int
    alpha: int = 255

    def to_xml(self):
        """
        Convert the stylesheet into an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the image.
        """

        style = f"color: rgba({self.red}, {self.green}, {self.blue}, {round(self.alpha / 255, 2)}); background-color: transparent;"
        prop = ET.Element("property", {"name": "styleSheet"})
        string_elem = ET.SubElement(prop, "string")
        string_elem.text = style
        return prop

to_xml()

Convert the stylesheet into an XML element.

Returns

etree.Element The XML element representing the image.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self):
    """
    Convert the stylesheet into an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the image.
    """

    style = f"color: rgba({self.red}, {self.green}, {self.blue}, {round(self.alpha / 255, 2)}); background-color: transparent;"
    prop = ET.Element("property", {"name": "styleSheet"})
    string_elem = ET.SubElement(prop, "string")
    string_elem.text = style
    return prop

Rotation dataclass

Bases: XMLConvertible

Represents a rotation property for a widget.

Attributes

name : str The name of the rotation property. value : float The rotation angle.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Rotation(XMLConvertible):
    """
    Represents a rotation property for a widget.

    Attributes
    ----------
    name : str
        The name of the rotation property.
    value : float
        The rotation angle.
    """

    name: str
    value: float

    def to_xml(self) -> etree.Element:
        """
        Convert the rotation property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the rotation.
        """
        element: etree.Element = etree.Element(self.name)
        element.text = str(self.value)
        return element

to_xml()

Convert the rotation property to an XML element.

Returns

etree.Element The XML element representing the rotation.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the rotation property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the rotation.
    """
    element: etree.Element = etree.Element(self.name)
    element.text = str(self.value)
    return element

Row dataclass

Bases: XMLConvertible

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Row(XMLConvertible):
    value: Optional[str]
    font: dict = field(default_factory=dict)

    def to_xml(self) -> etree.Element:
        """
        Convert the Row properties to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the font.
        """
        row: etree.Element = etree.Element("row")
        prop: etree.Element = etree.SubElement(row, "property", attrib={"name": "text"})
        string_tag: etree.Element = etree.SubElement(prop, "string")
        string_tag.text = self.value
        row.append(Font(**self.font).to_xml())
        return row

to_xml()

Convert the Row properties to an XML element.

Returns

etree.Element The XML element representing the font.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the Row properties to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the font.
    """
    row: etree.Element = etree.Element("row")
    prop: etree.Element = etree.SubElement(row, "property", attrib={"name": "text"})
    string_tag: etree.Element = etree.SubElement(prop, "string")
    string_tag.text = self.value
    row.append(Font(**self.font).to_xml())
    return row

Rules dataclass

Bases: XMLConvertible

Represents a collection of rules grouped by type.

Attributes

rules : list of RuleArguments A list of rule argument tuples, where each tuple contains: (rule_type, channel, initial_value, show_on_true, visMin, visMax). hide_on_disconnect_channel : str, optional An additional channel used to hide widgets if it disconnects. extra_rules : list of dict, optional Complete PyDM rules for other properties (an embedded display's Filename), written after the grouped ones as given.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Rules(XMLConvertible):
    """
    Represents a collection of rules grouped by type.

    Attributes
    ----------
    rules : list of RuleArguments
        A list of rule argument tuples, where each tuple contains:
        (rule_type, channel, initial_value, show_on_true, visMin, visMax).
    hide_on_disconnect_channel : str, optional
        An additional channel used to hide widgets if it disconnects.
    extra_rules : list of dict, optional
        Complete PyDM rules for other properties (an embedded display's
        Filename), written after the grouped ones as given.
    """

    rules: List[RuleArguments]
    hide_on_disconnect_channel: Optional[str] = None
    extra_rules: List[Dict[str, Any]] = field(default_factory=list)

    def to_xml(self):
        """
        Convert the collection of rules into an XML element.

        Returns
        -------
        etree.Element
            An XML element representing all grouped rules.
        """

        rule_list = []
        rule_variables = self.group_by_rules()

        for rule_type, rule_var_list in rule_variables.items():
            if rule_var_list:
                rule_string = MultiRule(rule_type, rule_var_list, self.hide_on_disconnect_channel).to_string()
                rule_list.append(rule_string)
            elif rule_type == "Visible":
                rule_string = MultiRule(rule_type, [], self.hide_on_disconnect_channel).to_string()
                # "" when there is no channel to hide on: leave it out of the list.
                if rule_string:
                    rule_list.append(rule_string)
        rule_list.extend(_json_object(rule) for rule in self.extra_rules)
        output_string = f"[{', '.join(rule_list)}]"
        return Str("rules", output_string).to_xml()

    def group_by_rules(self):
        """
        Group rules by their rule type, removing duplicates.

        Returns
        -------
        dict of str to list of RuleArguments
            A dictionary where the keys are rule types (e.g., "Visible", "Enable"),
            and the values are lists of unique rules for that type, each in the
            order its first occurrence was added.
        """

        bool_rule_types = ["Visible", "Enable"]
        rule_variables = {key: [] for key in bool_rule_types}
        for rule in self.rules:
            if rule.rule_type in rule_variables:
                rule_variables[rule.rule_type].append(rule)
        for rule_name in rule_variables.keys():
            # Drop repeats but keep the first of each in place: a set's order follows
            # the string hashes, so the terms would change order with PYTHONHASHSEED.
            rule_variables[rule_name] = list(dict.fromkeys(rule_variables[rule_name]))
        return rule_variables

group_by_rules()

Group rules by their rule type, removing duplicates.

Returns

dict of str to list of RuleArguments A dictionary where the keys are rule types (e.g., "Visible", "Enable"), and the values are lists of unique rules for that type, each in the order its first occurrence was added.

Source code in pydmconverter/widgets_helpers.py

def group_by_rules(self):
    """
    Group rules by their rule type, removing duplicates.

    Returns
    -------
    dict of str to list of RuleArguments
        A dictionary where the keys are rule types (e.g., "Visible", "Enable"),
        and the values are lists of unique rules for that type, each in the
        order its first occurrence was added.
    """

    bool_rule_types = ["Visible", "Enable"]
    rule_variables = {key: [] for key in bool_rule_types}
    for rule in self.rules:
        if rule.rule_type in rule_variables:
            rule_variables[rule.rule_type].append(rule)
    for rule_name in rule_variables.keys():
        # Drop repeats but keep the first of each in place: a set's order follows
        # the string hashes, so the terms would change order with PYTHONHASHSEED.
        rule_variables[rule_name] = list(dict.fromkeys(rule_variables[rule_name]))
    return rule_variables

to_xml()

Convert the collection of rules into an XML element.

Returns

etree.Element An XML element representing all grouped rules.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self):
    """
    Convert the collection of rules into an XML element.

    Returns
    -------
    etree.Element
        An XML element representing all grouped rules.
    """

    rule_list = []
    rule_variables = self.group_by_rules()

    for rule_type, rule_var_list in rule_variables.items():
        if rule_var_list:
            rule_string = MultiRule(rule_type, rule_var_list, self.hide_on_disconnect_channel).to_string()
            rule_list.append(rule_string)
        elif rule_type == "Visible":
            rule_string = MultiRule(rule_type, [], self.hide_on_disconnect_channel).to_string()
            # "" when there is no channel to hide on: leave it out of the list.
            if rule_string:
                rule_list.append(rule_string)
    rule_list.extend(_json_object(rule) for rule in self.extra_rules)
    output_string = f"[{', '.join(rule_list)}]"
    return Str("rules", output_string).to_xml()

Size dataclass

Bases: XMLConvertible

Represents a size property for a widget.

Attributes

name : str The name of the property. width : str The width value. height : str The height value.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Size(XMLConvertible):
    """
    Represents a size property for a widget.

    Attributes
    ----------
    name : str
        The name of the property.
    width : str
        The width value.
    height : str
        The height value.
    """

    name: str
    width: str
    height: str

    def to_xml(self) -> etree.Element:
        """
        Convert the size properties to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the size.
        """
        top: etree.Element = etree.Element("property", attrib={"name": self.name})
        size_elem: etree.Element = etree.SubElement(top, "size")
        width_elem: etree.Element = etree.SubElement(size_elem, "width")
        width_elem.text = self.width
        height_elem: etree.Element = etree.SubElement(size_elem, "height")
        height_elem.text = self.height
        return top

to_xml()

Convert the size properties to an XML element.

Returns

etree.Element The XML element representing the size.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the size properties to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the size.
    """
    top: etree.Element = etree.Element("property", attrib={"name": self.name})
    size_elem: etree.Element = etree.SubElement(top, "size")
    width_elem: etree.Element = etree.SubElement(size_elem, "width")
    width_elem.text = self.width
    height_elem: etree.Element = etree.SubElement(size_elem, "height")
    height_elem.text = self.height
    return top

SizePolicy dataclass

Bases: XMLConvertible

Represents the size policy for a widget.

Attributes

hsizetype : str The horizontal size type. vsizetype : str The vertical size type.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class SizePolicy(XMLConvertible):
    """
    Represents the size policy for a widget.

    Attributes
    ----------
    hsizetype : str
        The horizontal size type.
    vsizetype : str
        The vertical size type.
    """

    hsizetype: str
    vsizetype: str

    def to_xml(self) -> etree.Element:
        """
        Convert the size policy to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the size policy.
        """
        top: etree.Element = etree.Element("property", attrib={"name": "sizePolicy"})
        sizePolicy_elem: etree.Element = etree.SubElement(
            top,
            "sizepolicy",
            attrib={
                "hsizetype": self.hsizetype,
                "vsizetype": self.vsizetype,
            },
        )
        horstretch: etree.Element = etree.SubElement(sizePolicy_elem, "horstretch")
        horstretch.text = "0"
        verstretch: etree.Element = etree.SubElement(sizePolicy_elem, "verstretch")
        verstretch.text = "0"
        return top

to_xml()

Convert the size policy to an XML element.

Returns

etree.Element The XML element representing the size policy.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the size policy to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the size policy.
    """
    top: etree.Element = etree.Element("property", attrib={"name": "sizePolicy"})
    sizePolicy_elem: etree.Element = etree.SubElement(
        top,
        "sizepolicy",
        attrib={
            "hsizetype": self.hsizetype,
            "vsizetype": self.vsizetype,
        },
    )
    horstretch: etree.Element = etree.SubElement(sizePolicy_elem, "horstretch")
    horstretch.text = "0"
    verstretch: etree.Element = etree.SubElement(sizePolicy_elem, "verstretch")
    verstretch.text = "0"
    return top

Str dataclass

Bases: XMLConvertible

Represents a string property.

Attributes

name : str The name of the property. string : str The string value.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Str(XMLConvertible):
    """
    Represents a string property.

    Attributes
    ----------
    name : str
        The name of the property.
    string : str
        The string value.
    """

    name: str
    string: str | bool

    def to_xml(self) -> etree.Element:
        """
        Convert the string property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the string.
        """
        if (
            isinstance(self.string, bool) and self.string
        ):  # This came from edgecases with strings having empty values and were converted into bool True
            self.string = ""
        prop: etree.Element = etree.Element("property", attrib={"name": self.name, "stdset": "0"})
        string_tag: etree.Element = etree.SubElement(prop, "string")
        if isinstance(self.string, list):
            raise TypeError(f"Element <{self.string}> has list as .text: {self.string}")
        string_tag.text = self.string
        return prop

to_xml()

Convert the string property to an XML element.

Returns

etree.Element The XML element representing the string.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the string property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the string.
    """
    if (
        isinstance(self.string, bool) and self.string
    ):  # This came from edgecases with strings having empty values and were converted into bool True
        self.string = ""
    prop: etree.Element = etree.Element("property", attrib={"name": self.name, "stdset": "0"})
    string_tag: etree.Element = etree.SubElement(prop, "string")
    if isinstance(self.string, list):
        raise TypeError(f"Element <{self.string}> has list as .text: {self.string}")
    string_tag.text = self.string
    return prop

StringList dataclass

Bases: XMLConvertible

Represents a property containing a list of strings.

Attributes

name : str The name of the property. items : List[str] A list of string values.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class StringList(XMLConvertible):
    """
    Represents a property containing a list of strings.

    Attributes
    ----------
    name : str
        The name of the property.
    items : List[str]
        A list of string values.
    """

    name: str
    items: List[str]

    def to_xml(self) -> etree.Element:
        prop = etree.Element("property", attrib={"name": self.name, "stdset": "0"})
        stringlist = etree.SubElement(prop, "stringlist")

        for item in self.items:
            if not isinstance(item, str):
                raise TypeError(f"Expected string in StringList.items, got {type(item)}: {item}")
            string_el = etree.SubElement(stringlist, "string")
            string_el.text = item
        return prop

    def escape_for_stringlist(self, s: str) -> str:
        return s.replace("&", "&amp;").replace('"', "&quot;").replace("<", "&lt;").replace(">", "&gt;")

StyleSheet dataclass

Bases: XMLConvertible

Represents a stylesheet for a widget.

Attributes

styles : Dict[str, Any] Declarations for the widget. With no selector Qt applies them to the widget and every descendant. scoped : Dict[str, Dict[str, Any]] Declarations keyed by the selector they apply to, e.g. {"PyDMEmbeddedDisplay#name": {"border": "1px solid black"}}.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class StyleSheet(XMLConvertible):
    """
    Represents a stylesheet for a widget.

    Attributes
    ----------
    styles : Dict[str, Any]
        Declarations for the widget. With no selector Qt applies them to the
        widget and every descendant.
    scoped : Dict[str, Dict[str, Any]]
        Declarations keyed by the selector they apply to, e.g.
        ``{"PyDMEmbeddedDisplay#name": {"border": "1px solid black"}}``.
    """

    styles: Dict[str, Any]
    scoped: Dict[str, Dict[str, Any]] = field(default_factory=dict)

    def _format_value(self, key: str, value: Any) -> str:
        if isinstance(value, RGBA) and key in ("color", "background-color"):
            r, g, b, *a = value
            alpha = a[0] if a else 1.0
            return f"{key}: rgba({r}, {g}, {b}, {round(alpha, 2)});"
        return f"{key}: {value};"

    def to_style_string(self) -> str:
        return " ".join(self._format_value(k, v) for k, v in self.styles.items())

    def to_xml(self) -> etree.Element:
        """
        Convert the stylesheet to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the stylesheet.
        """
        prop = ET.Element("property", {"name": "styleSheet"})
        string_elem = ET.SubElement(prop, "string")
        style_str: str = self.to_style_string()
        if "background-color" not in self.styles:
            style_str += "background-color: none;"
        if self.scoped:
            # Qt reads a sheet without selectors as "* { ... }" and drops a sheet that
            # mixes bare declarations with selector rules, so the unscoped ones go
            # under "*" explicitly.
            rules = [f"* {{ {style_str} }}"]
            for selector, styles in self.scoped.items():
                declarations = " ".join(self._format_value(k, v) for k, v in styles.items())
                rules.append(f"{selector} {{ {declarations} }}")
            style_str = " ".join(rules)
        string_elem.text = style_str
        return prop

to_xml()

Convert the stylesheet to an XML element.

Returns

etree.Element The XML element representing the stylesheet.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the stylesheet to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the stylesheet.
    """
    prop = ET.Element("property", {"name": "styleSheet"})
    string_elem = ET.SubElement(prop, "string")
    style_str: str = self.to_style_string()
    if "background-color" not in self.styles:
        style_str += "background-color: none;"
    if self.scoped:
        # Qt reads a sheet without selectors as "* { ... }" and drops a sheet that
        # mixes bare declarations with selector rules, so the unscoped ones go
        # under "*" explicitly.
        rules = [f"* {{ {style_str} }}"]
        for selector, styles in self.scoped.items():
            declarations = " ".join(self._format_value(k, v) for k, v in styles.items())
            rules.append(f"{selector} {{ {declarations} }}")
        style_str = " ".join(rules)
    string_elem.text = style_str
    return prop

StyleSheetObject dataclass

Bases: Tangible

A base class for UI elements that support stylesheet-based customization.

Attributes

foreground_color : Optional[RGBA] RGBA color tuple for the foreground (text) color. background_color : Optional[RGBA] RGBA color tuple for the background color.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class StyleSheetObject(Tangible):
    """
    A base class for UI elements that support stylesheet-based customization.

    Attributes
    ----------
    foreground_color : Optional[RGBA]
        RGBA color tuple for the foreground (text) color.
    background_color : Optional[RGBA]
        RGBA color tuple for the background color.
    """

    foreground_color: Optional[RGBA] = None
    background_color: Optional[RGBA] = None
    useDisplayBg: Optional[bool] = None
    name: Optional[str] = ""
    # The declaration PyDM's stylesheet sets for alarm-sensitive content: the
    # text colour, or a button's or combo box's face. None: no declaration.
    alarm_content_style: ClassVar[Optional[str]] = "color"

    def alarm_content_rules(self) -> Dict[str, Dict[str, Any]]:
        """PyDM's alarm colours for this widget's content, as selector rules for
        its own stylesheet; none unless its content is alarm sensitive.

        A widget's own stylesheet beats the application's whatever the
        selectors, so its static colours would hide the alarm colours of
        PyDM's stylesheet: the widget carries them itself, under selectors
        more specific than its static colours' "*".
        """
        if self.alarm_content_style is None or not getattr(self, "alarm_sensitive_content", False):
            return {}
        widget_class = type(self).__name__
        return {
            f'{widget_class}[alarmSensitiveContent="true"][alarmSeverity="{severity}"]': {
                self.alarm_content_style: color
            }
            for severity, color in PYDM_ALARM_COLORS.items()
        }

    def generate_properties(self) -> List[ET.Element]:
        """
        Generate a list of XML property elements for this object, including
        any stylesheets derived from foreground or background color settings.

        Returns
        -------
        List[ET.Element]
            A list of XML elements representing properties, including inherited
            ones from the base class and additional style properties if specified.
        """
        properties: List[ET.Element] = super().generate_properties()

        # if self.background_color is not None or self.foreground_color is not None:
        styles: Dict[str, Any] = {}
        if self.background_color is not None and self.useDisplayBg is None:
            styles["background-color"] = self.background_color
        if self.foreground_color is not None:
            styles["color"] = self.foreground_color
        if self.name.startswith("activeMenuButtonClass") or self.name.startswith("activeMessageButtonClass"):
            styles["border"] = "1px solid black"
        properties.append(StyleSheet(styles, self.alarm_content_rules()).to_xml())

        return properties

alarm_content_rules()

PyDM's alarm colours for this widget's content, as selector rules for its own stylesheet; none unless its content is alarm sensitive.

A widget's own stylesheet beats the application's whatever the selectors, so its static colours would hide the alarm colours of PyDM's stylesheet: the widget carries them itself, under selectors more specific than its static colours' "*".

Source code in pydmconverter/widgets_helpers.py

def alarm_content_rules(self) -> Dict[str, Dict[str, Any]]:
    """PyDM's alarm colours for this widget's content, as selector rules for
    its own stylesheet; none unless its content is alarm sensitive.

    A widget's own stylesheet beats the application's whatever the
    selectors, so its static colours would hide the alarm colours of
    PyDM's stylesheet: the widget carries them itself, under selectors
    more specific than its static colours' "*".
    """
    if self.alarm_content_style is None or not getattr(self, "alarm_sensitive_content", False):
        return {}
    widget_class = type(self).__name__
    return {
        f'{widget_class}[alarmSensitiveContent="true"][alarmSeverity="{severity}"]': {
            self.alarm_content_style: color
        }
        for severity, color in PYDM_ALARM_COLORS.items()
    }

generate_properties()

Generate a list of XML property elements for this object, including any stylesheets derived from foreground or background color settings.

Returns

List[ET.Element] A list of XML elements representing properties, including inherited ones from the base class and additional style properties if specified.

Source code in pydmconverter/widgets_helpers.py

def generate_properties(self) -> List[ET.Element]:
    """
    Generate a list of XML property elements for this object, including
    any stylesheets derived from foreground or background color settings.

    Returns
    -------
    List[ET.Element]
        A list of XML elements representing properties, including inherited
        ones from the base class and additional style properties if specified.
    """
    properties: List[ET.Element] = super().generate_properties()

    # if self.background_color is not None or self.foreground_color is not None:
    styles: Dict[str, Any] = {}
    if self.background_color is not None and self.useDisplayBg is None:
        styles["background-color"] = self.background_color
    if self.foreground_color is not None:
        styles["color"] = self.foreground_color
    if self.name.startswith("activeMenuButtonClass") or self.name.startswith("activeMessageButtonClass"):
        styles["border"] = "1px solid black"
    properties.append(StyleSheet(styles, self.alarm_content_rules()).to_xml())

    return properties

Tangible dataclass

Bases: XMLSerializableMixin

Represents a tangible widget that occupies space on a screen.

Attributes

x : int The x-coordinate. y : int The y-coordinate. width : int The width of the widget. height : int The height of the widget.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Tangible(XMLSerializableMixin):
    """
    Represents a tangible widget that occupies space on a screen.

    Attributes
    ----------
    x : int
        The x-coordinate.
    y : int
        The y-coordinate.
    width : int
        The width of the widget.
    height : int
        The height of the widget.
    """

    x: int = 0
    y: int = 0
    width: int = 0
    height: int = 0
    secretId: str = None

    def generate_properties(self) -> List[etree.Element]:
        """
        Generate XML properties for the tangible widget.

        Returns
        -------
        List[etree.Element]
            A list containing the geometry property.
        """
        properties: List[etree.Element] = []
        properties.append(Geometry(self.x, self.y, max(self.width, 2), max(self.height, 2)).to_xml())
        if self.secretId is not None:
            properties.append(Str("secretId", self.secretId).to_xml())
        return properties

generate_properties()

Generate XML properties for the tangible widget.

Returns

List[etree.Element] A list containing the geometry property.

Source code in pydmconverter/widgets_helpers.py

def generate_properties(self) -> List[etree.Element]:
    """
    Generate XML properties for the tangible widget.

    Returns
    -------
    List[etree.Element]
        A list containing the geometry property.
    """
    properties: List[etree.Element] = []
    properties.append(Geometry(self.x, self.y, max(self.width, 2), max(self.height, 2)).to_xml())
    if self.secretId is not None:
        properties.append(Str("secretId", self.secretId).to_xml())
    return properties

Text dataclass

Bases: XMLConvertible

Represents a text property for a widget.

Attributes

name : str The name of the text property. string : str The text content.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class Text(XMLConvertible):
    """
    Represents a text property for a widget.

    Attributes
    ----------
    name : str
        The name of the text property.
    string : str
        The text content.
    """

    name: str
    string: str

    def to_xml(self) -> ET.Element:
        """
        Convert the text property to an XML element.

        Returns
        -------
        ET.Element
            The XML element representing the text.
        """
        prop: ET.Element = ET.Element("property", attrib={"name": self.name})
        string_tag: ET.Element = ET.SubElement(prop, "string")
        string_tag.text = self.string
        return prop

to_xml()

Convert the text property to an XML element.

Returns

ET.Element The XML element representing the text.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> ET.Element:
    """
    Convert the text property to an XML element.

    Returns
    -------
    ET.Element
        The XML element representing the text.
    """
    prop: ET.Element = ET.Element("property", attrib={"name": self.name})
    string_tag: ET.Element = ET.SubElement(prop, "string")
    string_tag.text = self.string
    return prop

TextFormat dataclass

Bases: XMLConvertible

Represents text format properties for a widget.

Attributes

text_format : str The text format value.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class TextFormat(XMLConvertible):
    """
    Represents text format properties for a widget.

    Attributes
    ----------
    text_format : str
        The text format value.
    """

    text_format: str

    def to_xml(self) -> etree.Element:
        """
        Convert the text format property to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the text format.
        """
        prop: etree.Element = etree.Element("property", attrib={"name": "textFormat"})
        set_tag: etree.Element = etree.SubElement(prop, "enum")
        set_tag.text = f"Qt::{self.text_format.capitalize()}"
        return prop

to_xml()

Convert the text format property to an XML element.

Returns

etree.Element The XML element representing the text format.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> etree.Element:
    """
    Convert the text format property to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the text format.
    """
    prop: etree.Element = etree.Element("property", attrib={"name": "textFormat"})
    set_tag: etree.Element = etree.SubElement(prop, "enum")
    set_tag.text = f"Qt::{self.text_format.capitalize()}"
    return prop

TransparentBackground dataclass

Bases: XMLConvertible

Represents a stylesheet that gives an object no background.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class TransparentBackground(XMLConvertible):
    """
    Represents a stylesheet that gives an object no background.
    """

    def to_xml(self):
        """
        Convert the stylesheet to an XML element.

        Returns
        -------
        etree.Element
            The XML element representing the background stylesheet.
        """

        style = "background-color: transparent;"
        prop = ET.Element("property", {"name": "styleSheet"})
        string_elem = ET.SubElement(prop, "string")
        string_elem.text = style
        return prop

to_xml()

Convert the stylesheet to an XML element.

Returns

etree.Element The XML element representing the background stylesheet.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self):
    """
    Convert the stylesheet to an XML element.

    Returns
    -------
    etree.Element
        The XML element representing the background stylesheet.
    """

    style = "background-color: transparent;"
    prop = ET.Element("property", {"name": "styleSheet"})
    string_elem = ET.SubElement(prop, "string")
    string_elem.text = style
    return prop

XMLConvertible

Abstract base class for objects that can be converted to XML.

Methods

to_xml() -> ET.Element Convert the object to an XML element. to_string() -> str Return a formatted string representation of the XML element.

Source code in pydmconverter/widgets_helpers.py

class XMLConvertible:
    """
    Abstract base class for objects that can be converted to XML.

    Methods
    -------
    to_xml() -> ET.Element
        Convert the object to an XML element.
    to_string() -> str
        Return a formatted string representation of the XML element.
    """

    secretId: str = None

    def to_xml(self) -> ET.Element:
        """
        Convert the object to an XML element.

        Returns
        -------
        ET.Element
            The XML element representation of the object.

        Raises
        ------
        NotImplementedError
            If the method is not implemented by the subclass.
        """
        raise NotImplementedError

    def to_string(self) -> str:
        """
        Convert the XML element to a formatted string.

        Returns
        -------
        str
            The formatted string representation of the XML element.
        """
        element: ET.Element = self.to_xml()
        etree.indent(element)
        return etree.tostring(element, encoding="unicode")

to_string()

Convert the XML element to a formatted string.

Returns

str The formatted string representation of the XML element.

Source code in pydmconverter/widgets_helpers.py

def to_string(self) -> str:
    """
    Convert the XML element to a formatted string.

    Returns
    -------
    str
        The formatted string representation of the XML element.
    """
    element: ET.Element = self.to_xml()
    etree.indent(element)
    return etree.tostring(element, encoding="unicode")

to_xml()

Convert the object to an XML element.

Returns

ET.Element The XML element representation of the object.

Raises

NotImplementedError If the method is not implemented by the subclass.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> ET.Element:
    """
    Convert the object to an XML element.

    Returns
    -------
    ET.Element
        The XML element representation of the object.

    Raises
    ------
    NotImplementedError
        If the method is not implemented by the subclass.
    """
    raise NotImplementedError

XMLSerializableMixin dataclass

Bases: XMLConvertible

Mixin class that provides a generic XML serialization method.

This mixin assumes that the class has a 'name' attribute and a 'generate_properties' method.

Attributes

name : Optional[str] The name of the widget. count : ClassVar[int] A class variable used to generate default names.

Source code in pydmconverter/widgets_helpers.py

@dataclass
class XMLSerializableMixin(XMLConvertible):
    """
    Mixin class that provides a generic XML serialization method.

    This mixin assumes that the class has a 'name' attribute and a
    'generate_properties' method.

    Attributes
    ----------
    name : Optional[str]
        The name of the widget.
    count : ClassVar[int]
        A class variable used to generate default names.
    """

    name: Optional[str] = None
    count: ClassVar[int] = 1
    secretId: str = None

    def __post_init__(self) -> None:
        """
        Set a default name if not provided.
        """
        if not self.name:
            self.name = f"{type(self).__name__}{type(self).count}"
        elif self.name[0].isdigit():
            self.name = f"widget_{self.name}"
        type(self).count += 1

    def generate_properties(self) -> List[etree.Element]:
        """
        Generate a list of XML property elements.
        Subclasses should override this method to add thier own custom properties.

        Returns
        -------
        List[etree.Element]
            A list of XML elements representing properties.
        """
        el: etree.Element = etree.Element("property")
        el.set("name", "base")
        el.text = "value"
        return [el]

    def to_xml(self) -> ET.Element:
        """
        Generate an XML element representing the object.

        Returns
        -------
        ET.Element
            The XML element representation of the object.

        Raises
        ------
        ValueError
            If the 'name' attribute is not set.
        """
        if not hasattr(self, "name") or not self.name:
            raise ValueError(f"The 'name' attribute must be set for {type(self).__name__}.")

        widget: ET.Element = ET.Element(
            "widget",
            attrib={
                "class": type(self).__name__,
                "name": self.name,
            },
        )

        properties: List[etree.Element] = self.generate_properties()
        for prop in properties:
            widget.append(prop)

        additional_properties: List[etree.Element] = (
            self.get_additional_properties() if hasattr(self, "get_additional_properties") else []
        )
        for prop in additional_properties:
            if widget.find(prop.tag) is None:
                widget.append(prop)

        return widget

    def get_additional_properties(self) -> List[ET.Element]:
        """
        Provide additional XML properties for the object.
        Hook method for subclasses to provide additional XML properties.
        Subclasses can override this method to add custom properties.

        Returns
        -------
        List[ET.Element]
            A list of additional XML elements representing properties.
        """
        return []

__post_init__()

Set a default name if not provided.

Source code in pydmconverter/widgets_helpers.py

def __post_init__(self) -> None:
    """
    Set a default name if not provided.
    """
    if not self.name:
        self.name = f"{type(self).__name__}{type(self).count}"
    elif self.name[0].isdigit():
        self.name = f"widget_{self.name}"
    type(self).count += 1

generate_properties()

Generate a list of XML property elements. Subclasses should override this method to add thier own custom properties.

Returns

List[etree.Element] A list of XML elements representing properties.

Source code in pydmconverter/widgets_helpers.py

def generate_properties(self) -> List[etree.Element]:
    """
    Generate a list of XML property elements.
    Subclasses should override this method to add thier own custom properties.

    Returns
    -------
    List[etree.Element]
        A list of XML elements representing properties.
    """
    el: etree.Element = etree.Element("property")
    el.set("name", "base")
    el.text = "value"
    return [el]

get_additional_properties()

Provide additional XML properties for the object. Hook method for subclasses to provide additional XML properties. Subclasses can override this method to add custom properties.

Returns

List[ET.Element] A list of additional XML elements representing properties.

Source code in pydmconverter/widgets_helpers.py

def get_additional_properties(self) -> List[ET.Element]:
    """
    Provide additional XML properties for the object.
    Hook method for subclasses to provide additional XML properties.
    Subclasses can override this method to add custom properties.

    Returns
    -------
    List[ET.Element]
        A list of additional XML elements representing properties.
    """
    return []

to_xml()

Generate an XML element representing the object.

Returns

ET.Element The XML element representation of the object.

Raises

ValueError If the 'name' attribute is not set.

Source code in pydmconverter/widgets_helpers.py

def to_xml(self) -> ET.Element:
    """
    Generate an XML element representing the object.

    Returns
    -------
    ET.Element
        The XML element representation of the object.

    Raises
    ------
    ValueError
        If the 'name' attribute is not set.
    """
    if not hasattr(self, "name") or not self.name:
        raise ValueError(f"The 'name' attribute must be set for {type(self).__name__}.")

    widget: ET.Element = ET.Element(
        "widget",
        attrib={
            "class": type(self).__name__,
            "name": self.name,
        },
    )

    properties: List[etree.Element] = self.generate_properties()
    for prop in properties:
        widget.append(prop)

    additional_properties: List[etree.Element] = (
        self.get_additional_properties() if hasattr(self, "get_additional_properties") else []
    )
    for prop in additional_properties:
        if widget.find(prop.tag) is None:
            widget.append(prop)

    return widget

escape_qt_mnemonic(text)

Escape & as && for Qt widgets that treat & as a mnemonic marker.

QPushButton, tab titles, QMenu actions, QGroupBox, QCheckBox and QRadioButton swallow a single & and underline the next character; a literal ampersand must be written &&. QLabel renders & literally, so this must NOT be applied to label text. Idempotent: already-escaped && is left alone, so "A && B" stays "A && B" and never becomes "A &&&& B". Non-string inputs pass through unchanged.

Source code in pydmconverter/widgets_helpers.py

def escape_qt_mnemonic(text):
    """Escape ``&`` as ``&&`` for Qt widgets that treat ``&`` as a mnemonic marker.

    QPushButton, tab titles, QMenu actions, QGroupBox, QCheckBox and QRadioButton
    swallow a single ``&`` and underline the next character; a literal ampersand
    must be written ``&&``. QLabel renders ``&`` literally, so this must NOT be
    applied to label text. Idempotent: already-escaped ``&&`` is left alone, so
    ``"A && B"`` stays ``"A && B"`` and never becomes ``"A &&&& B"``.
    Non-string inputs pass through unchanged.
    """
    if not isinstance(text, str) or "&" not in text:
        return text
    # Collapse any existing "&&" to a single "&", then double every "&".
    return text.replace("&&", "&").replace("&", "&&")

unescape_qt_mnemonic(text)

Inverse of :func:escape_qt_mnemonic: && -> &.

Used when reading Qt .ui text destined for a renderer that shows & literally (the react/IR target). A stray single & (a real Qt mnemonic marker) is dropped, matching what Qt would display.

Source code in pydmconverter/widgets_helpers.py

def unescape_qt_mnemonic(text):
    """Inverse of :func:`escape_qt_mnemonic`: ``&&`` -> ``&``.

    Used when reading Qt ``.ui`` text destined for a renderer that shows ``&``
    literally (the react/IR target). A stray single ``&`` (a real Qt mnemonic
    marker) is dropped, matching what Qt would display.
    """
    if not isinstance(text, str) or "&" not in text:
        return text
    return re.sub(r"&(&?)", r"\1", text)