DocumentApp

The top-level representation of an application that manages documents.

Availability (Key)

macOS

GTK

Windows

iOS

Android

Web

Terminal

○

○

Usage

A DocumentApp is a specialized subclass of App that is used to manage documents. A DocumentApp does not have a main window; each document that the app manages has it’s own main window. Each document may also define additional windows, if necessary.

The types of documents that the DocumentApp can manage must be declared as part of the instantiation of the DocumentApp. This requires that you define a subclass of toga.Document that describes how your document can be read and displayed. In this example, the code declares an “Example Document” document type, whose files have an extension of mydoc:

import toga

class ExampleDocument(toga.Document):
    def __init__(self, path, app):
        super().__init__(document_type="Example Document", path=path, app=app)

    def create(self):
        # Create the representation for the document's main window
        self.main_window = toga.DocumentMainWindow(self)
        self.main_window.content = toga.MultilineTextInput()

    def read(self):
        # Put your logic to read the document here. For example:
        with self.path.open() as f:
            self.content = f.read()

        self.main_window.content.value = self.content

app = toga.DocumentApp("Document App", "com.example.document", {"mydoc": MyDocument})
app.main_loop()

The exact behavior of a DocumentApp is slightly different on each platform, reflecting platform differences.

macOS

On macOS, there is only ever a single instance of a DocumentApp running at any given time. That instance can manage multiple documents. If you use the Finder to open a second document of a type managed by the DocumentApp, it will be opened in the existing DocumentApp instance. Closing all documents will not cause the app to exit; the app will keep executing until explicitly exited.

If the DocumentApp is started without an explicit file reference, a file dialog will be displayed prompting the user to select a file to open. If this dialog can be dismissed, the app will continue running. Selecting “Open” from the file menu will also display this dialog; if a file is selected, a new document window will be opened.

Linux/Windows

On Linux and Windows, each DocumentApp instance manages a single document. If your app is running, and you use the file manager to open a second document, a second instance of the app will be started. If you close a document’s main window, the app instance associated with that document will exit, but any other app instances will keep running.

If the DocumentApp is started without an explicit file reference, a file dialog will be displayed prompting the user to select a file to open. If this dialog is dismissed, the app will continue running, but will show an empty document. Selecting “Open” from the file menu will also display this dialog; if a file is selected, the current document will be replaced.

Reference

class toga.DocumentApp(formal_name=None, app_id=None, app_name=None, *, icon=None, author=None, version=None, home_page=None, description=None, startup=None, document_types=None, on_exit=None, id=None)

Bases: App

Create a document-based application.

A document-based application is the same as a normal application, with the exception that there is no main window. Instead, each document managed by the app will create and manage its own window (or windows).

Parameters:
property document_types: dict[str, type[Document]]

The document types this app can manage.

A dictionary of file extensions, without leading dots, mapping to the toga.Document subclass that will be created when a document with that extension is opened. The subclass must take exactly 2 arguments in its constructor: path and app.

property documents: list[Document]

The list of documents associated with this app.

startup()

No-op; a DocumentApp has no windows until a document is opened.

Subclasses can override this method to define customized startup behavior.

Return type:

None

class toga.Document(path, document_type, app=None)

Bases: ABC

Create a new Document.

Parameters:

  • path (str | Path) – The path where the document is stored.

  • document_type (str) – A human-readable description of the document type.

  • app (App) – The application the document is associated with.

property app: App

The app that this document is associated with (read-only).

can_close()

Is the main document window allowed to close?

The default implementation always returns True; subclasses can override this to prevent a window closing with unsaved changes, etc.

This default implementation is a function; however, subclasses can define it as an asynchronous co-routine if necessary to allow for dialog confirmations.

Return type:

bool

abstract create()

Create the window (or windows) for the document.

This method must, at a minimum, assign the main_window property. It may also create additional windows or UI elements if desired.

Return type:

None

property document_type: Path

A human-readable description of the document type (read-only).

property filename: Path

DEPRECATED - Use path.

async handle_close(window, **kwargs)

An on-close handler for the main window of this document that implements platform-specific document close behavior.

It interrogates the can_close() method to determine if the document is allowed to close.

property main_window: Window

The main window for the document.

property path: Path

The path where the document is stored (read-only).

abstract read()

Load a representation of the document into memory and populate the document window.

Return type:

None

show()

Show the main_window for this document.

Return type:

None