edifice.component

edifice.component(f)

Decorator which turns a render function of props into an Element.

The first argument of the render function must be self, for internal technical reasons.

Return type:

Callable[[ParamSpec(P)], Element]

Props

The props are the arguments passed to the @component function.

The @component will be re-rendered when some of its props are not __eq__ to the props from the last time the @component rendered. If the props are all __eq__, the @component will not re-render.

Arguments with a leading underscore _ will not count as props. They are normal function arguments, and changing their value will not cause the @component to re-render.

Render

The @component function must render exactly one Element. In the @component function, declare a tree of Element with a single root.

a tree with a single root

@component
def MySimpleComp(self, prop1, prop2, prop3):
    with VBoxView():
        Label(text=prop1)
        Label(text=prop2)
        Label(text=prop3)

State

The @component function is a stateless function from props to an Element. To introduce state into a @component, use Hooks.

Composition

An @component’s children can be passed to it as props. This allows a @component to act as a parent container for other Element s, and to render them in a specific layout.

There are two features to accomplish this.

1. The special children prop is a tuple of Element s. The special children prop must be declared as a keyword argument with a default empty tuple, like this children:tuple[Element, ...]=().

   Do not explicitly pass the children prop when calling the @component. The children will be passed implicitly.

2. The child_place() function is used to place the children in the parent @component’s render function.

With these two features, you can declare how the parent container @component will render its children.

Example ContainerComponent with children props

@component
def ContainerComponent(self:Element, children:tuple[Element, ...]=()):
    with VBoxView():
        for child in children:
            with VBoxView():
                child_place(child)

Example ContainerComponent usage

with ContainerComponent():
    Label(text="First Child")
    Label(text="Second Child")
    Label(text="Third Child")

type f:

Callable[[Concatenate[TypeVar(selfT, bound= Element), ParamSpec(P)]], None]

param f:

The render function to wrap. Its first argument must be self. Subsequent arguments are props.