[widget Audit] toga.Window

.github/workflows/ci.yml

@@ -207,10 +207,15 @@ jobs:
           - backend: linux
             runs-on: ubuntu-22.04
             # The package list should be the same as in tutorial-0.rst, and the BeeWare
-            # tutorial, plus flwm to provide a window manager
+            # tutorial, plus blackbox to provide a window manager. We need a window
+            # manager that is reasonably lightweight, honors full screen mode, and
+            # treats the window position as the top-left corner of the *window*, not the
+            # top-left corner of the window *content*. The default GNOME window managers of
+            # most distros meet these requirementt, but they're heavyweight; flwm doesn't
+            # work either. Blackbox is the lightest WM we've found that works.
             pre-command: |
               sudo apt update -y
-              sudo apt install -y flwm pkg-config python3-dev libgirepository1.0-dev libcairo2-dev gir1.2-webkit2-4.0
+              sudo apt install -y blackbox pkg-config python3-dev libgirepository1.0-dev libcairo2-dev gir1.2-webkit2-4.0
 
               # Start Virtual X server
               echo "Start X server..."
@@ -219,7 +224,7 @@ jobs:
 
               # Start Window manager
               echo "Start window manager..."
-              DISPLAY=:99 flwm &
+              DISPLAY=:99 blackbox &
               sleep 1
 
             briefcase-run-prefix: 'DISPLAY=:99'

changes/2058.feature.rst

@@ -0,0 +1 @@
+Window and MainWindow now have 100% test coverage, and complete API documentation.

changes/2058.removal.1.rst

@@ -0,0 +1 @@
+Windows no longer need to be explicitly added to the app's window list. When a window is shown, it will be automatically added to the windows for the currently running app.

changes/2058.removal.2.rst

@@ -0,0 +1 @@
+The ``multiselect`` argument to Open File and Select Folder dialogs has been renamed ``multiple_select``, for consistency with other widgets that have multiple selection capability.

changes/2058.removal.3.rst

@@ -0,0 +1 @@
+``Window.resizeable`` and ``Window.closeable`` have been renamed ``Window.resizable`` and ``Window.closable``, to adhere to US spelling conventions.

cocoa/src/toga_cocoa/app.py

@@ -135,12 +135,21 @@ def create(self):
         self.appDelegate.native = self.native
         self.native.setDelegate_(self.appDelegate)
 
-        formal_name = self.interface.formal_name
+        self._create_app_commands()
+
+        # Call user code to populate the main window
+        self.interface._startup()
+
+        # Create the lookup table of menu items,
+        # then force the creation of the menus.
+        self.create_menus()
 
+    def _create_app_commands(self):
+        formal_name = self.interface.formal_name
         self.interface.commands.add(
             # ---- App menu -----------------------------------
             toga.Command(
-                lambda _: self.interface.about(),
+                self._menu_about,
                 "About " + formal_name,
                 group=toga.Group.APP,
             ),
@@ -176,12 +185,35 @@ def create(self):
             ),
             # Quit should always be the last item, in a section on its own
             toga.Command(
-                lambda _: self.interface.exit(),
+                self._menu_exit,
                 "Quit " + formal_name,
                 shortcut=toga.Key.MOD_1 + "q",
                 group=toga.Group.APP,
                 section=sys.maxsize,
             ),
+            # ---- File menu ----------------------------------
+            # This is a bit of an oddity. Safari has 2 distinct "Close Window" and
+            # "Close All Windows" menu items (partially to differentiate from "Close
+            # Tab"). Most other Apple HIG apps have a "Close" item that becomes
+            # "Close All" when you press Option (MOD_2). That behavior isn't something
+            # we're currently set up to implement, so we live with a separate menu item
+            # for now.
+            toga.Command(
+                self._menu_close_window,
+                "Close Window",
+                shortcut=toga.Key.MOD_1 + "W",
+                group=toga.Group.FILE,
+                order=1,
+                section=50,
+            ),
+            toga.Command(
+                self._menu_close_all_windows,
+                "Close All Windows",
+                shortcut=toga.Key.MOD_2 + toga.Key.MOD_1 + "W",
+                group=toga.Group.FILE,
+                order=2,
+                section=50,
+            ),
             # ---- Edit menu ----------------------------------
             toga.Command(
                 NativeHandler(SEL("undo:")),
@@ -244,26 +276,39 @@ def create(self):
                 section=10,
                 order=60,
             ),
