Merge pull request #61659 from KoBeWi/state-of-the-ed

1 files changed, 29 insertions, 4 deletions

diff --git a/doc/classes/EditorPlugin.xml b/doc/classes/EditorPlugin.xml
index 48d0636df4..1514b82ff8 100644
--- a/doc/classes/EditorPlugin.xml
+++ b/doc/classes/EditorPlugin.xml
@@ -261,14 +261,28 @@
 		<method name="_get_state" qualifiers="virtual const">
 			<return type="Dictionary" />
 			<description>
-				Gets the state of your plugin editor. This is used when saving the scene (so state is kept when opening it again) and for switching tabs (so state can be restored when the tab returns).
+				Override this method to provide a state data you want to be saved, like view position, grid settings, folding, etc. This is used when saving the scene (so state is kept when opening it again) and for switching tabs (so state can be restored when the tab returns). This data is automatically saved for each scene in an [code]editstate[/code] file in the editor metadata folder. If you want to store global (scene-independent) editor data for your plugin, you can use [method _get_window_layout] instead.
+				Use [method _set_state] to restore your saved state.
+				[b]Note:[/b] This method should not be used to save important settings that should persist with the project.
+				[b]Note:[/b] You must implement [method _get_plugin_name] for the state to be stored and restored correctly.
+				[codeblock]
+				func _get_state():
+				    var state = {"zoom": zoom, "preferred_color": my_color}
+				    return state
+				[/codeblock]
 			</description>
 		</method>
 		<method name="_get_window_layout" qualifiers="virtual">
 			<return type="void" />
 			<argument index="0" name="configuration" type="ConfigFile" />
 			<description>
-				Gets the GUI layout of the plugin. This is used to save the project's editor layout when [method queue_save_layout] is called or the editor layout was changed(For example changing the position of a dock).
+				Override this method to provide the GUI layout of the plugin or any other data you want to be stored. This is used to save the project's editor layout when [method queue_save_layout] is called or the editor layout was changed (for example changing the position of a dock). The data is stored in the [code]editor_layout.cfg[/code] file in the editor metadata directory.
+				Use [method _set_window_layout] to restore your saved layout.
+				[codeblock]
+				func _get_window_layout(configuration):
+				    configuration.set_value("MyPlugin", "window_position", $Window.position)
+				    configuration.set_value("MyPlugin", "icon_color", $Icon.modulate)
+				[/codeblock]
 			</description>
 		</method>
 		<method name="_handles" qualifiers="virtual const">
@@ -302,14 +316,25 @@
 			<return type="void" />
 			<argument index="0" name="state" type="Dictionary" />
 			<description>
-				Restore the state saved by [method _get_state].
+				Restore the state saved by [method _get_state]. This method is called when the current scene tab is changed in the editor.
+				[b]Note:[/b] Your plugin must implement [method _get_plugin_name], otherwise it will not be recognized and this method will not be called.
+				[codeblock]
+				func _set_state(data):
+				    zoom = data.get("zoom", 1.0)
+				    preferred_color = data.get("my_color", Color.white)
+				[/codeblock]
 			</description>
 		</method>
 		<method name="_set_window_layout" qualifiers="virtual">
 			<return type="void" />
 			<argument index="0" name="configuration" type="ConfigFile" />
 			<description>
-				Restore the plugin GUI layout saved by [method _get_window_layout].
+				Restore the plugin GUI layout and data saved by [method _get_window_layout]. This method is called for every plugin on editor startup. Use the provided [code]configuration[/code] file to read your saved data.
+				[codeblock]
+				func _set_window_layout(configuration):
+				    $Window.position = configuration.get_value("MyPlugin", "window_position", Vector2())
+				    $Icon.modulate = configuration.get_value("MyPlugin", "icon_color", Color.white)
+				[/codeblock]
 			</description>
 		</method>
 		<method name="add_autoload_singleton">