multiple MainWindows - Documents design

[areslagae]

Hi all,

I recently experimented with multiple MainWindows and Documents. I wanted to leave some feedback on how I experienced that and also ask some questions.

My use case does not map completely to the Documents case. One reason is that my files are actually (uncompressed) "bundles" (hence I open folders and not files) and also because my open/save/save as/read/write functionality does not entirely map to Toga's).

I was also not able to adapt the Document/DocumentWindow/ DocumentSet functionality to my case because it is very tightly coupled with App. For example, App creates a DocumentSet internally that insists on types/Documents having an extension attribute. So it seems difficult to adapt for the end user. Thinking about this, there are a lot of multiple document interfaces that do not work with files (e.g. browser windows, many other examples). I think that the Document functionality could be made much more broadly applicable by providing more abstract interfaces for Document/DocumentWindow/ DocumentSet and then for example a concrete implementation for files (which would also serve as an example for implementing other kinds of content). In fact, I was a bit surprised by the rigidity given that tables, trees, ... are abstracted in such a flexible way.

I also have some further questions since I must implement my own similar mechanism:

1/ Is an approach like below suitable for keeping the application open in a multiple document interface? It seems to work well, but I am not sure if it is the toga way. In essence, if a main window is about to close, and it is the main window of the app, I swap it out for another one, preventing a close. This seems to work wel for a multiple document interface.

class MyDocumentMainWindow(toga.MainWindow):

    def close(self):

        if self is self.app.main_window:
            new_main_window = next((w for w in self.app.windows if isinstance(w, toga.MainWindow) and w is not self), None)
            if new_main_window:
                self.app.main_window = new_main_window

        super().close()

2/ Is an approach like below suitable for swapping documents in a single document interface (single MainWindow)? In essence I group all of the content of the main window in a specific composite widget, and I swap out the entire widget, leaving the main window intact. Again, it seems to work well, but I am not sure it is the toga way and I can just swap out toga.MainWindow.content like that. Alternatives are closing the current window and opening a new one (which works when you are careful about the order of operations when setting main_window) or setting the document of MyDocumentWidget. But I found the one below particularly attractive and simple.

class MyDocumentMainWindow(toga.MainWindow):

    @document.setter
    def document(self, document):
        self._document.close()
        self._document = document
        self._document_widget = MyDocumentWidget(self._document) # make a new widget for the new doc
        self.content = self._document_widget # and swap it out

Additionally, I want to point out some potential issues with the documentation and example code.

1/ The page https://toga.beeware.org/en/stable/reference/api/app/ says the text below. This only seems the case when using documents, but the text is not in the section about managing documents. I was misled by that (but that might be my fault). I though that, on macOS, it would create an app with a menu bar an no windows. But this is only the case (sort of) when using document types.

If your app doesn't have a single "main" window, but instead has multiple windows that are equally important (e.g., a document editor, or a web browser), you can assign a value of None to [main_window](https://toga.beeware.org/en/stable/reference/api/app/#toga.App.main_window). The resulting behavior is slightly different on each platform, reflecting platform differences.

2/ I suspect the document app example on windows might be broken.

• only the app.main_window has a menu bar, the secondary windows do not. Is that the intention? I thought not, but I might be wrong. Because after closing the primary window you are stuck without a menu in the other windows.
• it throws an exception (see below), maybe related to above, have not investigated further.

In any case, I hope this is useful feedback.

Best regards,

Traceback (most recent call last):
  File "...\.venv\Lib\site-packages\toga\window.py", line 652, in on_gain_focus
    return self._on_gain_focus
           ^^^^^^^^^^^^^^^^^^^
  File "...\.venv\Lib\site-packages\toga_winforms\window.py", line 137, in winforms_Activated
    self.interface.on_gain_focus()
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File ...\.venv\Lib\site-packages\toga\handlers.py", line 288, in __call__
    return function(*args, **kwargs)
   bij Python.Runtime.PythonException.ThrowLastAsClrException()
   bij Python.Runtime.Dispatcher.TrueDispatch(Object[] args)
   bij Python.Runtime.Dispatcher.Dispatch(Object[] args)
   bij __System_EventHandlerDispatcher.Invoke(Object , EventArgs )
   bij System.Windows.Forms.Form.OnActivated(EventArgs e)
   bij System.Windows.Forms.Form.set_Active(Boolean value)
   bij System.Windows.Forms.Form.WmActivate(Message& m)
   bij System.Windows.Forms.NativeWindow.Callback(IntPtr hWnd, Int32 msg, IntPtr wparam, IntPtr lparam)