+            # ---- Window menu ----------------------------------
+            toga.Command(
+                self._menu_minimize,
+                "Minimize",
+                shortcut=toga.Key.MOD_1 + "m",
+                group=toga.Group.WINDOW,
+            ),
             # ---- Help menu ----------------------------------
             toga.Command(
-                lambda _: self.interface.visit_homepage(),
+                lambda _, **kwargs: self.interface.visit_homepage(),
                 "Visit homepage",
                 enabled=self.interface.home_page is not None,
                 group=toga.Group.HELP,
             ),
         )
-        self._create_app_commands()
 
-        # Call user code to populate the main window
-        self.interface._startup()
+    def _menu_about(self, app, **kwargs):
+        self.interface.about()
 
-        # Create the lookup table of menu items,
-        # then force the creation of the menus.
-        self.create_menus()
+    def _menu_exit(self, app, **kwargs):
+        self.interface.exit()
 
-    def _create_app_commands(self):
-        # No extra commands
-        pass
+    def _menu_close_window(self, app, **kwargs):
+        if self.interface.current_window:
+            self.interface.current_window._impl.native.performClose(None)
+
+    def _menu_close_all_windows(self, app, **kwargs):
+        for window in self.interface.windows:
+            window._impl.native.performClose(None)
+
+    def _menu_minimize(self, app, **kwargs):
+        if self.interface.current_window:
+            self.interface.current_window._impl.native.miniaturize(None)
 
     def create_menus(self):
         # Recreate the menu
@@ -427,6 +472,7 @@ def select_file(self, **kwargs):
 
 class DocumentApp(App):
     def _create_app_commands(self):
