classref: Sync with current 3.5 branch (5478afdb1)

classes/class_editorplugin.rst

@@ -628,7 +628,19 @@ Gets the Editor's dialog used for making scripts.
 
 - :ref:`Dictionary<class_Dictionary>` **get_state** **(** **)** |virtual|
 
-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 ``editstate`` file in the editor metadata folder. If you want to store global (scene-independent) editor data for your plugin, you can use :ref:`get_window_layout<class_EditorPlugin_method_get_window_layout>` instead.
+
+Use :ref:`set_state<class_EditorPlugin_method_set_state>` to restore your saved state.
+
+\ **Note:** This method should not be used to save important settings that should persist with the project.
+
+\ **Note:** You must implement :ref:`get_plugin_name<class_EditorPlugin_method_get_plugin_name>` for the state to be stored and restored correctly.
+
+::
+
+    func get_state():
+        var state = {"zoom": zoom, "preferred_color": my_color}
+        return state
 
 ----
 
@@ -644,7 +656,15 @@ Gets the undo/redo object. Most actions in the editor can be undoable, so use th
 
 - void **get_window_layout** **(** :ref:`ConfigFile<class_ConfigFile>` layout **)** |virtual|
 
-Gets the GUI layout of the plugin. This is used to save the project's editor layout when :ref:`queue_save_layout<class_EditorPlugin_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 :ref:`queue_save_layout<class_EditorPlugin_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 ``editor_layout.cfg`` file in the editor metadata directory.
+
+Use :ref:`set_window_layout<class_EditorPlugin_method_set_window_layout>` to restore your saved layout.
+
+::
+
+    func get_window_layout(configuration):
+        configuration.set_value("MyPlugin", "window_position", $Window.position)
+        configuration.set_value("MyPlugin", "icon_color", $Icon.modulate)
 
 ----
 
@@ -814,7 +834,15 @@ Use this method if you always want to receive inputs from 3D view screen inside
 
 - void **set_state** **(** :ref:`Dictionary<class_Dictionary>` state **)** |virtual|
 
-Restore the state saved by :ref:`get_state<class_EditorPlugin_method_get_state>`.
+Restore the state saved by :ref:`get_state<class_EditorPlugin_method_get_state>`. This method is called when the current scene tab is changed in the editor.
+
+\ **Note:** Your plugin must implement :ref:`get_plugin_name<class_EditorPlugin_method_get_plugin_name>`, otherwise it will not be recognized and this method will not be called.
+
+::
+
+    func set_state(data):
+        zoom = data.get("zoom", 1.0)
+        preferred_color = data.get("my_color", Color.white)
 
 ----
 
@@ -822,7 +850,13 @@ Restore the state saved by :ref:`get_state<class_EditorPlugin_method_get_state>`
 
 - void **set_window_layout** **(** :ref:`ConfigFile<class_ConfigFile>` layout **)** |virtual|
 
-Restore the plugin GUI layout saved by :ref:`get_window_layout<class_EditorPlugin_method_get_window_layout>`.
+Restore the plugin GUI layout and data saved by :ref:`get_window_layout<class_EditorPlugin_method_get_window_layout>`. This method is called for every plugin on editor startup. Use the provided ``configuration`` file to read your saved data.
+
+::
+
+    func set_window_layout(configuration):
+        $Window.position = configuration.get_value("MyPlugin", "window_position", Vector2())
+        $Icon.modulate = configuration.get_value("MyPlugin", "icon_color", Color.white)
 
 ----