'DocumentWindow' object has no attribute '_on_gain_focus'
Traceback (most recent call last):
  File "...\.venv\Lib\site-packages\toga\window.py", line 652, in on_gain_focus
    return self._on_gain_focus
           ^^^^^^^^^^^^^^^^^^^
  File "...\.venv\Lib\site-packages\toga_winforms\window.py", line 137, in winforms_Activated
    self.interface.on_gain_focus()
    ^^^^^^^^^^^^^^^^^^^^^^^^^^^^
  File "...\.venv\Lib\site-packages\toga\handlers.py", line 288, in __call__
    return function(*args, **kwargs)
   bij Python.Runtime.PythonException.ThrowLastAsClrException()
   bij Python.Runtime.Dispatcher.TrueDispatch(Object[] args)
   bij Python.Runtime.Dispatcher.Dispatch(Object[] args)
   bij __System_EventHandlerDispatcher.Invoke(Object , EventArgs )
   bij System.Windows.Forms.Form.OnActivated(EventArgs e)
   bij System.Windows.Forms.Form.set_Active(Boolean value)
   bij System.Windows.Forms.Form.WmActivate(Message& m)
   bij System.Windows.Forms.NativeWindow.Callback(IntPtr hWnd, Int32 msg, IntPtr wparam, IntPtr lparam)
'DocumentWindow' object has no attribute '_on_gain_focus'

[freakboy3742]

I recently experimented with multiple MainWindows and Documents. I wanted to leave some feedback on how I experienced that and also ask some questions.

Thanks - feedback is always welcome. I'll preface my response by saying that Toga's Document interface is an area that hasn't had as much development as some other APIs. It was built primarily to service the needs of Podium, BeeWare's slide presentation tool. I can't rule out that there are significant improvements possible or needed for Toga's Document API.

My use case does not map completely to the Documents case. One reason is that my files are actually (uncompressed) "bundles" (hence I open folders and not files) and also because my open/save/save as/read/write functionality does not entirely map to Toga's).

I was also not able to adapt the Document/DocumentWindow/ DocumentSet functionality to my case because it is very tightly coupled with App. For example, App creates a DocumentSet internally that insists on types/Documents having an extension attribute. So it seems difficult to adapt for the end user.

To some extent, we're hampered by operating systems here - operating systems think about documents as single files, and there's a lot of internal OS tooling that assumes a document has a document type.

That said - some apps will allow you to open a folder as a "project" (or similar) - IDEs, for example, will often let you open a folder. However, even then, there is often a single "file" that can be identified as "the project".

Thinking about this, there are a lot of multiple document interfaces that do not work with files (e.g. browser windows, many other examples).

So - a document-based app is just one way to structure an app. A Toga app can have multiple Main Windows; and the lifecycle of the app can be tied to "closing the last window". A Document-based app (i.e., adding document type registrations) is just one way to trigger that behavior.

From Toga's perspective, a browser isn't a document-based app. It's an app with multiple main windows.

I think that the Document functionality could be made much more broadly applicable by providing more abstract interfaces for Document/DocumentWindow/ DocumentSet and then for example a concrete implementation for files (which would also serve as an example for implementing other kinds of content). In fact, I was a bit surprised by the rigidity given that tables, trees, ... are abstracted in such a flexible way.

We're definitely option to suggestions here. As I said previously - the Document interface is an area that hasn't seen as much exercise as other parts of Toga; so if you've got concrete ideas on improvements, we're open hearing suggestions.

If your specific case is the ability to open a "folder" as a document type... the fix might be as simple as providing a way to register a document as being "folder based", rather than extension based.

The complication with this is that "file open" and "select folder" dialogs are very different. It may turn out that the solution for your use case isn't to think of this as a "document based" app, but an app with it's own abstraction layer around "windows as wrappers around folders of content".

I also have some further questions since I must implement my own similar mechanism:

1/ Is an approach like below suitable for keeping the application open in a multiple document interface? It seems to work well, but I am not sure if it is the toga way. In essence, if a main window is about to close, and it is the main window of the app, I swap it out for another one, preventing a close. This seems to work wel for a multiple document interface.