+        super()._create_app_commands()
         self.interface.commands.add(
             toga.Command(
                 lambda _: self.select_file(),

cocoa/src/toga_cocoa/container.py

@@ -103,8 +103,7 @@ def content(self, widget):
             widget.container = self
 
     def refreshed(self):
-        if self.on_refresh:
-            self.on_refresh(self)
+        self.on_refresh(self)
 
     @property
     def width(self):

cocoa/src/toga_cocoa/dialogs.py

@@ -7,9 +7,9 @@
     NSAlertFirstButtonReturn,
     NSAlertStyle,
     NSBezelBorder,
-    NSFileHandlingPanelOKButton,
     NSFont,
     NSMakeRect,
+    NSModalResponseOK,
     NSOpenPanel,
     NSSavePanel,
     NSScrollView,
@@ -20,7 +20,7 @@
 class BaseDialog(ABC):
     def __init__(self, interface):
         self.interface = interface
-        self.interface.impl = self
+        self.interface._impl = self
 
 
 class NSAlertDialog(BaseDialog):
@@ -46,21 +46,22 @@ def __init__(
         self.build_dialog(**kwargs)
 
         self.native.beginSheetModalForWindow(
-            interface.window._impl.native, completionHandler=completion_handler
+            interface.window._impl.native,
+            completionHandler=completion_handler,
         )
 
     def build_dialog(self):
         pass
 
     def completion_handler(self, return_value: int) -> None:
-        self.on_result(self, None)
+        self.on_result(None, None)
 
         self.interface.future.set_result(None)
 
     def bool_completion_handler(self, return_value: int) -> None:
         result = return_value == NSAlertFirstButtonReturn
 
-        self.on_result(self, result)
+        self.on_result(None, result)
 
         self.interface.future.set_result(result)
 
@@ -169,55 +170,62 @@ def __init__(
         filename,
         initial_directory,
         file_types,
-        multiselect,
+        multiple_select,
         on_result=None,
     ):
         super().__init__(interface=interface)
         self.on_result = on_result
 
         # Create the panel
-        self.create_panel(multiselect)
+        self.create_panel(multiple_select)
 
-        # Set all the
-        self.panel.title = title
+        # Set the title of the panel
+        self.native.title = title
 
         if filename:
-            self.panel.nameFieldStringValue = filename
+            self.native.nameFieldStringValue = filename
 
         if initial_directory:
-            self.panel.directoryURL = NSURL.URLWithString(
+            self.native.directoryURL = NSURL.URLWithString(
                 str(initial_directory.as_uri())
             )
 
-        self.panel.allowedFileTypes = file_types
+        self.native.allowedFileTypes = file_types
 
-        if multiselect:
+        if multiple_select:
             handler = self.multi_path_completion_handler
         else:
             handler = self.single_path_completion_handler
 
-        self.panel.beginSheetModalForWindow(
+        self.native.beginSheetModalForWindow(
             interface.window._impl.native,
             completionHandler=handler,
         )
 
+    # Provided as a stub that can be mocked in test conditions
+    def selected_path(self):
+        return self.native.URL
+
+    # Provided as a stub that can be mocked in test conditions
+    def selected_paths(self):
+        return self.native.URLs
+
     def single_path_completion_handler(self, return_value: int) -> None:
-        if return_value == NSFileHandlingPanelOKButton:
-            result = Path(self.panel.URL.path)
+        if return_value == NSModalResponseOK:
+            result = Path(str(self.selected_path().path))
         else:
             result = None
 
-        self.on_result(self, result)
-
+        self.on_result(None, result)
         self.interface.future.set_result(result)
 
     def multi_path_completion_handler(self, return_value: int) -> None:
-        if return_value == NSFileHandlingPanelOKButton:
-            result = [Path(url.path) for url in self.panel.URLs]
+        if return_value == NSModalResponseOK:
+            result = [Path(url.path) for url in self.selected_paths()]
         else:
             result = None
 
-        self.on_result(self, result)
+        self.on_result(None, result)
 
         self.interface.future.set_result(result)
 
@@ -238,12 +246,12 @@ def __init__(
             filename=filename,
             initial_directory=initial_directory,
             file_types=None,  # File types aren't offered by Cocoa save panels.
-            multiselect=False,
+            multiple_select=False,
             on_result=on_result,
         )
 
-    def create_panel(self, multiselect):
-        self.panel = NSSavePanel.alloc().init()
+    def create_panel(self, multiple_select):
+        self.native = NSSavePanel.alloc().init()
 
 
 class OpenFileDialog(FileDialog):
@@ -253,7 +261,7 @@ def __init__(
         title,
         initial_directory,
         file_types,
-        multiselect,
+        multiple_select,
         on_result=None,
     ):
         super().__init__(
@@ -262,16 +270,16 @@ def __init__(
             filename=None,
             initial_directory=initial_directory,
             file_types=file_types,
-            multiselect=multiselect,
+            multiple_select=multiple_select,
             on_result=on_result,
         )
 
-    def create_panel(self, multiselect):
-        self.panel = NSOpenPanel.alloc().init()
-        self.panel.allowsMultipleSelection = multiselect
-        self.panel.canChooseDirectories = False
-        self.panel.canCreateDirectories = False
-        self.panel.canChooseFiles = True
+    def create_panel(self, multiple_select):
+        self.native = NSOpenPanel.alloc().init()
+        self.native.allowsMultipleSelection = multiple_select
+        self.native.canChooseDirectories = False
+        self.native.canCreateDirectories = False
+        self.native.canChooseFiles = True
 
 
 class SelectFolderDialog(FileDialog):
@@ -280,7 +288,7 @@ def __init__(
         interface,
         title,
         initial_directory,
-        multiselect,
+        multiple_select,
         on_result=None,
     ):
         super().__init__(
@@ -289,14 +297,14 @@ def __init__(
             filename=None,
             initial_directory=initial_directory,
             file_types=None,
-            multiselect=multiselect,
+            multiple_select=multiple_select,
             on_result=on_result,
         )
 
-    def create_panel(self, multiselect):
-        self.panel = NSOpenPanel.alloc().init()
-        self.panel.allowsMultipleSelection = multiselect
-        self.panel.canChooseDirectories = True
-        self.panel.canCreateDirectories = True
-        self.panel.canChooseFiles = False
-        self.panel.resolvesAliases = True
+    def create_panel(self, multiple_select):
+        self.native = NSOpenPanel.alloc().init()
+        self.native.allowsMultipleSelection = multiple_select
+        self.native.canChooseDirectories = True
+        self.native.canCreateDirectories = True
+        self.native.canChooseFiles = False
+        self.native.resolvesAliases = True