diff options
Diffstat (limited to 'doc')
| -rw-r--r-- | doc/classes/EditorDebuggerPlugin.xml | 116 | ||||
| -rw-r--r-- | doc/classes/EditorDebuggerSession.xml | 86 | ||||
| -rw-r--r-- | doc/classes/EditorPlugin.xml | 4 |
3 files changed, 146 insertions, 60 deletions
diff --git a/doc/classes/EditorDebuggerPlugin.xml b/doc/classes/EditorDebuggerPlugin.xml index c3e0a995c6..10da1edd56 100644 --- a/doc/classes/EditorDebuggerPlugin.xml +++ b/doc/classes/EditorDebuggerPlugin.xml @@ -1,88 +1,88 @@ <?xml version="1.0" encoding="UTF-8" ?> -<class name="EditorDebuggerPlugin" inherits="Control" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> +<class name="EditorDebuggerPlugin" inherits="RefCounted" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> <brief_description> A base class to implement debugger plugins. </brief_description> <description> [EditorDebuggerPlugin] provides functions related to the editor side of the debugger. - You don't need to instantiate this class; that is automatically handled by the debugger. [Control] nodes can be added as child nodes to provide a GUI for the plugin. - Do not free or reparent this node, otherwise it becomes unusable. - To use [EditorDebuggerPlugin], register it using the [method EditorPlugin.add_debugger_plugin] method first. + To interact with the debugger, an instance of this class must be added to the editor via [method EditorPlugin.add_debugger_plugin]. + Once added, the [method _setup_session] callback will be called for every [EditorDebuggerSession] available to the plugin, and when new ones are created (the sessions may be inactive during this stage). + You can retrieve the available [EditorDebuggerSession]s via [method get_sessions] or get a specific one via [method get_session]. + [codeblocks] + [gdscript] + @tool + extends EditorPlugin + + class ExampleEditorDebugger extends EditorDebuggerPlugin: + + func _has_capture(prefix): + # Return true if you wish to handle message with this prefix. + return prefix == "my_plugin" + + func _capture(message, data, session_id): + if message == "my_plugin:ping": + get_session(session_id).send_message("my_plugin:echo", data) + + func _setup_session(session_id): + # Add a new tab in the debugger session UI containing a label. + var label = Label.new() + label.name = "Example plugin" + label.text = "Example plugin" + var session = get_session(session_id) + # Listens to the session started and stopped signals. + session.started.connect(func (): print("Session started")) + session.stopped.connect(func (): print("Session stopped")) + session.add_session_tab(label) + + var debugger = ExampleEditorDebugger.new() + + func _enter_tree(): + add_debugger_plugin(debugger) + + func _exit_tree(): + remove_debugger_plugin(debugger) + [/gdscript] + [/codeblocks] </description> <tutorials> </tutorials> <methods> - <method name="has_capture"> - <return type="bool" /> - <param index="0" name="name" type="StringName" /> - <description> - Returns [code]true[/code] if a message capture with given name is present otherwise [code]false[/code]. - </description> - </method> - <method name="is_breaked"> - <return type="bool" /> - <description> - Returns [code]true[/code] if the game is in break state otherwise [code]false[/code]. - </description> - </method> - <method name="is_debuggable"> + <method name="_capture" qualifiers="virtual"> <return type="bool" /> + <param index="0" name="message" type="String" /> + <param index="1" name="data" type="Array" /> + <param index="2" name="session_id" type="int" /> <description> - Returns [code]true[/code] if the game can be debugged otherwise [code]false[/code]. + Override this method to process incoming messages. The [param session_id] is the ID of the [EditorDebuggerSession] that received the message (which you can retrieve via [method get_session]). </description> </method> - <method name="is_session_active"> + <method name="_has_capture" qualifiers="virtual const"> <return type="bool" /> + <param index="0" name="capture" type="String" /> <description> - Returns [code]true[/code] if there is an instance of the game running with the attached debugger otherwise [code]false[/code]. + Override this method to enable receiving messages from the debugger. If [param capture] is "my_message" then messages starting with "my_message:" will be passes to the [method _capture] method. </description> </method> - <method name="register_message_capture"> + <method name="_setup_session" qualifiers="virtual"> <return type="void" /> - <param index="0" name="name" type="StringName" /> - <param index="1" name="callable" type="Callable" /> + <param index="0" name="session_id" type="int" /> <description> - Registers a message capture with given [param name]. If [param name] is "my_message" then messages starting with "my_message:" will be called with the given callable. - Callable must accept a message string and a data array as argument. If the message and data are valid then callable must return [code]true[/code] otherwise [code]false[/code]. + Override this method to be notified whenever a new [EditorDebuggerSession] is created (the session may be inactive during this stage). </description> </method> - <method name="send_message"> - <return type="void" /> - <param index="0" name="message" type="String" /> - <param index="1" name="data" type="Array" /> + <method name="get_session"> + <return type="EditorDebuggerSession" /> + <param index="0" name="id" type="int" /> <description> - Sends a message with given [param message] and [param data] array. + Returns the [EditorDebuggerSession] with the given [param id]. </description> </method> - <method name="unregister_message_capture"> - <return type="void" /> - <param index="0" name="name" type="StringName" /> + <method name="get_sessions"> + <return type="Array" /> <description> - Unregisters the message capture with given name. + Returns an array of [EditorDebuggerSession] currently available to this debugger plugin. + Note: Not sessions in the array may be inactive, check their state via [method EditorDebuggerSession.is_active] </description> </method> </methods> - <signals> - <signal name="breaked"> - <param index="0" name="can_debug" type="bool" /> - <description> - Emitted when the game enters a break state. - </description> - </signal> - <signal name="continued"> - <description> - Emitted when the game exists a break state. - </description> - </signal> - <signal name="started"> - <description> - Emitted when the debugging starts. - </description> - </signal> - <signal name="stopped"> - <description> - Emitted when the debugging stops. - </description> - </signal> - </signals> </class> diff --git a/doc/classes/EditorDebuggerSession.xml b/doc/classes/EditorDebuggerSession.xml new file mode 100644 index 0000000000..faf528c143 --- /dev/null +++ b/doc/classes/EditorDebuggerSession.xml @@ -0,0 +1,86 @@ +<?xml version="1.0" encoding="UTF-8" ?> +<class name="EditorDebuggerSession" inherits="RefCounted" version="4.0" xmlns:xsi="http://www.w3.org/2001/XMLSchema-instance" xsi:noNamespaceSchemaLocation="../class.xsd"> + <brief_description> + A class to interact with the editor debugger. + </brief_description> + <description> + This class cannot be directly instantiated and must be retrieved via a [EditorDebuggerPlugin]. + You can add tabs to the session UI via [method add_session_tab], send messages via [method send_message], and toggle [EngineProfiler]s via [method toggle_profiler]. + </description> + <tutorials> + </tutorials> + <methods> + <method name="add_session_tab"> + <return type="void" /> + <param index="0" name="control" type="Control" /> + <description> + Adds the given [param control] to the debug session UI in the debugger bottom panel. + </description> + </method> + <method name="is_active"> + <return type="bool" /> + <description> + Returns [code]true[/code] if the debug session is currently attached to a remote instance. + </description> + </method> + <method name="is_breaked"> + <return type="bool" /> + <description> + Returns [code]true[/code] if the attached remote instance is currently in the debug loop. + </description> + </method> + <method name="is_debuggable"> + <return type="bool" /> + <description> + Returns [code]true[/code] if the attached remote instance can be debugged. + </description> + </method> + <method name="remove_session_tab"> + <return type="void" /> + <param index="0" name="control" type="Control" /> + <description> + Removes the given [param control] from the debug session UI in the debugger bottom panel. + </description> + </method> + <method name="send_message"> + <return type="void" /> + <param index="0" name="message" type="String" /> + <param index="1" name="data" type="Array" default="[]" /> + <description> + Sends the given [param message] to the attached remote instance, optionally passing additionally [param data]. See [EngineDebugger] for how to retrieve those messages. + </description> + </method> + <method name="toggle_profiler"> + <return type="void" /> + <param index="0" name="profiler" type="String" /> + <param index="1" name="enable" type="bool" /> + <param index="2" name="data" type="Array" default="[]" /> + <description> + Toggle the given [param profiler] on the attached remote instance, optionally passing additionally [param data]. See [EngineProfiler] for more details. + </description> + </method> + </methods> + <signals> + <signal name="breaked"> + <param index="0" name="can_debug" type="bool" /> + <description> + Emitted when the attached remote instance enters a break state. If [param can_debug] is [code]true[/code], the remote instance will enter the debug loop. + </description> + </signal> + <signal name="continued"> + <description> + Emitted when the attached remote instance exits a break state. + </description> + </signal> + <signal name="started"> + <description> + Emitted when a remote instance is attached to this session (i.e. the session becomes active). + </description> + </signal> + <signal name="stopped"> + <description> + Emitted when a remote instance is detached from this session (i.e. the session becomes inactive). + </description> + </signal> + </signals> +</class> diff --git a/doc/classes/EditorPlugin.xml b/doc/classes/EditorPlugin.xml index 2289a373bf..806588d100 100644 --- a/doc/classes/EditorPlugin.xml +++ b/doc/classes/EditorPlugin.xml @@ -415,7 +415,7 @@ </method> <method name="add_debugger_plugin"> <return type="void" /> - <param index="0" name="script" type="Script" /> + <param index="0" name="script" type="EditorDebuggerPlugin" /> <description> Adds a [Script] as debugger plugin to the Debugger. The script must extend [EditorDebuggerPlugin]. </description> @@ -599,7 +599,7 @@ </method> <method name="remove_debugger_plugin"> <return type="void" /> - <param index="0" name="script" type="Script" /> + <param index="0" name="script" type="EditorDebuggerPlugin" /> <description> Removes the debugger plugin with given script from the Debugger. </description> |