Merge pull request #790 from myk002/myk_exportlegends

[exportlegends] add overlays to integrate into legends UI

changelog.txt

@@ -27,6 +27,7 @@ Template for new versions:
 # Future
 
 ## New Features
+- `exportlegends`: new overlay that integrates with the vanilla "Export XML" button. Now you can generate both the vanilla export and the extended data export with a single click!
 
 ## Fixes
 - `suspendmanager`: Fix the overlay enabling/disabling `suspendmanager` unexpectedly

docs/exportlegends.rst

@@ -5,21 +5,46 @@ exportlegends
     :summary: Exports extended legends data for external viewing.
     :tags: legends inspection
 
-When run from the legends mode screen, you can export detailed data about your
-world so that it can be browsed with external programs like
-:forums:`Legends Browser <179848>` and other similar utilities. The data
-exported with this tool is more detailed than what you can get with vanilla
-export functionality, and some external tools depend on this extra information.
+When run from the legends mode screen, this tool will export detailed data
+about your world so that it can be browsed with external programs like
+:forums:`Legends Browser <179848>`. The data is more detailed than what you can
+get with vanilla export functionality, and many external tools depend on this
+extra information.
+
+By default, ``exportlegends`` hooks into the standard vanilla ``Export XML`` button and runs in the background when you click it, allowing both the vanilla export and the extended data export to execute simultaneously. You can continue to browse legends mode via the vanilla UI while the export is running.
 
 To use:
 
-- enter legends mode
-- click the vanilla "Export XML" button to get the standard export
-- run this command (``exportlegends``) to get the extended export
+- Enter legends by "Starting a new game" in an existing world and selecting
+  Legends mode
+- Ensure the toggle for "Also export extended legends data" is on (which is the
+  default)
+- Click the "Export XML" button to generate both the standard export and the
+  extended data export
+
+You can also generate just the extended data export by manually running the
+``exportlegends`` command while legends mode is open.
 
 Usage
 -----
 
 ::
 
     exportlegends
+
+Overlay
+-------
+
+This script also provides an overlay that is managed by the `overlay` framework.
+When the overlay is enabled, a toggle for exporting extended legends data will
+appear below the vanilla "Export XML" button. If the toggle is enabled when the
+"Export XML" button is clicked, then ``exportlegends`` will run alongside the
+vanilla data export.
+
+While the extended data is being exported, a status line will appear in place
+of the toggle, reporting the current export target and the overall percent
+complete.
+
+There is an additional overlay that masks out the "Done" button while the
+extended export is running. This prevents the player from exiting legends mode
+before the export is complete.