This comes back to the "multi-window" use case. An app doesn't have to have a main window. If you explicitly assign None as the value of main_window, then Toga's behavior is to close the app when the last window is closed (unless you're on macOS, where the app is persistent with no open windows).

So - what you're describing here is fine - and is essentially what Toga is already doing with Document-based apps. When you request a DocumentWindow opens a new document, DocumentSet has a mechanism for replacing the current window with the new content. The mechanism is slightly different to what you've described here, but fundamentally it's doing the same trick - ensuring that there's a new open window before closing the old one. The only difference is that Toga isn't relying on main_window for the application lifecycle.

2/ Is an approach like below suitable for swapping documents in a single document interface (single MainWindow)? In essence I group all of the content of the main window in a specific composite widget, and I swap out the entire widget, leaving the main window intact. Again, it seems to work well, but I am not sure it is the toga way and I can just swap out toga.MainWindow.content like that.

If I'm following what you're trying to describe here, then yes - it's fine. You can replace the content of a window whenever you want. Whether that's because a "new document" has been loaded, or because you just don't like the way the window looks any more - window content can be replaced.

1/ The page https://toga.beeware.org/en/stable/reference/api/app/ says the text below. This only seems the case when using documents, but the text is not in the section about managing documents. I was misled by that (but that might be my fault). I though that, on macOS, it would create an app with a menu bar an no windows. But this is only the case (sort of) when using document types.

As I've indicated above, there's overlap between "document based apps" and Toga's window handling - but the two concepts are very separate. Toga's concept of window handling is independent of using Documents.

2/ I suspect the document app example on windows might be broken.

• only the app.main_window has a menu bar, the secondary windows do not. Is that the intention? I thought not, but I might be wrong. Because after closing the primary window you are stuck without a menu in the other windows.

I have been able to reproduce this - it looks like it's a rendering problem. The DocumentWindow in is a Main Window, so it does have a menu... the bug appears to be that something in the rendering process is hiding that menu. I've found that if you resize the window, the menu re-appears.

• it throws an exception (see below), maybe related to above, have not investigated further.

I haven't seen that exception. Can you elaborate on what you did to trigger it?

[areslagae]

Many thanks for your reply.

After reading your post it seems I misunderstood some of the Toga concepts. For some reason I assumed that Toga's handling of multiple windows was tied to document based apps and I had to adjust Document/DocumentWindow/ DocumentSet to my use case. I now realize that is not the case at all, and I should just implement my own similar functionality e.g. based on the snippets I shared. Thanks for clarifying that.

I also misinterpreted the paragraph about assigning None to main_window. I wrote

self.main_window = None

assuming it would open an application with a menu bar but no windows (macOS) while I now realize the documentation actually refers to the case where a window is openend before assigning None to main_window.

MyMainWindow().show()
self.main_window = None

About the exception, I am not doing anything specific to trigger it, it seems to occur during program startup, and the app seems to keep working.

Thanks again for clarifying,

Best regards,

[freakboy3742]

I also misinterpreted the paragraph about assigning None to main_window. I wrote

self.main_window = None

assuming it would open an application with a menu bar but no windows (macOS) while I now realize the documentation actually refers to the case where a window is openend before assigning None to main_window.

The order of the calls in startup() isn't relevant. The assignment of main_window alters:

1. Whether a default document window is opened in a document-based app (but only on non-macOS platforms)
2. Whether the app exits when the last window is closed.

So - if you're on Windows, and you have a document type declared, and you don't explicitly open a Document window, and you set main_window = None, then yes - a default window will be created for your document type. However, the decision to open a default window is made after the completion of the user's startup() method.

About the exception, I am not doing anything specific to trigger it, it seems to occur during program startup, and the app seems to keep working.

Hrm... ok - there's very little we can do without a reproduction case. If you're able to identify anything else that might be contributing, it would be helpful to know.

[areslagae]

Hi,

In order to reproduce: this was actually the literal code of the "documentapp" example, also see code below.

https://github.com/beeware/toga/tree/main/examples/documentapp

I still have a somewhat related question. Suppose no window can be created due to an error condition (e.g. the user supplied file could not be opened). How do I display an error dialog to inform the user of the error and the closing of the app? I can create a dialog using self.loop.create_task() but meanwhile a runtime error RuntimeError: App didn't create any windows, or register any document types. is thrown. My current workaround is an invisible window, but that is not very elegant.

import toga


class ExampleDocument(toga.Document):
    description = "Example Document"
    extensions = ["exampledoc"]

    def create(self):
        # Create the main window for the document. The window has a single widget;
        # when that widget changes, the document is modified.
        self.main_window = toga.DocumentWindow(
            doc=self,
            content=toga.MultilineTextInput(on_change=self.touch),
        )

    def read(self):
        # Read the content of the file represented by the document, and populate the
        # widgets in the main window with that content.
        with self.path.open() as f:
            self.main_window.content.value = f.read()

    def write(self):
        # Save the content currently displayed by the main window.
        with self.path.open("w") as f:
            f.write(self.main_window.content.value)


class DocumentApp(toga.App):
    def startup(self):
        # A document-based app does not have a single main window. A window (or windows)
        # will be created from the document(s) specified at the command line; or if no
        # document is specified, the platform will determine how to create an initial
        # document.
        self.main_window = None


def main():
    return DocumentApp(
        "Document App",
        "org.beeware.toga.examples.documentapp",
        document_types=[ExampleDocument],
    )


if __name__ == "__main__":
    main().main_loop()

[freakboy3742]

Hi,

In order to reproduce: this was actually the literal code of the "documentapp" example, also see code below.

https://github.com/beeware/toga/tree/main/examples/documentapp

Hrm - I'm definitely not seeing the problem you describe. Can you share more details about your specific setup - OS versions, Python versions, Python source (Python.org? Conda? uv?) Anything else about your setup that might be influencing app execution (a non-EN locale? unusual network conditions?)

I still have a somewhat related question. Suppose no window can be created due to an error condition (e.g. the user supplied file could not be opened). How do I display an error dialog to inform the user of the error and the closing of the app? I can create a dialog using self.loop.create_task() but meanwhile a runtime error RuntimeError: App didn't create any windows, or register any document types. is thrown. My current workaround is an invisible window, but that is not very elegant.

The logic that is displaying that error is entirely contained in App._create_initial_windows(). If you provide your own custom implementation for that method, you can completely customise how the initial windows are created.

That's obviously a private method, so it's not guaranteed stable - but the RuntimeError behavior you're seeing is entirely contained in that one method.

As a longer term design activity - command line argument handling is an area where we know there are limitations. Right now, you can't have a document-based app that also accepts command line arguments; that's something we'd like to address; and if part of that design rework was to add other forms of customization around document handling, then all the better.

[areslagae]

W.r.t. the documentapp sample exception: I have submitted a bug report.

W.r.t. handling errors in startup():

Below is a workaround by overriding _create_initial_windows() per your suggestion. The code could be moved into startup() but you would still have to override _create_initial_windows to avoid the exception. I am not sure if it is OK to call self.exit() in startup() or _create_initial_windows() however. This is definitely an OK workaround, but it does not seem a good final solution, because of the override of the private method.

I do want to point out that this issue is not limited to handling documents or parsing arguments (which was just an example and not my actual use case). In general, real world applications have various reasons to fail in the startup phase. Is there a deeper issue here, that there does not seem to be an easy way to report an error in startup() to the user? Which in the end is a common scenario. Or am I (again ;-) ) missing something?

    def startup(self):

        ...

        self.main_window = None

    def _create_initial_windows(self):
        try:
            ...
            # do stuff, perhaps loading a file, loading a config file, ...
            raise RuntimeError('error') # simulate error
            ...
        except Exception as error:
            async def _await_dialog_and_exit(dialog):
                await self.dialog(dialog)
                self.exit()        
            self.loop.create_task(_await_dialog_and_exit(toga.ErrorDialog(title=self.formal_name, message=f'Error: {error}')))

