Coherent GT allows for easy communication between your application and the UI via several mechanisms - this document outlines the simplemost option based on message passing. This option requires writing some amount of JS. If you'd rather not write JS, see Data Binding.
First the JavaScript code has to attach a handler for the event using engine.on
:
Then we trigger the event in C++, using the Coherent::UIGT::View::TriggerEvent method:
There are also global functions in the Coherent::UIGT namespace which can be used such as:
Coherent::UIGT::TriggerEvent(view, 'ScoreChanged', 10000);
Every TriggerEvent
call starts with a C++ macro:
By default this macro does nothing and is compiled out. You can, however, add custom code there by defining COHERENTGT_TRIGGER_EVENT_SCOPE
before it's used in View.h
. For example, you can add some profiling code such as:
Note that in order for the binding to work you need to include the coherent.js library in the head section of your HTML page.
engine
, see JavaScript .Registering C++ functions for events triggered by JavaScript should happen in the handler of the Coherent::UIGT::ViewListener::OnReadyForBindings event.
Event handlers are registered with the Coherent::UIGT::View::RegisterForEvent method. They cannot return any value to JavaScript, but may trigger an event for JavaScript. There may be more than one C++ handler for a given event. There also may be both C++ and JavaScript handlers for the same event.
Triggering the event from JavaScript looks like:
Coherent::UIGT::MakeHandler
uses template argument deduction to guess the signature of the handler. This requires several specializations of Coherent::UIGT::FunctorTraits
and overloads of Coherent::UIGT::EventHandler::InvokeStub. To extend the number of arguments for event handlers supported by Coherent GT, you have to add additional specializations and overloads.
Call handlers are registered with the Coherent::UIGT::View::BindCall method. There may be only one handler for a given call and the handler may return a result.
To get the player name in the view is:
To be able to use your C++ types as arguments or results for event and call handlers, the C++ type must be exposed to Coherent GT. To expose a C++ type to Coherent GT use the following pattern:
The CoherentBind
overload must be visible in all places where a Player
instance is exposed to JavaScript, i.e. in any of the following cases:
Player
instance is used as an argument to TriggerEvent
Player
as an argumentPlayer
to JavaScriptIn case the CoherentBind
overload for the Player
class is not visible, you will get the following compilation error:
include\coherent\uigt\binding\binding.h(57): error C2338: Coherent::UIGT::Overload_CoherentBind_For_Your_Type<T*> 1> include\coherent\uigt\binding\binding.h(191) : see reference to function template instantiation 'void CoherentBind<T>(Coherent::UIGT::Binder *,T *)' being compiled 1> with 1> [ 1> T=Player 1> ]
Going down the template instantiation stack, you can find where you are using Player
without the CoherentBind
overload visible.
You can define the CoherentBind
overload for Player
in any C++ source (.cpp) file, but you'll need to have a declaration for it, that is included everywhere Player
is exposed to Coherent GT.
Depending on the structure of your project, you may consider the following patterns:
Player
is dedicated only for the UI - then add the declaration of CoherentBind for Player
in the Player
header. This way the overload will be visible everywhere Player
is visible.Player
is generic game type - add a PlayerBinding.h or a MySubsystemBindings.h header with the declaration of CoherentBind for Player
(or for all the types in the particular game subsystem). After that make sure to include the header where Player
is used with Coherent GT.CoherentBind
overload for Player
has to be either in the namespace of Player
or in the Coherent::UIGT
namespace. This way it will be found using argument dependent lookup.Coherent GT has built-in support for most STL containers and std::
classes.
C++ Type | JavaScript Type | Header |
---|---|---|
std::string | String | <Coherent\UIGT\Binding\String.h> |
std::vector | Array | <Coherent\UIGT\Binding\Vector.h> |
std::map | Object | <Coherent\UIGT\Binding\Map.h> |
std::pair | Object | <Coherent\UIGT\Binding\Pair.h> |
C style array | Array | <Coherent\UIGT\Binding\Array.h> |
Support for additional containers can be added in a similar way.
Registering type Player
triggering events in both directions with instances of Player
as argument and as a result of a call handler.
Then in JavaScript, we receive an object with the specified properties. The value of each property is the same as in the moment of triggering the event. The JavaScript callback may store a reference to the object, but its properties WILL NOT be synchronised with the actual g_Game.m_Player
in the game.
If you want to call C++ handler with an instance of Player
created in JavaScript there is one important detail - the object must have a property __Type
with value Player (the same name of the type we gave to Coherent::UIGT::Binder::RegisterType in CoherentBind
for Player
. Otherwise Coherent GT cannot treat the object as an instance of Player
.
For some calls it's possible that there is no meaningful value to return. For example -
Coherent GT supports exporting C++ objects by reference. This avoids copying the C++ values to the JavaScript heap and makes the communication between the game and the UI faster. However the user is responsible for keeping the exposed C++ object pointers valid while they are exposed to JavaScript.
The API to expose a C++ object by reference is the same as normal values. The difference is that to expose a reference the object has to be wrapped in a Coherent::UIGT::ByRef
or Coherent::UIGT::ByRefThreadSafe
holder. The only difference between Coherent::UIGT::ByRef
and Coherent::UIGT::ByRefThreadSafe
is that ByRefThreadSafe is guaranteed to work correctly during a simultaneous execution. Which means that ByRef is faster, but must be used carefully because of various concurrency issues (e.g. race conditions).
Once an object is exposed by reference to JavaScript, any subsequent TriggerEvent
calls using ByRef
or ByRefThreadSafe
with the same object will result in the same JavaScript variable sent to JavaScript. This allows for 1-to-1 mapping between the C++ and JavaScript objects.
When an exposed object is about to be destroyed (or moved) its reference must be removed from JavaScript to avoid using invalid pointers (use-after-free). To notify JavaScript that a referenced object is no longer available call the Coherent::UIGT::View::RemoveExposedInstance
method with the address of the object being destroyed. It will remove the reference from the JavaScript values and make any attempt to access the properties of the object throw an exception in JavaScript. If you expose an array by ref you need to call Coherent::UIGT::View::RemoveExposedArray instead, with the address of the first element as an argument.
Coherent::UIGT::View::RemoveExposedInstance
method is asynchronous, so the JavaScript code should have stopped using the C++ object, before it can be safely removed.Here is a example usage of exposing objects by reference.
To take advantage of this C++ classes the JavaScript side can do:
When a C++ object is exposed by reference to JavaScript, its methods also might be called from JavaScript.
After this JavaScript can use the game
variable as any other object.
Coherent GT provides a default version of CoherentBind which will error out if you don't provide a template specialization of CoherentBind for your type. In some cases you might want to implement the default by yourself (e.g. binding all types via the reflection system of your engine). To do that you need to declare a template specialization for Coherent::UIGT::IsDefaultBindEnabled
structure in the way shown below.
For example let's declare DisableDefaultBinding
specialization for user-defined type Player
:
In the case you need to write a more generic version, you can use the second template parameter where you can use SFINAE and enable_if techniques. If you wish to disable default binding for classes and unions you can write something similar to this: