README.md

Bea tools for C++

Purpose

The purpose of Bea C++ is to provide a 'glue' between the code generated by the Bea C++ to V8 Converter and native C++ library/application.
It is a single .h file which provides all the APIs needed by the converter.
A short description of the API is found in this file.

Convert

Specialize this with a custom type to define conversions from/to Javascript.
Bea provides specializations for most basic C++ types: int, double, bool, std::string, std::vector, but custom 
types can be easily converted.

	//C++ : Converting a Point object from/to javascript
	template<> struct Convert<cv::Point> {
		static bool Is(v8::Handle<v8::Value> v) {
			return !v.IsEmpty() && v->IsObject();
		}
		
		static cv::Point FromJS(v8::Handle<v8::Value> v, int nArg) {
			const char* msg = "Object with the following properties expected: x, y. This will be cast to 'cv::Point'";
			if (!Is(v)) BEATHROW();
			v8::HandleScope scope;
			v8::Local<v8::Object> obj = v->ToObject();
			cv::Point ret;
			ret.x = bea::Convert<int>::FromJS(obj->Get(v8::String::NewSymbol("x")), nArg);
			ret.y = bea::Convert<int>::FromJS(obj->Get(v8::String::NewSymbol("y")), nArg);
			return ret;
		}
		
		static v8::Handle<v8::Value> ToJS(cv::Point const& v) {
			v8::HandleScope scope;
			v8::Local<v8::Object> obj = v8::Object::New();
			obj->Set(v8::String::NewSymbol("x"), bea::Convert<int>::ToJS(v.x));
			obj->Set(v8::String::NewSymbol("y"), bea::Convert<int>::ToJS(v.y));
			return scope.Close(obj);
		}
	};
	
If there is an exposed C++ class which takes a cv::Point as a parameter, the following javascript can be used:
	//Javascript: Passing a cv::Point from Javascript to the native function
	myobject.myfunction({x: 100, y: 100});	//Use familiar Javascript object notation

ExposedClass

This class is used to expose a C++ class to Javascript. 
The term 'Class' means 'a function template which can be instantiated from Javascript with operator new.'
The class must be specialized for the desired type and instantiated. Then the methods *exposeMethod()*, *exposeProperty()*, *setConstructor()* can be called.
Here is an example:

	//C++: Using ExposedClass
	bea::ExposedClass<cv::Mat>* obj = EXPOSE_CLASS(cv::Mat, "Mat");
	//Destructor
	obj->setDestructor(__destructor);
	//Exposed Methods
	obj->setPostAllocator(__postAllocator);
	obj->setConstructor(__constructor);
	obj->exposeMethod("row", row);
	obj->exposeMethod("col", col);
	//Accessors
	obj->exposeProperty("width", accGet_width, accSet_width);
	obj->exposeProperty("height", accGet_height, accSet_height);
	
This allows us to execute this script:
	//Javascript
	var mat = new Mat();
	mat.row()
	mat.col()
	log(mat.width)
	log(mat.height)

DECLARE_EXPOSED_CLASS(ClassName)

Helper macros which creates a static variable bea::ExposedClass<ClassName>* bea::ExposedClass<ClassName>::Instance = NULL;

EXPOSE_CLASS(typeName, jsName)

Helper macros which creates an instance of ExposedClass<typeName> and exposes it as jsName

ExposedStatic

This is an object exposed to Javascript, which cannot be instantiated. 
The term 'Static' means 'an object which can be accessed from Javascript'.
The class must be specialized for the desired type. Then the method *exposeMethod()*, can be used.
The functions exposed by ExposedStatic don't have a 'this' pointer (eg. static C++ or C functions).