[freakboy3742]

W.r.t. the documentapp sample exception: I have submitted a bug report.

Thanks - I've now been able to reproduce the problem; and the fix seems to be the same as it is for #4347.

W.r.t. handling errors in startup():

Below is a workaround by overriding _create_initial_windows() per your suggestion. The code could be moved into startup() but you would still have to override _create_initial_windows to avoid the exception. I am not sure if it is OK to call self.exit() in startup() or _create_initial_windows() however. This is definitely an OK workaround, but it does not seem a good final solution, because of the override of the private method.

Completely agreed it's not an ideal solution - it "works for now", but as it's not a documented API, you won't be able to 100% guarantee it will continue to work.

As for calling exit() - I can't spot any obvious problems with that approach.

I do want to point out that this issue is not limited to handling documents or parsing arguments (which was just an example and not my actual use case). In general, real world applications have various reasons to fail in the startup phase. Is there a deeper issue here, that there does not seem to be an easy way to report an error in startup() to the user? Which in the end is a common scenario. Or am I (again ;-) ) missing something?

I don't think you're missing anything - the idea that an app might fail during startup is something we haven't really accounted for. We're open to suggestions for how this could be handled in a way that makes sense in the general case.

The core of the problem is to establish exactly what contractual guarantees an app can provide in case of failure - how "active" is the app? Can you display a dialog? Can you display an emergency window? Will the app loop be running? Is an exit implied? Is there any way to recover?

