| .. _bind-h: |
| |
| =========================== |
| bind.h (under-construction) |
| =========================== |
| |
| The C++ APIs in `bind.h <https://github.com/emscripten-core/emscripten/blob/main/system/include/emscripten/bind.h>`_ define |
| |
| Guide documentation for this API can be found in :ref:`Embind`. |
| |
| .. contents:: Table of Contents |
| :local: |
| :depth: 1 |
| |
| How to use this API |
| =================== |
| |
| |
| Defines |
| ------- |
| |
| |
| .. cpp:namespace: emscripten |
| |
| .. cpp:function:: EMSCRIPTEN_BINDINGS(name) |
| |
| This define is used to bind C++ classes, functions and other constructs to |
| JavaScript. It is used differently depending on the construct being mapped |
| — see the :ref:`embind guide <embind>` for examples. |
| |
| :param name: This is a label to mark a group of related bindings (for example ``EMSCRIPTEN_BINDINGS(physics)``, ``EMSCRIPTEN_BINDINGS(components)``, etc.) |
| |
| |
| |
| .. cpp:type:: sharing_policy |
| |
| .. cpp:type:: sharing_policy::NONE |
| |
| .. cpp:type:: sharing_policy::INTRUSIVE |
| |
| .. cpp:type:: sharing_policy::BY_EMVAL |
| |
| |
| .. _bind-h-policies: |
| |
| Policies |
| ======== |
| |
| Currently only :cpp:type:`allow_raw_pointers` policy is supported. |
| Eventually we hope to implement `Boost.Python-like raw pointer policies |
| <https://wiki.python.org/moin/boost.python/CallPolicy>`_ for managing |
| object ownership. |
| |
| .. cpp:type:: arg |
| |
| .. cpp:member:: static int index |
| |
| .. code-block:: cpp |
| |
| // Prototype |
| static constexpr int index |
| |
| |
| .. cpp:type:: ret_val |
| |
| .. cpp:member:: static int index |
| |
| .. code-block:: cpp |
| |
| // Prototype |
| static constexpr int index |
| |
| |
| .. cpp:type:: allow_raw_pointers |
| |
| This policy is used to allow raw pointers. |
| |
| .. cpp:type:: Transform::type |
| |
| |
| .. cpp:type:: allow_raw_pointer |
| |
| .. code-block: cpp |
| |
| // Prototype |
| template<typename Slot> |
| struct allow_raw_pointer : public allow_raw_pointers |
| |
| |
| select_overload and select_const |
| ====================================== |
| |
| |
| .. cpp:function:: typename std::add_pointer<Signature>::type select_overload(typename std::add_pointer<Signature>::type fn) |
| |
| .. code-block:: cpp |
| |
| // Prototype |
| template<typename Signature> |
| typename std::add_pointer<Signature>::type select_overload(typename std::add_pointer<Signature>::type fn) |
| |
| :param typename std\:\:add_pointer<Signature>::type fn: |
| |
| .. cpp:function:: typename internal::MemberFunctionType<ClassType, Signature>::type select_overload() |
| |
| .. code-block:: cpp |
| |
| // Prototype |
| template<typename Signature, typename ClassType> |
| typename internal::MemberFunctionType<ClassType, Signature>::type select_overload(Signature (ClassType::*fn)) |
| |
| :param Signature (ClassType::\*fn): |
| |
| .. cpp:function:: auto select_const() |
| |
| .. code-block:: cpp |
| |
| // Prototype |
| template<typename ClassType, typename ReturnType, typename... Args> |
| auto select_const(ReturnType (ClassType::*method)(Args...) const) |
| |
| :param ReturnType (ClassType::\*method)(Args...) const: |
| |
| |
| .. cpp:function:: typename internal::CalculateLambdaSignature<LambdaType>::type optional_override(const LambdaType& fp) |
| |
| .. code-block:: cpp |
| |
| // Prototype |
| template<typename LambdaType> |
| typename internal::CalculateLambdaSignature<LambdaType>::type optional_override(const LambdaType& fp) |
| |
| :param const LambdaType& fp: |
| |
| |
| Functions |
| ========= |
| |
| .. cpp:function:: void function() |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename ReturnType, typename... Args, typename... Policies> |
| void function(const char* name, ReturnType (*fn)(Args...), Policies...) |
| |
| Registers a function to export to JavaScript. This is called from within |
| an :cpp:func:`EMSCRIPTEN_BINDINGS` block. |
| |
| For example to export the function ``lerp()`` |
| |
| .. code:: cpp |
| |
| // quick_example.cpp |
| #include <emscripten/bind.h> |
| |
| using namespace emscripten; |
| |
| float lerp(float a, float b, float t) { |
| return (1 - t) * a + t * b; |
| } |
| |
| EMSCRIPTEN_BINDINGS(my_module) { |
| function("lerp", &lerp); |
| } |
| |
| |
| |
| :param const char* name: The name of the function to export (e.g. ``"lerp"``). |
| :param ReturnType (\*fn)(Args...): Function pointer address for the exported function (e.g. ``&lerp``). |
| :param Policies...: |policies-argument| |
| |
| |
| |
| Value tuples |
| ============== |
| |
| .. cpp:class:: value_array : public internal::noncopyable |
| |
| .. cpp:type:: class_type |
| |
| A typedef of ``ClassType``, the typename of the templated type for the class. |
| |
| |
| .. cpp:function:: value_array(const char* name) |
| |
| Constructor. |
| |
| :param const char* name: |
| |
| |
| .. cpp:function:: ~value_array() |
| |
| Destructor. |
| |
| |
| .. cpp:function:: value_array& element(ElementType InstanceType::*field) |
| |
| :param ElementType InstanceType::\*field: Note that ``ElementType`` and ``InstanceType`` are typenames (templated types). |
| |
| |
| .. cpp:function:: value_array& element(Getter getter, Setter setter) |
| |
| :param Getter getter: Note that ``Getter`` is a typename (templated type). |
| :param Setter setter: Note that ``Setter`` is a typename (templated type). |
| |
| |
| .. cpp:function:: value_array& element(index<Index>) |
| |
| :param index<Index>: Note that ``Index`` is an integer template parameter. |
| |
| |
| |
| |
| |
| Value structs |
| ============= |
| |
| .. cpp:class:: value_object : public internal::noncopyable |
| |
| .. cpp:type:: class_type |
| |
| A typedef of ``ClassType``, the typename of the templated type for the class. |
| |
| |
| .. cpp:function:: value_object(const char* name) |
| |
| Constructor. |
| |
| :param const char* name: |
| |
| |
| .. cpp:function:: ~value_object() |
| |
| Destructor. |
| |
| |
| .. cpp:function:: value_object& field(const char* fieldName, FieldType InstanceType::*field) |
| |
| :param const char* fieldName: |
| :param FieldType InstanceType\:\:\*field: |
| |
| |
| |
| .. cpp:function:: value_object& field(const char* fieldName, Getter getter, Setter setter) |
| |
| :param const char* fieldName: |
| :param Getter getter: Note that ``Getter`` is a typename (templated type). |
| :param Setter setter: Note that ``Setter`` is a typename (templated type). |
| |
| |
| .. cpp:function:: value_object& field(const char* fieldName, index<Index>) |
| |
| :param const char* fieldName: |
| :param index<Index>: Note that ``Index`` is an integer template parameter. |
| |
| |
| Smart pointers |
| ============== |
| |
| |
| .. cpp:type:: default_smart_ptr_trait |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename PointerType> |
| struct default_smart_ptr_trait |
| |
| .. cpp:function:: static sharing_policy get_sharing_policy() |
| |
| |
| .. cpp:function:: static void* share(void* v) |
| |
| :param void* v: |
| |
| |
| .. cpp:function:: static PointerType* construct_null() |
| |
| :returns: Note that the ``PointerType`` returned is a typename (templated type). |
| |
| |
| |
| .. cpp:type:: smart_ptr_trait |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename PointerType> |
| struct smart_ptr_trait : public default_smart_ptr_trait<PointerType> |
| |
| .. cpp:type:: PointerType::element_type element_type |
| |
| .. code-block:: cpp |
| |
| //prototype |
| typedef typename PointerType::element_type element_type; |
| |
| |
| A typedef for the PointerType::element_type, where ``PointerType`` is a typename (templated type). |
| |
| |
| .. cpp:function:: static element_type* get(const PointerType& ptr) |
| |
| :param const PointerType& ptr: Note that ``PointerType`` is a typename (templated type) |
| |
| |
| |
| .. cpp:type:: template<typename PointeeType> smart_ptr_trait<std::shared_ptr<PointeeType>> |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename PointeeType> |
| struct smart_ptr_trait<std::shared_ptr<PointeeType>> |
| |
| .. cpp:type:: PointerType |
| |
| A typedef to std::shared_ptr<PointeeType>, where ``PointeeType`` is a typename (templated type). |
| |
| .. cpp:type:: element_type |
| |
| A typedef for the ``PointerType::element_type``. |
| |
| |
| .. cpp:function:: static element_type* get(const PointerType& ptr) |
| |
| :param const PointerType& ptr: |
| |
| .. cpp:function:: static sharing_policy get_sharing_policy() |
| |
| |
| .. cpp:function:: static std::shared_ptr<PointeeType>* share(PointeeType* p, EM_VAL v) |
| |
| :param PointeeType* p: Note that ``PointeeType`` is a typename (templated type). |
| :param EM_VAL v: |
| |
| |
| .. cpp:function:: static PointerType* construct_null() |
| |
| |
| |
| Classes |
| ======= |
| |
| |
| .. cpp:class:: wrapper : public T, public internal::WrapperBase |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename T> |
| class wrapper : public T, public internal::WrapperBase |
| |
| .. cpp:type:: class_type |
| |
| A typedef of ``T``, the typename of the templated type for the class. |
| |
| |
| .. cpp:function:: wrapper(val&& wrapped, Args&&... args) |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename... Args> |
| explicit wrapper(val&& wrapped, Args&&... args) |
| : T(std::forward<Args>(args)...) |
| , wrapped(std::forward<val>(wrapped)) |
| |
| Constructor. |
| |
| :param val&& wrapped: |
| :param Args&&... args: Note that ``Args`` is a typename (templated type). |
| |
| |
| .. cpp:function:: ~wrapper() |
| |
| Destructor. |
| |
| |
| .. cpp:function:: ReturnType call(const char* name, Args&&... args) const |
| |
| Constructor. |
| |
| :param const char* name: |
| :param Args&&... args: Note that ``Args`` is a typename (templated type). |
| :returns: Note that ``ReturnType`` is a typename (templated type). |
| |
| |
| .. cpp:function:: EMSCRIPTEN_WRAPPER(T) |
| |
| :param T: |
| |
| |
| .. cpp:type:: base |
| |
| .. cpp:type:: class_type |
| |
| A typedef of ``BaseClass``, the typename of the templated type for the class. |
| |
| |
| .. cpp:function:: static void verify() |
| |
| Note, is templated function which takes typename ``ClassType``. |
| |
| |
| .. cpp:function:: static internal::TYPEID get() |
| |
| |
| .. code-block:: cpp |
| |
| template<typename ClassType> |
| using Upcaster = BaseClass* (*)(ClassType*); |
| |
| template<typename ClassType> |
| using Downcaster = ClassType* (*)(BaseClass*); |
| |
| |
| .. cpp:function:: static Upcaster<ClassType> getUpcaster() |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename ClassType> |
| static Upcaster<ClassType> getUpcaster() |
| |
| |
| .. cpp:function:: static Downcaster<ClassType> getDowncaster() |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename ClassType> |
| static Downcaster<ClassType> getDowncaster() |
| |
| |
| .. cpp:function:: static To* convertPointer(From* ptr) |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename From, typename To> |
| static To* convertPointer(From* ptr) |
| |
| :param From* ptr: |
| |
| |
| |
| .. cpp:type:: pure_virtual |
| |
| .. cpp:type:: Transform |
| |
| Note that this is a templated struct taking typename parameter ``InputType`` and integer ``Index``. |
| |
| .. cpp:type:: type |
| |
| This is a typedef to the parent struct typename parameter ``InputType``. |
| |
| |
| .. cpp:type:: constructor |
| |
| Note that this is a template struct taking typename ``... ConstructorArgs``. |
| |
| |
| |
| .. cpp:class:: class_ |
| |
| Note that this is a templated class with typename parameters ``ClassType`` and ``BaseSpecifier``. |
| |
| .. cpp:type:: class_type |
| |
| A typedef of ``ClassType`` (a typename for the class). |
| |
| |
| .. cpp:type:: base_specifier |
| |
| A typedef of ``BaseSpecifier`` (a typename for the class). |
| |
| |
| .. cpp:type:: HELPNEEDEDHERE |
| |
| :: |
| |
| class_() = delete; |
| |
| |
| .. cpp:function:: explicit class_(const char* name) |
| |
| .. code-block:: cpp |
| |
| //prototype |
| EMSCRIPTEN_ALWAYS_INLINE explicit class_(const char* name) |
| |
| |
| Constructor. |
| |
| :param const char* name: |
| |
| |
| .. cpp:function:: const class_& smart_ptr(const char* name) const |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename PointerType> |
| EMSCRIPTEN_ALWAYS_INLINE const class_& smart_ptr(const char* name) const |
| |
| :param const char* name: |
| :returns: |class_-function-returns| |
| |
| |
| .. _embind-class-zero-argument-constructor: |
| |
| .. cpp:function:: const class_& constructor() const |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename... ConstructorArgs, typename... Policies> |
| EMSCRIPTEN_ALWAYS_INLINE const class_& constructor(Policies... policies) const |
| |
| Zero-argument form of the class constructor. This invokes the natural constructor with the arguments specified in the template. See :ref:`embind-external-constructors` for more information. |
| |
| :param Policies... policies: |policies-argument| |
| :returns: |class_-function-returns| |
| |
| .. _embind-class-function-pointer-constructor: |
| |
| |
| .. cpp:function:: const class_& constructor(Callable callable, Policies...) const |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename Signature = internal::DeduceArgumentsTag, typename Callable, typename... Policies> |
| EMSCRIPTEN_ALWAYS_INLINE const class_& constructor(Callable callable, Policies...) const |
| |
| Class constructor for objects that use a factory function to create the object. This method will accept either a function pointer, ``std::function`` |
| object or function object which will return a newly constructed object. When the ``Callable`` is a function object the function signature must be |
| explicitly specified in the ``Signature`` template parameter in the format ``ReturnType (Args...)``. For ``Callable`` types other than function objects |
| the method signature will be deduced. |
| |
| The following are all valid calls to ``constructor``: |
| |
| .. code-block:: cpp |
| |
| using namespace std::placeholders; |
| myClass1.constructor(&my_factory); |
| myClass2.constructor(std::function<ClassType2(float, float)>(&class2_factory)); |
| myClass3.constructor<ClassType3(const val&)>(std::bind(Class3Functor(), _1)); |
| |
| See :ref:`embind-external-constructors` for more information. |
| |
| |
| :param Callable callable: Note that ``Callable`` may be either a member function pointer, function pointer, ``std::function`` or function object. |
| :param Policies... policies: |policies-argument| |
| :returns: |class_-function-returns| |
| |
| |
| .. cpp:function:: const class_& smart_ptr_constructor() const |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename SmartPtr, typename... Args, typename... Policies> |
| EMSCRIPTEN_ALWAYS_INLINE const class_& smart_ptr_constructor(const char* smartPtrName, SmartPtr (*factory)(Args...), Policies...) const |
| |
| :param const char* smartPtrName: |
| :param SmartPtr (\*factory)(Args...): |
| :param Policies... policies: |policies-argument| |
| :returns: |class_-function-returns| |
| |
| |
| .. cpp:function:: const class_& allow_subclass() const |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename WrapperType, typename PointerType, typename... ConstructorArgs> |
| EMSCRIPTEN_ALWAYS_INLINE const class_& allow_subclass( |
| const char* wrapperClassName, |
| const char* pointerName, |
| ::emscripten::constructor<ConstructorArgs...> = ::emscripten::constructor<>() |
| ) const |
| |
| :param const char* wrapperClassName: |
| :param const char* pointerName: |
| :param emscripten\:\:constructor<ConstructorArgs...> constructor): |
| :returns: |class_-function-returns| |
| |
| |
| .. cpp:function:: const class_& allow_subclass(const char* wrapperClassName, ::emscripten::constructor<ConstructorArgs...> constructor) const |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename WrapperType, typename... ConstructorArgs> |
| EMSCRIPTEN_ALWAYS_INLINE const class_& allow_subclass( |
| const char* wrapperClassName, |
| ::emscripten::constructor<ConstructorArgs...> constructor = ::emscripten::constructor<>() |
| ) const |
| |
| :param const char* wrapperClassName: |
| :param \:\:emscripten\:\:constructor<ConstructorArgs...> constructor): |
| |
| :returns: |class_-function-returns| |
| |
| |
| .. cpp:function:: const class_& function() const |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename Signature = internal::DeduceArgumentsTag, typename Callable, typename... Policies> |
| EMSCRIPTEN_ALWAYS_INLINE const class_& function(const char* methodName, Callable callable, Policies...) const |
| |
| This method is for declaring a method belonging to a class. |
| |
| On the JavaScript side this is a function that gets bound as a property of the prototype. For example ``.function("myClassMember", &MyClass::myClassMember)`` |
| would bind ``myClassMember`` to ``MyClass.prototype.myClassMember`` in the JavaScript. This method will accept either a pointer-to-member-function, function |
| pointer, ``std::function`` object or function object. When the ``Callable`` is not a pointer-to-member-function it must accept the ``ClassType`` as the first |
| (``this``) parameter. When the ``Callable`` is a function object the function signature must be explicitly specified in the ``Signature`` template parameter |
| in the format ``ReturnType (Args...)``. For ``Callable`` types other than function objects the method signature will be deduced. |
| |
| A method name specified in the human-readable well-known symbol format (e.g., ``@@iterator``) |
| is bound using the named ``Symbol`` for JavaScript (e.g., ``Symbol.iterator``). |
| |
| The following are all valid calls to ``function``: |
| |
| .. code-block:: cpp |
| |
| using namespace std::placeholders; |
| myClass.function("myClassMember", &MyClass::myClassMember) |
| .function("myFreeFunction", &my_free_function) |
| .function("myStdFunction", std::function<float(ClassType&, float, float)>(&my_function)) |
| .function<val(const MyClass&)>("myFunctor", std::bind(&my_functor_taking_this, _1)); |
| |
| |
| :param const char* methodName: |
| :param Callable callable: Note that ``Callable`` may be either a member function pointer, function pointer, ``std::function`` or function object. |
| :param typename... Policies: |policies-argument| |
| :returns: |class_-function-returns| |
| |
| .. cpp:function:: const class_& iterable() const |
| |
| .. code-block:: cpp |
| |
| // prototype |
| template<typename ElementType> |
| EMSCRIPTEN_ALWAYS_INLINE const class_& iterable(const char* sizeMethodName, const char* getMethodName) const |
| |
| Makes a bound class iterable in JavaScript by installing ``Symbol.iterator``. |
| This enables use with ``for...of`` loops, ``Array.from()``, and spread syntax. |
| |
| :tparam ElementType: The type of elements yielded by the iterator. |
| |
| :param sizeMethodName: Name of the bound method that returns the number of elements. |
| |
| :param getMethodName: Name of the bound method that retrieves an element by index. |
| |
| :returns: |class_-function-returns| |
| |
| .. code-block:: cpp |
| |
| class_<MyContainer>("MyContainer") |
| .function("size", &MyContainer::size) |
| .function("get", &MyContainer::get) |
| .iterable<int>("size", "get"); |
| |
| .. code-block:: javascript |
| |
| const container = new Module.MyContainer(); |
| for (const item of container) { /* ... */ } |
| const arr = Array.from(container); |
| |
| |
| .. cpp:function:: const class_& property() const |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename FieldType, typename = typename std::enable_if<!std::is_function<FieldType>::value>::type> |
| EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, const FieldType ClassType::*field) const |
| |
| :param const char* fieldName: |
| :param const FieldType ClassType\:\:\*field: |
| |
| :returns: |class_-function-returns| |
| |
| |
| .. cpp:function:: const class_& property(const char* fieldName, FieldType ClassType::*field) const |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename FieldType, typename = typename std::enable_if<!std::is_function<FieldType>::value>::type> |
| EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, FieldType ClassType::*field) const |
| |
| :param const char* fieldName: |
| :param FieldType ClassType\:\:\*field: |
| |
| :returns: |class_-function-returns| |
| |
| |
| .. cpp:function:: const class_& property(const char* fieldName, Getter getter) const |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename PropertyType = internal::DeduceArgumentsTag, typename Getter> |
| EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, Getter getter) const; |
| |
| Declare a read-only property with the specified ``fieldName`` on the class using the specified ``getter`` to retrieve the property |
| value. ``Getter`` may be either a class method, a function, a ``std::function`` or a function object. When ``Getter`` |
| is not pointer-to-member-function, it must accept an instance of the ``ClassType`` as the ``this`` argument. When |
| ``Getter`` is a function object, the property type must be specified as a template parameter as it cannot be deduced, |
| e.g.: ``myClass.property<int>("myIntProperty", MyIntGetterFunctor());`` |
| |
| :param const char* fieldName: |
| :param Getter getter: Note that ``Getter`` is a function template typename. |
| :returns: |class_-function-returns| |
| |
| |
| .. cpp:function:: const class_& property(const char* fieldName, Getter getter, Setter setter) const |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename PropertyType = internal::DeduceArgumentsTag, typename Getter, typename Setter> |
| EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, Getter getter, Setter setter) const |
| |
| This is a function template taking typenames ``Setter`` and ``Getter``: ``template<typename Getter, typename Setter>`` |
| which declares a read-write property with the specified ``fieldName`` on the class. ``Getter`` and ``Setter`` may be either a |
| class method, a function, a ``std::function`` or a function object. When ``Getter`` or ``Setter`` is not pointer-to-member-function, |
| it must accept an instance of the ``ClassType`` as the ``this`` argument. When ``Getter`` or ``Setter`` is a function object, the |
| property type must be specified as a template parameter as it cannot be deduced, e.g.: |
| ``myClass.property<int>("myIntProperty", MyIntGetterFunctor(), MyIntSetterFunctor());`` |
| |
| :param const char* fieldName: |
| :param Getter getter: Note that ``Getter`` is a function template typename. |
| :param Setter setter: Note that ``Setter`` is a function template typename. |
| :returns: |class_-function-returns| |
| |
| .. cpp:function:: const class_& class_function() const |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename ReturnType, typename... Args, typename... Policies> |
| EMSCRIPTEN_ALWAYS_INLINE const class_& class_function(const char* methodName, ReturnType (*classMethod)(Args...), Policies...) const |
| |
| This method is for declaring a static function belonging to a class. |
| |
| On the JavaScript side this is a function that gets bound as a property |
| of the constructor. For example ``.class_function("myStaticFunction", |
| &MyClass::myStaticFunction)`` binds ``myStaticFunction`` to |
| ``MyClass.myStaticFunction``. |
| |
| A method name specified in the human-readable well-known symbol format (e.g., ``@@species``) |
| is bound using the named ``Symbol`` for JavaScript (e.g., ``Symbol.species``). |
| |
| :param const char* methodName: |
| :param ReturnType (\*classMethod)(Args...): |
| :param Policies...: |policies-argument| |
| :returns: |class_-function-returns| |
| |
| .. cpp:function:: const class_& class_property(const char* fieldName, FieldType *field) const |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename FieldType> |
| EMSCRIPTEN_ALWAYS_INLINE const class_& property(const char* fieldName, FieldType *field) const |
| |
| :param const char* fieldName: |
| :param FieldType ClassType\:\:\*field: |
| |
| :returns: |class_-function-returns| |
| |
| |
| |
| |
| |
| Vectors |
| ======= |
| |
| .. cpp:function:: class_<std::vector<T>> register_vector(const char* name) |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename T> |
| class_<std::vector<T>> register_vector(const char* name) |
| |
| A function to register a ``std::vector<T>``. |
| |
| :param const char* name: |
| |
| |
| Maps |
| ==== |
| |
| .. cpp:function:: class_<std::map<K, V>> register_map(const char* name) |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename K, typename V> |
| class_<std::map<K, V>> register_map(const char* name) |
| |
| A function to register a ``std::map<K, V>``. |
| |
| :param const char* name: |
| |
| |
| |
| Enums |
| ===== |
| |
| |
| .. cpp:class:: enum_ |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename EnumType> |
| class enum_ |
| |
| Registers an enum to export to JavaScript. This is called from within an |
| :cpp:func:`EMSCRIPTEN_BINDINGS` block and works with both C++98 enums |
| and C++11 "enum classes". See :ref:`embind-enums` for more information. |
| |
| |
| .. cpp:type:: enum_type |
| |
| A typedef of ``EnumType`` (a typename for the class). |
| |
| |
| .. cpp:function:: enum_(const char* name, enum_value_type valueType = enum_value_type::object) |
| |
| Constructor. |
| |
| :param const char* name: Name of the enum in JavaScript. |
| :param enum_value_type valueType: |
| Determines how the enumerated values are represented in JavaScript. |
| |
| Possible values: |
| |
| - ``enum_value_type::object`` (default): |
| Values are JavaScript objects with a ``.value`` field. |
| |
| - ``enum_value_type::number``: |
| Values are plain numbers matching their corresponding C++ values. |
| |
| - ``enum_value_type::string``: |
| Values are strings containing their name. |
| |
| .. cpp:function:: enum_& value(const char* name, EnumType value) |
| |
| Registers an enum value. |
| |
| :param const char* name: The name of the enumerated value. |
| :param EnumType value: The enumerated value. |
| :returns: A reference to the current object. This allows chaining of |
| multiple enum values in the :cpp:func:`EMSCRIPTEN_BINDINGS` |
| block. |
| |
| |
| |
| Constants |
| ========= |
| |
| .. cpp:function:: void constant(const char* name, const ConstantType& v) |
| |
| .. code-block:: cpp |
| |
| //prototype |
| template<typename ConstantType> |
| void constant(const char* name, const ConstantType& v) |
| |
| Registers a constant to export to JavaScript. This is called from within |
| an :cpp:func:`EMSCRIPTEN_BINDINGS` block. |
| |
| .. code:: cpp |
| |
| EMSCRIPTEN_BINDINGS(my_constant_example) { |
| constant("SOME_CONSTANT", SOME_CONSTANT); |
| } |
| |
| :param const char* name: The name of the constant. |
| :param const ConstantType& v: The constant type. This can be any type known to *embind*. |
| |
| |
| |
| |
| |
| .. COMMENT (not rendered): Following values are common to many functions, and currently only updated in one place (here). |
| .. COMMENT (not rendered): These can be properly replaced if required either wholesale or on an individual basis. |
| |
| .. |policies-argument| replace:: :ref:`Policy <bind-h-policies>` for managing raw pointer object ownership. Currently must be :cpp:type:`allow_raw_pointers`. |
| .. |class_-function-returns| replace:: A ``const`` reference to the current object. This allows chaining of the :cpp:class:`class_` functions that define the binding in the :cpp:func:`EMSCRIPTEN_BINDINGS` block. |
