Base Elements

Base Elements are the building blocks for an Edifice application.

Each Base Element manages an underlying QWidget.

All Base Elements in this module inherit from QtWidgetElement and its props. This means that all Base Elements can be made to respond to clicks by passing a handler function to the on_click prop. All Base Elements are stylable using the style prop, see Styling.

QtWidgetElement([style, tool_tip, cursor, ...])

Base Qt Widget Element.

Base Elements can roughly be divided into Root Elements, Layout Elements, and Content Elements.

Root Base Elements

The root parent Element of every Edifice application is a Window.

Or an ExportList for exporting components to a normal PySide6/PyQt6 app.

Window([title, icon, menu, _on_open, ...])	The root View element of an App which runs in an operating system window.
ExportList()	The root element for an App which does App.export_widgets().

Layout Base Elements

Each Layout Base Element manages an underlying QLayout, and can have children (like the <div> HTML tag).

To render a Layout Base Element, always use the with statement and indent the element’s children:

with VBoxView():
    with HBoxView():
        Label("Hello")
        Label("World")

All of the Layout Base Elements have the name suffix View.

VBoxView(**kwargs)	Vertical column layout view for child elements.
HBoxView(**kwargs)	Horizontal row layout view for child elements.
FixView(**kwargs)	View layout for child widgets with fixed position.
VScrollView(**kwargs)	Scrollable vertical column layout.
HScrollView(**kwargs)	Scrollable horizontal row layout widget.
FixScrollView(**kwargs)	Scrollable layout widget for child widgets with fixed position.
TabView([labels])	Layout widget with multiple tabs.
GridView([layout, key_to_code])	Grid layout widget for rendering children on a 2D rectangular grid.
TableGridView([row_stretch, column_stretch, ...])	Table-style grid layout displays its children as aligned rows of columns.
TableGridRow()	Row Element of a TableGridView.
FlowView(**kwargs)	Flow-style layout.
WindowPopView([title, icon, on_close, ...])	Pop-up Window layout.

Content Base Elements

Content Base Elements render a single Qt Widget and mostly do not have children.

Button([title])	Basic button widget.
ButtonView([on_trigger])	Button with child layout.
CheckBox([checked, text, on_change])	Checkbox widget.
Dropdown([selection, options, on_select, ...])	Dropdown selection widget.
Image(src[, aspect_ratio_mode])	Render an image.
ImageSvg(src, **kwargs)	Render an SVG image.
Icon(name[, size, collection, ...])	Display an Icon.
IconButton(name[, size, collection, ...])	Display an Icon Button.
Label([text, selectable, word_wrap, ...])	Text display widget.
ProgressBar(value[, min_value, max_value, ...])	Progress bar widget.
RadioButton([checked, text, on_change])	Radio buttons.
ScrollBar([value, minimum, maximum, ...])	Scroll bar widget.
Slider(value[, min_value, max_value, ...])	Slider bar widget.
SpinInput([value, min_value, max_value, ...])	Widget for a int input value with up/down buttons.
TextInput([text, placeholder_text, ...])	One line text input widget.
TextInputMultiline([text, placeholder_text, ...])	Multiline text input widget.

Events

Each user interaction with a Base Element generates events, and you can specify how to handle the event by providing a handler function.

These handlers are passed into the Base Element as props, for example the on_click prop of QtWidgetElement, or the on_change prop for checkboxes, radio buttons, sliders, and text input. When the event occurs the handler function will be called with an argument describing the event.

Usually, what you want to do in an event handler is to update some state with a use_state() setter function.

Async Event Handlers

These event handlers run in the main event loop. A lengthy operation will block the application from interacting with the user, which is generally a bad user experience.

Consider this code.

Blocking Event Handler

@component
def MyComponent(self):

    results, set_results = use_state("")

    def on_click(event:QMouseEvent):
        r = fetch_from_network()
        set_results(r)

    with VBoxView():
        Button("Fetch", on_click=on_click)
        if results:
            Label(results)

When the Fetch button is clicked, the event handler will call a fetch_from_network function, blocking the application for an unbounded length of time. If the user clicks the increment button while waiting for the fetch then nothing will happen.

Use the use_async_call Hook for an asynchronous event handler which will cancel automatically when MyComponent is unmounted, or when the Fetch button is pressed again.

Async Event Handler

@component
def MyComponent(self):

    results, set_results = use_state("")
    loading, set_loading = use_state(False)

    async def on_click(event:QMouseEvent):
        set_loading(True)
        r = await fetch_from_network()
        set_results(r)
        set_loading(False)

    on_click_handler, cancel_click_handler = use_async_call(on_click)

    with VBoxView():
        Button("Fetch", on_click=on_click_handler)
        if loading:
            Label("Fetching...")
        elif results:
            Label(results)

Custom Base Elements

Not all QtWidgets are supported by Edifice. Edifice provides CustomWidget to allow you to bind arbitrary QtWidgets to an Edifice Element.

CustomWidget(*args, **kwargs)

Custom widgets that you can define.