diff --git a/tutorials/plugins/editor/img/inspector_plugin_example.png b/tutorials/plugins/editor/img/inspector_plugin_example.png new file mode 100644 index 000000000..774302b99 Binary files /dev/null and b/tutorials/plugins/editor/img/inspector_plugin_example.png differ diff --git a/tutorials/plugins/editor/inspector_plugins.rst b/tutorials/plugins/editor/inspector_plugins.rst index 84c7504ed..aa9b82a0e 100644 --- a/tutorials/plugins/editor/inspector_plugins.rst +++ b/tutorials/plugins/editor/inspector_plugins.rst @@ -4,53 +4,79 @@ Inspector plugins ================= The inspector dock supports custom plugins to create your own widgets for -editing properties. This tutorial explains how to use the -:ref:`class_EditorInspectorPlugin` and :ref:`class_EditorProperty` classes to -write such plugins with the example of creating a custom value editor. +editing properties. This can be beneficial when working with custom datatypes +and resources, but may be used to change the default behavior for built-in +types as well. It is possible to introduce custom controls for specific properties, +entire objects, and even detached controls associated with particular datatypes. + +This tutorial explains how to use the :ref:`class_EditorInspectorPlugin` +and :ref:`class_EditorProperty` classes to create a custom control for each +property of the integer type, replacing the default behavior with a button +that generates random values between numbers 0 and 99. + +.. figure:: img/inspector_plugin_example.png + :align: center + + The default behavior on the left, and the end result on the right. + Setup ----- -Just like :ref:`doc_making_plugins`, we start out by making a new plugin, -getting a ``plugin.cfg`` file created, and start with our -:ref:`class_EditorPlugin`. However, instead of using -``add_custom_node`` or ``add_control_to_dock`` we'll use -``add_inspector_plugin``. +Follow the :ref:`doc_making_plugins` guide to setup the framework for your +new plugin. Lets assume you've called your plugin folder ``my_inspector_plugin``. +If so, you should end up with a new ``addons/my_inspector_plugin`` folder +that contains two files: ``plugin.cfg`` and ``plugin.gd``. + +As before, ``plugin.gd`` is a script extending :ref:`class_EditorPlugin` and you +need to introduce new code for its ``_enter_tree`` and ``_exit_tree`` methods. To +setup your inspector plugin you must load its script and then create and add +the instance using ``add_inspector_plugin``. If the plugin is disabled you should +remove the instance you have added using ``remove_inspector_plugin``. + +.. note:: Take note, that here you are loading a script and not a packed scene. + Therefore you should use ``new()`` instead of ``instance()``. .. tabs:: .. code-tab:: gdscript GDScript - # MyEditorPlugin.gd + # plugin.gd tool extends EditorPlugin - var plugin func _enter_tree(): - # EditorInspectorPlugin is a resource, so we use `new()` instead of `instance()`. - plugin = preload("res://addons/MyPlugin/MyInspectorPlugin.gd").new() + plugin = preload("res://addons/my_inspector_plugin/MyInspectorPlugin.gd").new() add_inspector_plugin(plugin) func _exit_tree(): remove_inspector_plugin(plugin) + EditorInspectorPlugin --------------------- -To actually connect into the Inspector, we create a -:ref:`class_EditorInspectorPlugin` class. This script provides the "hooks" to -the inspector. Thanks to this class, the editor will call the functions within -the EditorInspectorPlugin while it goes through the process of building the UI -for the inspector. The script is used to check if we should enable ourselves for -any :ref:`class_Object` that is currently in the inspector (including any -:ref:`class_Resource` that is embedded!). +To be able to interact with the inspector dock, your ``MyInspectorPlugin.gd`` script +must extend the :ref:`class_EditorInspectorPlugin` class. This class provides +several virtual methods that can be implemented to affect the way the inspector +is handling properties. -Once enabled, EditorInspectorPlugin has methods that allow for adding -:ref:`class_EditorProperty` nodes or just custom :ref:`class_Control` nodes to -the beginning and end of the inspector for that :ref:`class_Object`, or for -overriding or changing existing property editors. +To have any effect at all the script must implement the ``can_handle()`` method. This +function is called for each edited :ref:`class_Object` and must return ``true`` if +this plugin should handle the object or its properties (including any :ref:`class_Resource` +that is embedded!). + +There are 4 other methods that can be implemented to add controls to the inspector at +specific positions. The ``parse_begin()`` and ``parse_end()`` functions are called only once +at the beginning and the end of parsing for each object, respectively. They can be used to +add controls at the very top or very bottom of the inspector layout with ``add_custom_control``. + +As the object is parsed the ``parse_category()`` and ``parse_property()`` functions are +called. In addition to ``add_custom_control`` both ``add_property_editor`` and +``add_property_editor_for_multiple_properties`` can be utilized. These methods are used +specifically to add :ref:`class_EditorProperty`-based controls. .. tabs:: .. code-tab:: gdscript GDScript @@ -58,71 +84,98 @@ overriding or changing existing property editors. # MyInspectorPlugin.gd extends EditorInspectorPlugin + var RandomIntEditor = preload("res://addons/my_inspector_plugin/RandomIntEditor.gd") + func can_handle(object): - # Here you can specify which object types (classes) should be handled by - # this plugin. For example if the plugin is specific to your player - # class defined with `class_name MyPlayer`, you can do: - # `return object is MyPlayer` - # In this example we'll support all objects, so: + # We will support all objects in this example. return true func parse_property(object, type, path, hint, hint_text, usage): # We will handle properties of type integer. if type == TYPE_INT: - # Register *an instance* of the custom property editor that we'll define next. - add_property_editor(path, MyIntEditor.new()) - # We return `true` to notify the inspector that we'll be handling - # this integer property, so it doesn't need to parse other plugins - # (including built-in ones) for an appropriate editor. + # Create an instance of the custom property editor and register + # it to a specific property path. + add_property_editor(path, RandomIntEditor.new()) + # Inform the editor to remove the default property editor for + # this property type. return true else: return false + EditorProperty -------------- -Next, we define the actual :ref:`class_EditorProperty` custom value editor that -we want instantiated to edit integers. This is a custom :ref:`class_Control` and -we can add any kinds of additional nodes to make advanced widgets to embed in -the inspector. +The :ref:`class_EditorProperty` class is a special type of :ref:`class_Control` that +can interact with edited objects inside of the inspector dock. By itself it doesn't +display anything, but can house any other control nodes, including complex +scenes. + +There are three essential parts to the script extending :ref:`class_EditorProperty`: + +1. There must be the ``_init`` method that sets up the node structure of the control. + +2. The ``update_property()`` method should be implemented to handle changes to the + data from the outside. + +3. A signal must be emitted at some point to inform the inspector that the control has + changed the property using ``emit_changed``. + +You can display your custom widget in two ways. Use the default ``add_child`` method +to display it to the right of the property name, and ``set_bottom_editor`` to position +it below the name. .. tabs:: .. code-tab:: gdscript GDScript - # MyIntEditor.gd + # RandomIntEditor.gd extends EditorProperty - class_name MyIntEditor + # The main control for editing the property. + var property_control = Button.new() + # An internal value of the property. + var current_value = 0 + # A guard against internal changes when the property is updated. var updating = false - var spin = EditorSpinSlider.new() func _init(): - # We'll add an EditorSpinSlider control, which is the same that the - # inspector already uses for integer and float edition. - # If you want to put the editor below the property name, use: - # `set_bottom_editor(spin)` - # Otherwise to put it inline with the property name use: - add_child(spin) - # To remember focus when selected back: - add_focusable(spin) - # Setup the EditorSpinSlider - spin.set_min(0) - spin.set_max(1000) - spin.connect("value_changed", self, "_spin_changed") + # Add the control as a direct child of EditorProperty node. + add_child(property_control) + # Make sure the control is able to retain the focus. + add_focusable(property_control) + # Setup the initial state and connect to the signal to track changes. + property_control.text = "Value: " + str(current_value) + property_control.connect("pressed", self, "_on_button_pressed") - func _spin_changed(value): + func _on_button_pressed(): + # Ignore the signal if the property is currently being updated. if (updating): return - emit_changed(get_edited_property(), value) + + # Generate a new random integer between 0 and 99. + current_value = randi() % 100 + property_control.text = "Value: " + str(current_value) + emit_changed(get_edited_property(), current_value) func update_property(): + # Read the current value from the property. var new_value = get_edited_object()[get_edited_property()] + if (new_value == current_value): + return + + # Update the control with the new value. updating = true - spin.set_value(new_value) + current_value = new_value + property_control.text = "Value: " + str(current_value) updating = false + + +Using the example code above you should be able to make a custom widget +that replaces the default :ref:`class_SpinBox` control for integers with +a :ref:`class_Button` that generates random values.