Fixed Value View

Fixed value view components for the UI Generator framework.

This module provides the FixedValueView class, which enables displaying structured data in a fixed grid layout with customizable cells. Fixed value views are ideal for presenting parameters, calculations, and constant values in an organized tabular format with rich styling and conditional formatting capabilities.

Fixed value views create grid-based layouts where each cell can display either static text or dynamic values from parameters and calculations. The grid structure is defined with a fixed number of rows and columns, with cells positioned precisely using row/column indexing.

Classes:

Cell: Represents a single cell with content, styling, and formatting rules
FixedValueView: Container view managing the fixed grid layout and cells

Example:

>>> # Define parameters
>>> max_users = Parameter("max_users", DataType.INTEGER, default_value=100)
>>> min_age = Parameter("min_age", DataType.INTEGER, default_value=18)
>>> system_name = Parameter("system_name", DataType.STRING, default_value="MyApp")
>>>
>>> # Create fixed value view
>>> builder = UiBuilder()
>>> config_view = builder.add_fixed_value_view(
...     display_name="System Configuration",
...     show_band_color=True,
...     band_odd_row_background_color="#F0F0F0",
...     band_even_row_background_color="#FFFFFF"
... )
>>>
>>> # Add column headers
>>> name_header = Cell("Setting Name", header_column=True)
>>> value_header = Cell("Value", header_column=True)
>>> config_view.add_column(name_header)
>>> config_view.add_column(value_header)
>>>
>>> # Add data rows
>>> # Row 0: System name
>>> config_view.add_cell(Cell("System Name"), row=0, col=0)
>>> config_view.add_cell(Cell(system_name), row=0, col=1)
>>>
>>> # Row 1: Max users
>>> config_view.add_cell(Cell("Maximum Users"), row=1, col=0)
>>> config_view.add_cell(Cell(max_users), row=1, col=1)
>>>
>>> # Row 2: Min age with conditional formatting
>>> config_view.add_cell(Cell("Minimum Age"), row=2, col=0)
>>> age_cell = Cell(min_age)
>>> # Highlight if age is below 21
>>> age_warning = Parameter("age_warning", DataType.BOOLEAN)
>>> warning_style = ColumnStyle(background_color="#FFEEEE")
>>> age_cell.add_conditional_formatting_rule(
...     named_value=age_warning,
...     override_styles=warning_style,
...     stop_if_true=True
... )
>>> config_view.add_cell(age_cell, row=2, col=1)

class FixedValueView(display_name=None, hidden=False, show_dropdowns_below=True, show_band_color=True)[source]

Bases: BaseView

A view representing a layout with a fixed number of rows and columns.

total_rows: Total number of rows. Rows start at index 0 (e.g., if the last added row index is 3, total_rows = 4).

columns: List of column header Cell objects.

cells: Nested mapping: {row_index -> {col_index -> Cell}}.

show_dropdowns_below: Indicates whether table dropdowns should always be shown below the editing cell.

show_band_color: Whether banded row colouring is enabled.

band_odd_row_background_color: Background colour for odd-numbered rows (if show_band_color is True). Default to #F7F7F7

band_even_row_background_color: Background colour for even-numbered rows (if show_band_color is True). Default to #FFFFFF

set_band_colors(odd_row_background_color='#F7F7F7', even_row_background_color='#FFFFFF')[source]

Sets the background colours for alternating row banding.

Parameters:

odd_row_background_color (str) – Background colour for odd-numbered rows.
even_row_background_color (str) – Background colour for even-numbered rows.

Return type:

FixedValueView

add_column(column)[source]

Adds a column header cell to the view.

Parameters:: column (Cell) – A Cell instance representing the column header to append.
Raises:: ValueError – If the provided cell is not marked as a header column.
Return type:: None

add_cell(cell, row, col)[source]

Inserts a cell into the layout at the specified row and column.

This method ensures the internal cell structure remains consistent:

Automatically initializes the row dictionary if it does not exist.
Ensures the column index is valid relative to the defined header columns.
Automatically updates total_rows when adding cells beyond the current range.

Parameters:

cell (Cell) – The Cell instance to place into the layout.
row (int) – The zero-based row index where the cell should be inserted.
col (int) – The zero-based column index where the cell should be inserted.

Raises:

IndexError – If the provided column index is outside the range of the defined columns.
ValueError – If row or column indices are negative.

Return type:

None

class Cell(value, cell_style=None, header_column=False, default_value=None, read_only=False)[source]

Bases: Buildable

Represents a single cell within a table or grid layout.

cell_style

Style configuration controlling the base visual appearance of the cell.

Type:: Optional[CellStyle]

header_column

Whether this cell belongs to a header column. Header cells may be treated differently by the UI renderer.

Type:: bool

read_only

Indicates whether the cell is editable by the end user.

Type:: bool

conditional_formatting_rules

A list of rules that dynamically override the cell’s appearance depending on data conditions.

Type:: List[ConditionalFormattingRule]

default_definition_id

The named value ID of the default value (if provided).

Type:: Optional[str]

display_string

A literal string to display when the cell contains textual content. For dynamic cells (Parameter/Calculation), this is typically empty.

Type:: Optional[str]

definition_id

The named value ID associated with the Parameter or Calculation driving the cell’s value. None when the cell contains a literal string.

Type:: Optional[str]

__init__(value, cell_style=None, header_column=False, default_value=None, read_only=False)[source]

Initializes a Cell instance, which can display either a literal string or a dynamic value referenced by a Parameter or Calculation.

Parameters:

value (Parameter | Calculation | str) – The content of the cell. A string is displayed directly. A Parameter or Calculation is stored as a reference via its named_value_id.
cell_style (CellStyle | None) – Base visual styling for the cell.
header_column (bool) – Indicates whether this cell belongs to a header column. Default to False.
default_value (Parameter | Calculation | None) – Optional default value used when no explicit value is provided. Stored by reference via default_definition_id. Defaults to None.
read_only (bool) – Whether the cell can be edited by the end user. Defaults to False.

Raises:

TypeError – If value is not a string, Parameter, or Calculation.

add_conditional_formatting_rule(named_value, override_styles, element_states=None, stop_if_true=False, formatting_type=ConditionalFormattingType.BOOLEAN)[source]

Adds a conditional formatting rule to the cell.

The rule describes how the cell’s appearance should change when the condition defined by condition_column evaluates to true.

Parameters:

named_value (Parameter | Calculation) – The data column whose value will be evaluated to determine whether the formatting rule should be applied. Either a Parameter or a Calculation.
override_styles (ColumnStyle) – The ColumnStyle instance specifying visual overrides when the rule triggers.
element_states (ElementStates | None) – The element state to apply if the condition is met.
stop_if_true (bool) – If True, further conditional formatting rules will not be evaluated after this rule matches. Defaults to False.
formatting_type (ConditionalFormattingType) – Indicates how the condition should be interpreted (e.g., Boolean, Numeric). Defaults to ConditionalFormattingType.BOOLEAN.

Return type:

None