edifice.App

class edifice.App(root_element, inspector=False, create_application=True, qapplication=None)

Bases: object

The main application object.

The App provides the rendering engine that’s responsible for issuing the commands necessary to render each Element as Qt Widgets.

Start

To start the application, construct an App with a root Element and call the App.start() method:

App(MyRootElement()).start()

If the application is a normal application in an operating system window, then the root Element rendered by MyRootElement must be a Window.

The App.start() method will:

1. Create the application event loop qasync.QEventLoop.

2. Start the application event loop.

3. Render the root Element.

Instead of calling application initialization code from the __main__ function, call the initialization code from a use_state() initializer function in the root Element because this function will run when the app is started by the Edifice Runner.

Example:

from PySide6.QtWidgets import QApplication
from PySide6.QtGui import QFont
from edifice import App, Window, Label, component, use_state

@component
def Main(self):

    def initalizer():
        qapp = cast(QApplication, QApplication.instance())
        QApplication.setStyle("fusion")
        qapp.setApplicationName("My App")
        qapp.setFont(QFont("Yu Gothic UI", 10))
        qapp.setStyleSheet("QLabel { font-size: 12pt; }")
        if theme_is_light():
            qapp.setPalette(palette_edifice_light())
        else:
            qapp.setPalette(palette_edifice_dark())

    _, _ = use_state(initalizer)

    with Window():
        Label("Hello, World!")


if __name__ == "__main__":
    App(Main()).start()

For more information about global styles, see Styling.

Stop

When the user closes the Window or when App.stop() is called, the application will stop.

Stopping the application will:

1. Unmount all Elements.

2. Cancel all edifice.use_async() tasks.

3. Wait for the edifice.use_async() tasks to cancel.

4. Stop the application event loop.

5. Close the application event loop.

6. Exit.

Export Widgets

If you just want to create widgets that you’ll integrate with an existing Qt application, use the App.export_widgets() method instead of App.start(). These widgets can then be plugged into the rest of your Qt application, and there’s no need to manage the rendering of the widgets — state changes will trigger automatic re-render without any intervention.

Caveat: Your Qt application must use a qasync.QEventLoop.

Logging

To enable Edifice logging set the logging level. Example:

import logging
logger = logging.getLogger("Edifice")
logger.setLevel(logging.INFO)

App Construction

By default, App() creates a new QtWidgets.QApplication instance.

type root_element:

Element

param root_element:

The root Element of the application. It must render to an instance of Window or ExportList.

type inspector:

bool

param inspector:

Whether or not to run an instance of the Edifice Inspector alongside the main app. Defaults to False.

type create_application:

bool

param create_application:

(Default True) Whether or not to create an instance of QApplication. Usually you want to use the default setting. However, if the QApplication is already created (e.g. in a test suite or if you just want Edifice to make a widget to plug into an existing Qt application), you can set this to False.

type qapplication:

Optional[QApplication]

param qapplication:

(Default None) The QtWidgets.QApplication. If you do not provide one, it will be created for you.

Methods

__init__(root_element[, inspector, ...])
export_widgets()	Exports the underlying Qt QWidgets s from the Edifice Elements in the ExportList.
start()	Start the application event loop.
start_loop()	Start the application event loop.
stop()	Stop the application.

export_widgets()

Exports the underlying Qt QWidgets s from the Edifice Elements in the ExportList.

Returns a list of QtWidgets.QWidget.

These QWidget s are still managed by Edifice, they will still benefit from full reactivity and state consistency. You can mount these widgets to your pre-existing Qt application this way:

# Suppose parent_widget is defined in Qt code.

@component
def export_elements(self):
    with ExportList():
        MyAwesomeComponent()
        AnotherComponent()

edifice_app = edifice.App(export_elements(), create_application=False)
edifice_widgets = edifice_app.export_widgets()

edifice_widgets[0].setParent(parent_widget)
parent_widget.layout().add_widget(edifice_widgets[0])

edifice_widgets[1].setParent(parent_widget)
parent_widget.layout().add_widget(edifice_widgets[1])

Return type:

list[QWidget]

start()

Start the application event loop.

Return type:

None

start_loop()

Start the application event loop.

A context manager alternative to App.start() which allows access to the application’s qasync.QEventLoop after the application starts, and before the first render.

The QEventLoop is the asyncio current event loop. You can also access the asyncio current event loop in the usual way with asyncio.get_running_loop().

In this example, we add a Unix SIGINT handler which will App.stop() the application:

app = edifice.App(MyAppElement())
with app.start_loop() as loop:
    loop.add_signal_handler(signal.SIGINT, app.stop)

Return type:

Generator[QSelectorEventLoop, None, None]

stop()

Stop the application.

See use_stop() for a way to stop the App from within a @component.

Return type:

None