[areslagae]

I don't think you're missing anything - the idea that an app might fail during startup is something we haven't really accounted for. We're open to suggestions for how this could be handled in a way that makes sense in the general case.

The core of the problem is to establish exactly what contractual guarantees an app can provide in case of failure - how "active" is the app? Can you display a dialog? Can you display an emergency window? Will the app loop be running? Is an exit implied? Is there any way to recover?

Thanks for your thoughts on this.

W.r.t provided guarantees (if I interpret what you write you correctly): The error would be in user part of the code and not in Toga part of the code. So I think we can assume that the Toga part is still working correctly, and we can determine upfront if e.g. the application loop is running during the startup method for example. From a user perspective the solution below would already be very useful.

    async def startup(self):

        try:
            ...
            # user code that could throw an error
            ...
        except Exception as error:
            await self.dialog(toga.ErrorDialog(...))
            return False / self.exit() / raise

This would require

• a way to display an app level dialog (from a user perspective ideally using await self.dialog)
• a way to exit the program (return False, self.exit() or re-raise).
  Which are both already mostly in place.

The exit strategy probably requires some thought. This may also interact with how cleanup is handled (e.g. uncaught exception handling, atexits and return out of the main loop). I previously posted about that.

In general, I think I would prefer if an exit of the app would return control to the caller of app.main_loop(), if possible of course. That would at least open up options for resource management.

# allocate resources, set-up logging, ... here or in app.startup() ?
try:
    app = MyApp(...)
    app.main_loop()
except:
    ....
    # allow catching of exceptions here or not?

[freakboy3742]

This would require

• a way to display an app level dialog (from a user perspective ideally using await self.dialog)
• a way to exit the program (return False, self.exit() or re-raise).
  Which are both already mostly in place.

The exit strategy probably requires some thought. This may also interact with how cleanup is handled (e.g. uncaught exception handling, atexits and return out of the main loop). I previously posted about that.

