Element Class API Reference

Note

βš™οΈ New to this topic? Start with Visual Styling and Junction Types to understand element styling and junction semantics before diving into the API details.

The Element class represents ArchiMate elements with support for element hierarchy (parent-child relationships), visual styling, and junction type semantics.

Visual Styling Methods

Color Properties

set_fill_color(color: str | None) → None

Set the fill/background color of this element.

Parameters:

color (Optional[str]) – Hex color (#RRGGBB), named color (e.g., β€˜red’, β€˜blue’), or None to use default

Raises:

ValueError – If color format is invalid

Supported Named Colors: red, green, blue, yellow, orange, purple, pink, brown, gray, white, black

Example:

elem = model.add(ArchiType.BusinessProcess, 'Process')
elem.set_fill_color('#ff0000')  # Hex color
elem.set_fill_color('red')      # Named color
elem.set_fill_color(None)       # Reset to default
get_fill_color() → str | None

Get the fill color of this element.

Returns:

Hex color (#rrggbb) or None if not set

Return type:

Optional[str]

set_line_color(color: str | None) → None

Set the border/line color of this element.

Parameters:

color (Optional[str]) – Hex color (#RRGGBB), named color, or None to use default

Raises:

ValueError – If color format is invalid

Example:

elem.set_line_color('#0066cc')
elem.set_line_color('blue')
get_line_color() → str | None

Get the line color of this element.

Returns:

Hex color (#rrggbb) or None if not set

Return type:

Optional[str]

Line Width Property

set_line_width(width: float | None) → None

Set the border/line width of this element in pixels.

Parameters:

width (Optional[float]) – Width in pixels (β‰₯ 0), or None to use default

Raises:

  • ValueError – If width is negative

  • TypeError – If width is not numeric

Example:

elem.set_line_width(2.0)  # 2 pixel border
elem.set_line_width(0.5)  # 0.5 pixel border
elem.set_line_width(None) # Reset to default
get_line_width() → float | None

Get the line width of this element.

Returns:

Width in pixels or None if not set

Return type:

Optional[float]

Transparency Property

set_transparency(alpha: float | None) → None

Set the opacity/transparency of this element.

Parameters:

alpha (Optional[float]) – Opacity 0.0 (fully transparent) to 1.0 (fully opaque), or None to use default

Raises:

  • ValueError – If alpha is out of range

  • TypeError – If alpha is not numeric

Example:

elem.set_transparency(1.0)   # Fully opaque
elem.set_transparency(0.5)   # 50% transparent
elem.set_transparency(0.0)   # Fully transparent
elem.set_transparency(None)  # Reset to default
get_transparency() → float | None

Get the transparency/opacity of this element.

Returns:

Opacity 0.0-1.0 or None if not set

Return type:

Optional[float]

Bulk Style Operations

set_visual_style(fill_color: str | None = None, line_color: str | None = None, line_width: float | None = None, transparency: float | None = None) → None

Set multiple visual style properties at once.

Parameters:

  • fill_color – Fill color (hex or named)

  • line_color – Line color (hex or named)

  • line_width – Line width in pixels (β‰₯ 0)

  • transparency – Opacity 0.0-1.0

Raises:

ValueError – If any property is invalid

Example:

elem.set_visual_style(
    fill_color='#ffeb3b',
    line_color='#ff6f00',
    line_width=2.0,
    transparency=0.9
)
get_visual_style() → dict[str, Any]

Get all visual style properties as a dictionary.

Returns:

Dictionary with fillColor, lineColor, lineWidth, transparency (only set values)

Return type:

dict[str, Any]

Example:

style = elem.get_visual_style()
# Returns: {'fillColor': '#ffeb3b', 'lineColor': '#ff6f00', 'lineWidth': 2.0, 'transparency': 0.9}
reset_visual_style() → None

Reset all custom visual styles to defaults.

Example:

elem.reset_visual_style()  # Clear all custom styles

Junction Type Methods

set_junction_type(junction_type: str | None) → None

Set the junction type for a Junction element.

Parameters:

junction_type (Optional[str]) – Junction type (β€˜and’, β€˜or’, β€˜xor’) or None

Raises:

ValueError – If junction_type is not valid

Valid Junction Types: - β€˜and’: All inputs must be satisfied - β€˜or’: At least one input must be satisfied - β€˜xor’: Exactly one input must be satisfied

Example:

junction = model.add(ArchiType.Junction, 'Decision Point')
junction.set_junction_type('and')
junction.set_junction_type('xor')
junction.set_junction_type(None)  # Clear junction type
get_junction_type() → str | None

Get the junction type for a Junction element.

Returns:

Junction type (β€˜and’, β€˜or’, β€˜xor’) or None if not set

Return type:

Optional[str]

Example:

jtype = junction.get_junction_type()
if jtype == 'and':
    print("AND junction - all inputs required")

Hierarchy Methods

Parent-Child Relationships

The Element class stores its parent UUID reference. Use Model methods for full hierarchy management:

  • element._parent_uuid: Internal reference to parent element UUID (read-only)

Use Model.add_child() to create relationships and Model.get_parent() to query.

See Element Hierarchies for hierarchy usage guide.

Round-Trip Preservation

All visual properties and junction types are automatically preserved during XML export/import cycles.

Note

The examples below are validated by review (not make doctest) because they interact with the file system in ways that vary by environment. The getting-started.rst and api/model.rst round-trip examples are validated by Sphinx doctest (make doctest).

# Create and style element
elem = model.add(ArchiType.BusinessProcess, 'Process')
elem.set_fill_color('#ff0000')
elem.set_transparency(0.8)

# Export to XML
model.write('model.archimate')

# Import from XML
m2 = Model('reloaded')
m2.read('model.archimate')

# Properties are preserved exactly
elem2 = m2.elems_dict[elem.uuid]
assert elem2.get_fill_color() == '#ff0000'
assert elem2.get_transparency() == 0.8

See Also