Document¶

A representation of a file on disk that will be displayed in one or more windows.

Availability (Key)

macOS	GTK	Windows	iOS	Android	Web	Terminal
●	●	●

Usage¶

A common requirement for apps is to view or edit a particular type of file. In Toga, you define a toga.Document class to represent each type of content that your app is able to manipulate. This Document class is then registered with your app when the App instance is created.

The toga.Document class describes how your document can be read, displayed, and saved. It also tracks whether the document has been modified. In this example, the code declares an "Example Document" document type, which will create files with the extensions .mydoc and .mydocument; because it is listed first, the .mydoc extension will be the default for documents of this type. The main window for this document type contains a MultilineTextInput. Whenever the content of that widget changes, the document is marked as modified:

import toga

class ExampleDocument(toga.Document):
    description = "Example Document"
    extensions = [`"mydoc", "mydocument"]

    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.DocumentMainWindow(
            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)

The document window uses the modification status to determine whether the window is allowed to close. If a document is modified, the user will be asked if they want to save changes to the document.

Registering document types¶

A document type is used by registering it with an app instance. The constructor for toga.App allows you to declare the collection of document types that your app supports. The first declared document type is treated as the default document type for your app; this is the type that will be connected to the keyboard shortcut of the NEW command.

After startup() returns, any filenames which were passed to the app by the operating system will be opened using the registered document types. If after this the app still has no windows, then:

On Windows and GTK, an untitled document of the default type will be opened.
On macOS, an Open dialog will be shown.

In the following example, the app will be able to manage documents of type ExampleDocument or OtherDocument, with ExampleDocument being the default content type. The app is configured to not have a single "main" window, so the life cycle of the app is not tied to a specific window.

import toga

class ExampleApp(toga.App):
    def startup(self):
        # The app does not have a single main window
        self.main_window = None

app = ExampleApp(
    "Document App",
    "com.example.documentapp",
    document_types=[ExampleDocument, OtherDocument]
)

app.main_loop()

By declaring these document types, the app will automatically have file management commands (New, Open, Save, etc) added.

Reference¶

toga.Document ¶

Document(app)

Bases: ABC

Create a new Document. Do not call this constructor directly - use DocumentSet.new, DocumentSet.open or DocumentSet.request_open instead.

PARAMETER	DESCRIPTION
`app`	The application the document is associated with. TYPE: `App`

app `property` ¶

app

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

main_window `property` `writable` ¶

main_window

The main window for the document.

modified `property` `writable` ¶

modified

Has the document been modified?

path `property` ¶

path

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

title `property` ¶

title

The title of the document.

This will be used as the default title of a toga.DocumentWindow that contains the document.

create `abstractmethod` ¶

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.

focus ¶

focus()

Give the document focus in the app.

hide ¶

hide()

Hide the visual representation for this document.

open ¶

open(path)

Open a file as a document.

PARAMETER	DESCRIPTION
`path`	The file to open. TYPE: `str \| Path`

read `abstractmethod` ¶

read()

Load a representation of the document into memory from Document.path, and populate the document window.

save ¶

save(path=None)

Save the document as a file.

If a path is provided, the path for the document will be updated. Otherwise, the existing path will be used.

If the Document.write() method has not been implemented, this method is a no-op.

PARAMETER	DESCRIPTION
`path`	If provided, the new file name for the document. TYPE: `str \| Path \| None` DEFAULT: `None`

show ¶

show()

Show the visual representation for this document.

touch ¶

touch(*args, **kwargs)

Mark the document as modified.

This method accepts *args and **kwargs so that it can be used as an on_change handler; these arguments are not used.

write ¶

write()

Persist a representation of the current state of the document.

This method is a no-op by default, to allow for read-only document types.

toga.documents.DocumentSet ¶

DocumentSet(app, types)

Bases: Sequence[Document], Mapping[Path, Document]

A collection of documents managed by an app.

A document is automatically added to the app when it is created, and removed when it is closed. The document collection will be stored in the order that documents were created.

PARAMETER	DESCRIPTION
`app`	The app that this instance is bound to. TYPE: `App`
`types`	The document types managed by this app. TYPE: `list[type[Document]]`

types `property` ¶

types

The list of document types the app can manage.

The first document type in the list is the app's default document type.

new ¶

new(document_type)

Create a new document of the given type, and show the document window.

PARAMETER	DESCRIPTION
`document_type`	The document type that has been requested. TYPE: `type[Document]`

RETURNS	DESCRIPTION
`Document`	The newly created document.

open ¶

open(path)

Open a document in the app, and show the document window.

If the provided path is already an open document, the existing representation for the document will be given focus.

PARAMETER	DESCRIPTION
`path`	The path to the document to be opened. TYPE: `Path \| str`

RETURNS	DESCRIPTION
`Document`	The document that was opened.

RAISES	DESCRIPTION
`ValueError`	If the path describes a file that is of a type that doesn't match a registered document type.

request_open `async` ¶

request_open()

Present a dialog asking the user for a document to open, and pass the selected path to DocumentSet.open().

RETURNS	DESCRIPTION
`Document`	The document that was opened.

RAISES	DESCRIPTION
`ValueError`	If the path describes a file that is of a type that doesn't match a registered document type.

save `async` ¶

save()

Save the current content of an app.

If there isn't a current window, or current window doesn't define a save() method, the save request will be ignored.

save_all `async` ¶

save_all()

Save the state of all content in the app.

This method will attempt to call save() on every window associated with the app. Any windows that do not provide a save() method will be ignored.

save_as `async` ¶

save_as()

Save the current content of an app under a different filename.

If there isn't a current window, or the current window hasn't defined a save_as() method, the save-as request will be ignored.

Document¶

Usage¶

Registering document types¶

Reference¶

toga.Document ¶

app property ¶

main_window property writable ¶

modified property writable ¶

path property ¶

title property ¶

create abstractmethod ¶

focus ¶

hide ¶

open ¶

read abstractmethod ¶

save ¶

show ¶

touch ¶

write ¶

toga.documents.DocumentSet ¶

types property ¶

new ¶

open ¶

request_open async ¶

save async ¶

save_all async ¶

save_as async ¶

app `property` ¶

main_window `property` `writable` ¶

modified `property` `writable` ¶

path `property` ¶

title `property` ¶

create `abstractmethod` ¶

read `abstractmethod` ¶

types `property` ¶

request_open `async` ¶

save `async` ¶

save_all `async` ¶

save_as `async` ¶