Add support for background and session-based apps

[freakboy3742]

Builds on #2649; that PR should be reviewed and merged before reviewing this one.

Derived from #2244.

Adds support for 2 new application types:

• Background apps: Apps that run, but aren't required to have any windows. This is the precursor to having system tray apps.
• Session-based apps: Apps that don't have a single "main" window, but multiple windows each of which manages a "session". What was previously called a "document-based" app would be a session-based app (with each session being a document); web browsers and file managers would also be session-based (where each session is an open URL, or a view on a directory). Session-based apps can have multiple open windows. Behavior when the last window is closed varies by platform; on macOS, the app persists; on Windows/GTK, closing the last window closes the app.

Includes a new statusiconapp example to demonstrate background apps. This is a bit of a stub until full status icon support is added in a subsequent PR. The key detail is that a background app is configured by setting main_window = toga.App.BACKGROUND.

The documentapp example is used as an example of session-based apps; the addition from this PR is that configuring the app requires setting main_window = None.

This PR also adds a runnning() method on apps that can be overridden by subclasses; this is guaranteed to be executed as soon as the main event loop starts. This simplifies a common use case of using startup() to add a background task. The statusiconapp contains a simple example of usage.

This PR uses the document-based app as a testing exemplar of session-based apps. Testing the session-based API requires loosening some of the test coverage related to document handling; these tests will be made more robust in a subsequent PR that finalises the Document API.

Two notable minor changes:

1. On Winforms, the main window is no longer set as the application's context. This was needed prior to Decoupled winforms event loop from AppContext. #2112, but is now redundant; there's also a side effect that assigning a window as the application context forces the window to be shown. Fixes On Windows, the creation of MainWindow renders it in the display without calling show() #2653.
2. On GTK, the call to set the "role" of the window has been removed. This call is only useful on X11; and even then, is only used to provide a position restoration hint if the app's window name isn't unique.

Refs #2209.
Refs #97.

PR Checklist:

• All new features have been tested
• All new features have been documented
• I have read the CONTRIBUTING.md file
• I will abide by the code of conduct

[mhsmith]

This PR also adds a runnning() method on apps that can be overridden by subclasses; this is guaranteed to be executed as soon as the main event loop starts. This simplifies a common use case of using startup() to add a background task.

As we discussed starting at #2099 (comment), this can now be written as self.loop.create_task(my_async_function()). This seems simple enough already, and is more flexible because it supports any number of tasks, created at any time, with any arguments.

[mhsmith]

Hiding the module name would make the page more readable. In fact, I think we should be doing this more generally in the docs.

Suggested change

	:class:`toga.Window`
	~~~~~~~~~~~~~~~~~~~~
	:class:`Window`
	~~~~~~~~~~~~~~~

[freakboy3742]

Agreed; however, AIUI, the ~ is the preferred way to do this; that keeps the Sphinx reference explicit, while hiding the context.

[mhsmith]

It makes a difference when there are more than two components. For example, :any:~toga.App.exit will display as exit, while :any:App.exit will display as App.exit.

If you use the :any: syntax, Sphinx doesn't require names to be absolute, it just searches for a match among all the targets in the docs, and gives an error if it doesn't find exactly one. This usually allows you to write the names in the RST exactly as you want them to appear in the HTML.

I'm not suggesting any more changes to this PR, just that in future it's probably better to avoid littering the docs with toga everywhere. Note that toga is already hidden in the right sidebar, and in argument and return types.

[mhsmith]

Another advantage of using :any: is that it gives an error if it doesn't find a valid target, while :class:, :meth:, etc. all fail silently and output the text with no hyperlink.

[freakboy3742]

This PR also adds a runnning() method on apps that can be overridden by subclasses; this is guaranteed to be executed as soon as the main event loop starts. This simplifies a common use case of using startup() to add a background task.

As we discussed starting at #2099 (comment), this can now be written as self.loop.create_task(my_async_function()). This seems simple enough already, and is more flexible because it supports any number of tasks, created at any time, with any arguments.

I agree that it can be spelled like this; but "logic I want to run as soon as the event loop is running" is a very common pattern; and that logic won't always be async. To my mind, providing explicit support for this use case is worth it, even if it can be replicated with other primitives - if only for the beginner use case, because it means we can expose the capability without needing to give a full primer on what a "task" is in the context of asyncio.

[mhsmith]

After discussion, we agreed to do the following in a separate PR:

• Change running into an event handler called on_running. Like other event handlers, this will support being assigned as a property or a constructor argument.
• Since the App class is designed to be subclassed, we'll also support overriding the event property with a synchronous or asynchronous method.
• Do the same with on_exit.

[freakboy3742]

See #2678 for the discussed changes around on_exit and running.