Merge pull request #2666 from freakboy3742/document-api

Finalize API for Document-based apps

android/src/toga_android/app.py

@@ -1,5 +1,4 @@
 import asyncio
-import sys
 import warnings
 
 from android.content import Context
@@ -11,9 +10,8 @@
 from org.beeware.android import IPythonApp, MainActivity
 
 import toga
-from toga.command import Command, Group, Separator
+from toga.command import Group, Separator
 from toga.dialogs import InfoDialog
-from toga.handlers import simple_handler
 
 from .libs import events
 from .screens import Screen as ScreenImpl
@@ -186,6 +184,9 @@ def onPrepareOptionsMenu(self, menu):
 class App:
     # Android apps exit when the last window is closed
     CLOSE_ON_LAST_WINDOW = True
+    # Android doesn't have command line handling;
+    # but saying it does shortcuts the default handling
+    HANDLES_COMMAND_LINE = True
 
     def __init__(self, interface):
         self.interface = interface
@@ -210,16 +211,8 @@ def create(self):
     # Commands and menus
     ######################################################################
 
-    def create_app_commands(self):
-        self.interface.commands.add(
-            # About should be the last item in the menu, in a section on its own.
-            Command(
-                simple_handler(self.interface.about),
-                f"About {self.interface.formal_name}",
-                section=sys.maxsize,
-                id=Command.ABOUT,
-            ),
-        )
+    def create_standard_commands(self):
+        pass
 
     def create_menus(self):
         # Menu items are configured as part of onPrepareOptionsMenu; trigger that

android/src/toga_android/command.py

@@ -1,10 +1,38 @@
+import sys
+
 from org.beeware.android import MainActivity
 
+from toga import Command as StandardCommand
+
 
 class Command:
     def __init__(self, interface):
         self.interface = interface
         self.native = []
 
+    @classmethod
+    def standard(cls, app, id):
+        # ---- Help menu ----------------------------------
+        if id == StandardCommand.ABOUT:
+            return {
+                "text": f"About {app.formal_name}",
+                "section": sys.maxsize,
+            }
+        # ---- Undefined commands--------------------------
+        elif id in {
+            StandardCommand.EXIT,
+            StandardCommand.NEW,
+            StandardCommand.OPEN,
+            StandardCommand.PREFERENCES,
+            StandardCommand.SAVE,
+            StandardCommand.SAVE_AS,
+            StandardCommand.SAVE_ALL,
+            StandardCommand.VISIT_HOMEPAGE,
+        }:
+            # These are valid commands, but they're not defined on Android.
+            return None
+
+        raise ValueError(f"Unknown standard command {id!r}")
+
     def set_enabled(self, value):
         MainActivity.singletonThis.invalidateOptionsMenu()

changes/2209.feature.2.rst

@@ -0,0 +1 @@
+The API for Documents and document types has been finalized. Document handling behavior is now controlled by declaring document types as part of your ``toga.App`` definition.

changes/2209.removal.rst

@@ -0,0 +1,13 @@
+The API for Documents and Document-based apps has been significantly modified. Unfortunately, these changes are not backwards compatible; any existing Document-based app will require modification.
+
+The ``DocumentApp`` base class is no longer required. Apps can subclass ``App`` directly, passing the document types as a ``list`` of ``Document`` classes, rather than a mapping of extension to document type.
+
+The API for ``Document`` subclasses has also changed:
+
+* A path is no longer provided as an argument to the Document constructor;
+
+* The ``document_type`` is now specified as a class property called ``description``; and
+
+* Extensions are now defined as a class property of the ``Document``; and
+
+* The ``can_close()`` handler is no longer honored. Documents now track if they are modified, and have a default ``on_close`` handler that uses the modification status of a document to control whether a document can close. Invoking ``touch()`` on document will mark a document as modified. This modification flag is cleared by saving the document.