Fix add-on usages of addMedia (#1721)

* Expose old .addMedia again, and use a new resolve_media for built-in uses

* Add an explaining comment for addMedia

* Add some docstrings (dae)

qt/aqt/editor.py

@@ -688,13 +688,15 @@ require("anki/ui").loaded.then(() => require("anki/NoteEditor").instances[0].too
     ######################################################################
 
     def onAddMedia(self) -> None:
+        """Show a file selection screen, then add the selected media.
+        This expects initial setup to have been done by TemplateButtons.svelte."""
         extension_filter = " ".join(
             f"*.{extension}" for extension in sorted(itertools.chain(pics, audio))
         )
         filter = f"{tr.editing_media()} ({extension_filter})"
 
         def accept(file: str) -> None:
-            self.addMedia(file)
+            self.resolve_media(file)
 
         file = getFile(
             parent=self.widget,
@@ -707,8 +709,20 @@ require("anki/ui").loaded.then(() => require("anki/NoteEditor").instances[0].too
         self.parentWindow.activateWindow()
 
     def addMedia(self, path: str, canDelete: bool = False) -> None:
-        """canDelete is a legacy arg and is ignored."""
+        """Legacy routine used by add-ons to add a media file and update the current field.
+        canDelete is ignored."""
 
+        try:
+            html = self._addMedia(path)
+        except Exception as e:
+            showWarning(str(e))
+            return
+
+        self.web.eval(f"setFormat('inserthtml', {json.dumps(html)});")
+
+    def resolve_media(self, path: str) -> None:
+        """Finish inserting media into a field.
+        This expects initial setup to have been done by TemplateButtons.svelte."""
         try:
             html = self._addMedia(path)
         except Exception as e:
@@ -716,7 +730,7 @@ require("anki/ui").loaded.then(() => require("anki/NoteEditor").instances[0].too
             return
 
         self.web.eval(
-            f'require("anki/TemplateButtons").mediaResolve({json.dumps(html)})'
+            f'require("anki/TemplateButtons").resolveMedia({json.dumps(html)})'
         )
 
     def _addMedia(self, path: str, canDelete: bool = False) -> str:
@@ -734,7 +748,7 @@ require("anki/ui").loaded.then(() => require("anki/NoteEditor").instances[0].too
             self.parentWindow,
             self.mw,
             True,
-            lambda file: self.addMedia(file, canDelete=True),
+            self.resolve_media,
         )
 
     # Media downloads

ts/editor/editor-toolbar/TemplateButtons.svelte

@@ -31,13 +31,11 @@ License: GNU AGPL, version 3 or later; http://www.gnu.org/licenses/agpl.html
     let mediaPromise: Promise<string>;
     let resolve: (media: string) => void;
 
-    function mediaResolve(media: string): void {
+    function resolveMedia(media: string): void {
-        resolve(media);
+        resolve?.(media);
     }
 
-    registerPackage("anki/TemplateButtons", { mediaResolve });
+    function attachMediaOnFocus(): void {
-
-    function onAttachment(): void {
         if (!editingInputIsRichText($focusedInput)) {
             return;
         }
@@ -51,9 +49,13 @@ License: GNU AGPL, version 3 or later; http://www.gnu.org/licenses/agpl.html
         bridgeCommand("attach");
     }
 
+    registerPackage("anki/TemplateButtons", {
+        resolveMedia,
+    });
+
     const recordCombination = "F5";
 
-    function onRecord(): void {
+    function attachRecordingOnFocus(): void {
         if (!editingInputIsRichText($focusedInput)) {
             return;
         }
@@ -87,11 +89,14 @@ License: GNU AGPL, version 3 or later; http://www.gnu.org/licenses/agpl.html
                 )})"
                 iconSize={70}
                 {disabled}
-                on:click={onAttachment}
+                on:click={attachMediaOnFocus}
             >
                 {@html paperclipIcon}
             </IconButton>
-            <Shortcut keyCombination={attachmentCombination} on:action={onAttachment} />
+            <Shortcut
+                keyCombination={attachmentCombination}
+                on:action={attachMediaOnFocus}
+            />
         </ButtonGroupItem>
 
         <ButtonGroupItem>
@@ -101,11 +106,14 @@ License: GNU AGPL, version 3 or later; http://www.gnu.org/licenses/agpl.html
                 )})"
                 iconSize={70}
                 {disabled}
-                on:click={onRecord}
+                on:click={attachRecordingOnFocus}
             >
                 {@html micIcon}
             </IconButton>
-            <Shortcut keyCombination={recordCombination} on:action={onRecord} />
+            <Shortcut
+                keyCombination={recordCombination}
+                on:action={attachRecordingOnFocus}
+            />
         </ButtonGroupItem>
 
         <ButtonGroupItem id="cloze">