toga icon indicating copy to clipboard operation
toga copied to clipboard

Finalize API for Document-based apps

Open freakboy3742 opened this issue 1 year ago • 6 comments
trafficstars

Derived from #2244.

Finalizes the Document-based app interface.

This unfortunately involves some backwards incompatible changes; I can't see any obvious way to retain compatibility with the old API and also allow for the flexibility needed to support GTK, Windows and "new/save" functionality. The changes aren't that invasive... I hope?

Summary of changes:

  • The DocumentApp class is no longer required; all the functionality of DocumentApp is now contained in App, controlled by being a session-based app that defines a document_type dictionary.
  • The Document base class no longer requires a path at time of construction. The path is now set as a side effect of opening or saving a document. This allows for creating empty "untitled" documents. Document subclasses will generally not need to override the constructor.
  • The document type of a Document must now be declared as a class-level property, rather than being handled as an instance property
  • The close handling of a document now uses a standard on_close handler, rather than a specialised interface. The default on_close handler tracks modification status of the document; a document can be marked as modified using the touch() API.
  • On macOS, if there's no open documents, giving the app focus opens the File Open dialog.
  • On GTK and Windows, starting the app with no documents creates an empty "Untitled" document.
  • Opening an document that is already open gives the existing representation focus.

There's no longer a need for an implementation-level document. The only backend that was using it was macOS; and it turns out we're not actually using any of the functionality that might make that interesting (like CoreData support). AFAICT, we can meet all the same app requirements using Python's file handling, and the standard cocoa command line handling API.

The testbed has been updated to use an automated window cleanup mechanism, rather than requiring each test to explicitly close windows that have been opened. This also ensures that garbage collection is enforced in the GUI thread (this was being done in the Window tests, but not in other examples). This is an extended version of what was included in #2682; this PR also removes the try/finally blocks that were manually implementing window cleanup.

Fixes #2209.

PR Checklist:

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

freakboy3742 avatar Jun 18 '24 06:06 freakboy3742