The problem with this is that when startup() is called, the event loop isn't running yet. That why is isn't (and can't) be declared as async, and you can't await a dialog - there's no loop to await. on_running() will generally be the first task to fire on a running loop. If you've got logic that can fail and needs to display a dialog, you might be better suited to putting that logic into on_running(), and limit the content of startup() to things that cannot fail - at the very minimum, the creation (but not necessarily showing) the main window, or at least the assignment of self.main_window.

In general, I think I would prefer if an exit of the app would return control to the caller of app.main_loop(), if possible of course. That would at least open up options for resource management.

I might be missing what you mean here, because that is what happens already. When you exit the app, the main loop exits, and the program continues. At that point, you can't then display GUI operations... because the main loop has exited - but you can do any resource cleanup you might need.

[areslagae]

I might be missing what you mean here, because that is what happens already. When you exit the app, the main loop exits, and the program continues. At that point, you can't then display GUI operations... because the main loop has exited - but you can do any resource cleanup you might need.

OK, I see now in #4320 the the current behavior in macOS - a program termination from the event loop - is actually not the intended behavior. That's good.

The problem with this is that when startup() is called, the event loop isn't running yet. That why is isn't (and can't) be declared as async, and you can't await a dialog - there's no loop to await. on_running() will generally be the first task to fire on a running loop. If you've got logic that can fail and needs to display a dialog, you might be better suited to putting that logic into on_running(), and limit the content of startup() to things that cannot fail - at the very minimum, the creation (but not necessarily showing) the main window, or at least the assignment of self.main_window.

OK, I had a look at the source code and I understand what you mean. I actually assumed that startup() was called from App.main_loop() and not from App.init().

According to the documentation, startup() must create the main window for the application.

1. If you see this process as part of the initialization of App, so before any user interaction can take place, this makes totally sense.
2. If you accept the idea that window creation can involve user interaction - and I think a compelling case can be made that it actually does - it makes less sense to me.

The options are not mutually exclusive. Option 1/ seems as intended / as designed? Option 2/ seems almost supported. At first sight, it seems possible to move window creation that might involve user interaction to App.on_running(), except that you need to avoid the exception involving no windows, see code below. I think this is a better workaround than in my previous post.

    def startup(self):
        self.main_window = None

    def _create_initial_windows(self):
        pass # avoid exception for no windows

    async def on_running(self):

        # create windows here instead, which allows the same user interaction with await self.dialog as in e.g. an app.open() handler

        main_window = None
        try:
            ...
            # do stuf needed to create windows
            # raise RuntimeError('error while creating windows')
            ...
        except Exception as error:
            await self.dialog(toga.ErrorDialog(title=self.formal_name, message=f'Error: {error}'))
            self.exit()

        self.main_window = main_window

This is something other Toga users will also be confronted with I think.

• I was a bit misled by studying the current implementation of Documents. It calls _create_initial_windows() from startup(). This becomes an issue as soon as open functions might signal an error. It seems that App itself is working around the limitation of not having user interaction with the line "self.loop.create_task(self.documents.request_open())".
• One possible solution would be to postpone the check for a main window until after on_running() has returned. That might allow both options above to coexist. The distinction between whether or not user input is required to place code in startup() or on_running() seems to make sense.

Also, I found naming a bit confusing.

• The App.init() startup parameter seems a factory for a widget. I would perhaps consider "content_factory".
• App.startup() is actually an extension of App.init(). I associate names with start() with the start of the execution which here is the main loop (cfr. thread() and thread.start()), assuming it was called there. I would perhaps consider "init()" with default implementation create the main window using content_factory. That would make clear the method is an extension of init rather than a part of the main_loop.
• I would perhaps consider adding a method start() that is called as soon as main_loop has started, that could perhaps call on_started as default implementation. I find this more clear than on_running

You could then easily explain to users:

• Custom window creation and other initialization which does not require user interaction belongs in init(). It is part of the constructor that makes the App object ready to run.
• Custom window creation and other initialization that does require user interaction belongs in start(). It is executed as soon as the user interface is actually up and running as a first step of the main loop.

(But I fully realize this might be a matter of taste.)

[freakboy3742]

• I was a bit misled by studying the current implementation of Documents. It calls _create_initial_windows() from startup(). This becomes an issue as soon as open functions might signal an error. It seems that App itself is working around the limitation of not having user interaction with the line "self.loop.create_task(self.documents.request_open())".

I see what you're driving at here - "interaction during the window creation process" isn't an unreasonable requirement. Document creation is an obvious manifestation, but it's not the only one. Forced login dialogs could fall into the same category.

• One possible solution would be to postpone the check for a main window until after on_running() has returned. That might allow both options above to coexist. The distinction between whether or not user input is required to place code in startup() or on_running() seems to make sense.

I can see how that might work; the downside is that it would mean changing the (current) contract for on_running - at present, you can assume that you have a fully functioning set of windows; that wouldn't be the case if the main window check is deferred.

Thinking around the problem here - another option might be to allow startup to be an async method, and re-structure the startup process so that everything that is done by the app after the call to the user's startup() method is treated as a "cleanup" method on the user's wrapped startup method. If startup is synchronous, nothing would change; but if it were declared async, you would be able to await dialogs and do other.

My main hesitation on suggesting this is that app startup is a process that is subtly different on every platform, and I would not be at all surprised if there's at least one platform that doesn't deal well with this change. However, it would be worth some experimentation to see what is possible.

Also, I found naming a bit confusing.

• The App.init() startup parameter seems a factory for a widget. I would perhaps consider "content_factory".

I agree the inconsistency between the startup argument and the full startup() subclassed method is a little weird; however, it's also an edge case that I don't think is that hard to explain - "if you're subclassing the app, you have to take responsibility for the full startup process".

• App.startup() is actually an extension of App.init(). I associate names with start() with the start of the execution which here is the main loop (cfr. thread() and thread.start()), assuming it was called there. I would perhaps consider "init()" with default implementation create the main window using content_factory. That would make clear the method is an extension of init rather than a part of the main_loop.

I'm not sure I see the distinction you're making here. If anything, the content of startup() is exactly what you've described - a thing that happens when the app starts.

The other complication is that __init__ can't be async, so any of the suggestions you've made here with

• I would perhaps consider adding a method start() that is called as soon as main_loop has started, that could perhaps call on_started as default implementation. I find this more clear than on_running

This seems very much like a bikeshed to me. "Running" was picked because it ties directly to the language used by asyncio event loops ("is the event loop running?"), which is what the event handler designates, with the added layer of "...and the app has been started."