mirror of
https://github.com/godotengine/godot-docs-l10n.git
synced 2025-12-31 09:49:22 +03:00
346 lines
16 KiB
Plaintext
346 lines
16 KiB
Plaintext
# SOME DESCRIPTIVE TITLE.
|
|
# Copyright (C) 2014-present Juan Linietsky, Ariel Manzur and the Godot community (CC BY 3.0)
|
|
# This file is distributed under the same license as the Godot Engine package.
|
|
# FIRST AUTHOR <EMAIL@ADDRESS>, YEAR.
|
|
#
|
|
#, fuzzy
|
|
msgid ""
|
|
msgstr ""
|
|
"Project-Id-Version: Godot Engine latest\n"
|
|
"Report-Msgid-Bugs-To: \n"
|
|
"PO-Revision-Date: YEAR-MO-DA HO:MI+ZONE\n"
|
|
"Last-Translator: FULL NAME <EMAIL@ADDRESS>\n"
|
|
"Language-Team: LANGUAGE <LL@li.org>\n"
|
|
"MIME-Version: 1.0\n"
|
|
"Content-Type: text/plain; charset=UTF-8\n"
|
|
"Content-Transfer-Encoding: 8bit\n"
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:4
|
|
msgid "Object class"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:8
|
|
msgid "This page describes the C++ implementation of objects in Godot. Looking for the Object class reference? :ref:`Have a look here. <class_Object>`"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:12
|
|
msgid "General definition"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:14
|
|
msgid ":ref:`Object <class_object>` is the base class for almost everything. Most classes in Godot inherit directly or indirectly from it. Declaring them is a matter of using a single macro like this:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:24
|
|
msgid "Objects come with a lot of built-in functionality, like reflection and editable properties:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:34
|
|
#: ../../docs/engine_details/architecture/object_class.rst:112
|
|
#: ../../docs/engine_details/architecture/object_class.rst:324
|
|
#: ../../docs/engine_details/architecture/object_class.rst:362
|
|
#: ../../docs/engine_details/architecture/object_class.rst:383
|
|
#: ../../docs/engine_details/architecture/object_class.rst:402
|
|
msgid "References:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:36
|
|
msgid "`core/object/object.h <https://github.com/godotengine/godot/blob/master/core/object/object.h>`__"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:39
|
|
msgid "Registering Object classes"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:41
|
|
msgid "Most ``Object`` subclasses are registered by calling ``GDREGISTER_CLASS``."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:47
|
|
msgid "This will register it as a named, public class in the ``ClassDB``, which will allow the class to be instantiated by scripts, code, or by deserialization. Note that classes registered as ``GDREGISTER_CLASS`` should expect to be instantiated or freed automatically, for example by the editor or the documentation system."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:51
|
|
msgid "Besides ``GDREGISTER_CLASS``, there are a few other modes of privateness:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:71
|
|
msgid "It is also possible to use ``GDSOFTCLASS(MyCustomClass, SuperClass)`` instead of ``GDCLASS(MyCustomClass, SuperClass)``. Classes defined this way are not registered in the ``ClassDB`` at all. This is sometimes used for platform-specific subclasses."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:76
|
|
msgid "Registering bindings"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:78
|
|
msgid "Object-derived classes can override the static function ``static void _bind_methods()``. When the class is registered, this static function is called to register all the object methods, properties, constants, etc. It's only called once."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:83
|
|
msgid "Inside ``_bind_methods``, there are a couple of things that can be done. Registering functions is one:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:90
|
|
msgid "Default values for arguments can be passed as parameters at the end:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:96
|
|
msgid "Default values must be provided in the same order as they are declared, skipping required arguments and then providing default values for the optional ones. This matches the syntax for declaring methods in C++."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:100
|
|
msgid "``D_METHOD`` is a macro that converts \"methodname\" to a StringName for more efficiency. Argument names are used for introspection, but when compiling on release, the macro ignores them, so the strings are unused and optimized away."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:105
|
|
msgid "Check ``_bind_methods`` of Control or Object for more examples."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:107
|
|
msgid "If just adding modules and functionality that is not expected to be documented as thoroughly, the ``D_METHOD()`` macro can safely be ignored and a string passing the name can be passed for brevity."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:114
|
|
msgid "`core/object/class_db.h <https://github.com/godotengine/godot/blob/master/core/object/class_db.h>`__"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:117
|
|
msgid "Constants"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:119
|
|
msgid "Classes often have enums such as:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:128
|
|
msgid "For these to work when binding to methods, the enum must be declared convertible to int. A macro is provided to help with this:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:135
|
|
msgid "The constants can also be bound inside ``_bind_methods``, by using:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:143
|
|
msgid "Properties (set/get)"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:145
|
|
msgid "Objects export properties, properties are useful for the following:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:147
|
|
msgid "Serializing and deserializing the object."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:148
|
|
msgid "Creating a list of editable values for the Object derived class."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:150
|
|
msgid "Properties are usually defined by the PropertyInfo() class and constructed as:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:157
|
|
msgid "For example:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:163
|
|
msgid "This is an integer property named \"amount\". The hint is a range, and the range goes from 0 to 49 in steps of 1 (integers). It is only usable for the editor (editing the value visually) but won't be serialized."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:167
|
|
msgid "Another example:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:173
|
|
msgid "This is a string property, can take any string but the editor will only allow the defined hint ones. Since no usage flags were specified, the default ones are PROPERTY_USAGE_STORAGE and PROPERTY_USAGE_EDITOR."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:177
|
|
msgid "There are plenty of hints and usage flags available in object.h, give them a check."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:180
|
|
msgid "Properties can also work like C# properties and be accessed from script using indexing, but this usage is generally discouraged, as using functions is preferred for legibility. Many properties are also bound with categories, such as \"animation/frame\" which also make indexing impossible unless using operator []."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:186
|
|
msgid "From ``_bind_methods()``, properties can be created and bound as long as set/get functions exist. Example:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:193
|
|
msgid "This creates the property using the setter and the getter."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:198
|
|
msgid "Binding properties using ``_set``/``_get``/``_get_property_list``"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:200
|
|
msgid "An additional method of creating properties exists when more flexibility is desired (i.e. adding or removing properties on context)."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:203
|
|
msgid "The following functions can be overridden in an Object derived class, they are NOT virtual, DO NOT make them virtual, they are called for every override and the previous ones are not invalidated (multilevel call)."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:215
|
|
msgid "This is also a little less efficient since ``p_property`` must be compared against the desired names in serial order."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:220
|
|
msgid "Signals"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:222
|
|
msgid "Objects can have a set of signals defined (similar to Delegates in other languages). This example shows how to connect to them:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:234
|
|
msgid "``callable_mp`` is a macro to create a custom callable function pointer to member functions. For the values of ``p_flags``, see :ref:`ConnectFlags <enum_Object_ConnectFlags>`."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:237
|
|
msgid "Adding signals to a class is done in ``_bind_methods``, using the ``ADD_SIGNAL`` macro, for example:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:245
|
|
msgid "Object ownership and casting"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:247
|
|
msgid "Objects are allocated on the heap. There are two different ownership models:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:249
|
|
msgid "Objects derived from ``RefCounted`` are reference counted."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:250
|
|
msgid "All other objects are manually memory managed."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:252
|
|
msgid "The ownership models are fundamentally different. Refer to the section for each respectively to learn how to create, store, and free the object."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:255
|
|
msgid "When you do not know whether an object passed to you (via ``Object *``) is ``RefCounted``, and you need to store it, you should store its ``ObjectID`` rather than a pointer (as explained below, in the manual memory management section)."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:258
|
|
msgid "When an object is passed to you via :ref:`Variant<class_Variant>`, especially when using deferred callbacks, it is possible that the contained ``Object *`` was already freed by the time your function runs. Instead of converting directly to ``Object *``, you should use ``get_validated_object``:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:270
|
|
msgid "Manual memory management"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:272
|
|
msgid "Manually memory managed objects are created using ``memnew`` and freed using ``memdelete``:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:281
|
|
msgid "When you are not the sole owner of an object, storing a pointer to it is dangerous: The object may at any point be freed through other references to it, causing your pointer to become a dangling pointer, which will eventually result in a crash."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:285
|
|
msgid "When storing objects you are not the only owner of, you should store its ``ObjectID`` rather than a pointer:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:296
|
|
msgid "``RefCounted`` memory management"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:298
|
|
msgid ":ref:`RefCounted <class_RefCounted>` subclasses are memory managed with `reference counting semantics <https://en.wikipedia.org/wiki/Reference_counting>`__."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:301
|
|
msgid "They are constructed using ``memnew``, and should be stored in ``Ref`` instances. When the last ``Ref`` instance is dropped, the object automatically self-destructs."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:317
|
|
msgid "You should never call ``memdelete`` for ``RefCounted`` subclasses, because there may be other owners of it."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:319
|
|
msgid "You should also never store ``RefCounted`` subclasses using raw pointers, for example ``RefCounted *object = memnew(RefCounted)``. This is unsafe because other owners may destruct the object, leaving you with a dangling pointer, which will eventually result in a crash."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:326
|
|
msgid "`core/object/ref_counted.h <https://github.com/godotengine/godot/blob/master/core/object/ref_counted.h>`__"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:329
|
|
msgid "Dynamic casting"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:331
|
|
msgid "Godot provides dynamic casting between Object-derived classes, for example:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:339
|
|
msgid "If the cast fails, ``nullptr`` is returned. This works the same as ``dynamic_cast``, but does not use `C++ RTTI <https://en.wikipedia.org/wiki/Run-time_type_information>`__."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:343
|
|
msgid "Notifications"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:345
|
|
msgid "All objects in Godot have a :ref:`_notification <class_Object_private_method__notification>` method that allows them to respond to engine-level callbacks that may relate to it. More information can be found on the :ref:`doc_godot_notifications` page."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:351
|
|
msgid "Resources"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:353
|
|
msgid ":ref:`Resource <class_resource>` inherits from RefCounted, so all resources are reference counted. Resources can optionally contain a path, which reference a file on disk. This can be set with ``resource.set_path(path)``, though this is normally done by the resource loader. No two different resources can have the same path; attempting to do so will result in an error."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:359
|
|
msgid "Resources without a path are fine too."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:364
|
|
msgid "`core/io/resource.h <https://github.com/godotengine/godot/blob/master/core/io/resource.h>`__"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:367
|
|
msgid "Resource loading"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:369
|
|
msgid "Resources can be loaded with the ResourceLoader API, like this:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:375
|
|
msgid "If a reference to that resource has been loaded previously and is in memory, the resource loader will return that reference. This means that there can be only one resource loaded from a file referenced on disk at the same time."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:380
|
|
msgid "resourceinteractiveloader (TODO)"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:385
|
|
msgid "`core/io/resource_loader.h <https://github.com/godotengine/godot/blob/master/core/io/resource_loader.h>`__"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:388
|
|
msgid "Resource saving"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:390
|
|
msgid "Saving a resource can be done with the resource saver API:"
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:396
|
|
msgid "The instance will be saved, and sub resources that have a path to a file will be saved as a reference to that resource. Sub resources without a path will be bundled with the saved resource and assigned sub-IDs, like ``res://someresource.res::1``. This also helps to cache them when loaded."
|
|
msgstr ""
|
|
|
|
#: ../../docs/engine_details/architecture/object_class.rst:404
|
|
msgid "`core/io/resource_saver.h <https://github.com/godotengine/godot/blob/master/core/io/resource_saver.h>`__"
|
|
msgstr ""
|