JSAPIAuto type support derives from the types supported by FB::variant. When JSAPIAuto converts an argument to the type your JSAPI method or property expects, it does so using FB::variant::convert_cast<type>. Understanding this will help you get the most out of the incredibly powerful type system that FireBreath supports.
FireBreath supports all arithmetic types and will automatically convert between them. This includes, but may not be limited to:
- (signed/unsigned) int
- (signed/unsigned) long
- (signed/unsigned) short
- (signed/unsigned) char
FireBreath supports the bool type and will convert common string representations such as "1", "t", "true", "yes", or "y" to true, anything else to false.
FireBreath supports both std::string and std::wstring and will automatically convert between them -- note that std::string representations are always UTF8 encoded.
char* and wchar_t*
As a return type only (or assigning to a FB::variant) you can use char* or wchar_t*, but these will get converted internally to std::string and std::wstring respectively.
Please note that return values utilizing containers must be one of the following two types:
- FB::VariantList (typedef for std::vector<FB::variant>)
- FB::VariantMap (typedef for std::map<std::string, FB::variant>)
Note that when using these objects from another thread, InvokeAsync or SetPropertyAsync should be used whenever appropriate instead of the synchronous version to avoid the performance hit of making a cross-thread synchronous call.
One of the most powerful features of FireBreath is the ability for one JSAPI object to return another, thus giving you a rich multi-layer object interface. JSAPI objects can be passed in using FB::JSAPIPtr and returned using the same wrapper.
Starting in FireBreath 1.4: Any JSAPI-derived type wrapped in a boost::shared_ptr can be used as a return type or as a parameter type. An example use-case for a JSAPI-derived type as a parameter would be if you need to pass in an object that was previously obtained from your plugin.
Starting in FireBreath 1.4: Any valid type can be wrapped in a boost::optional type to create an optional version of that type. If optional types are at the end of the argument list in a method they can be left off when calling the function.
Starting in FireBreath 1.4: Any of these types can be used to create a boost::variant; when used as a parameter type the input value will be passed in as either the matching type or the first successful conversion.
Starting in FireBreath 1.4: boost::tribool is supported allowing true, false, and indeterminate. When converting to this type null or undefined will map to indeterminate.
Starting in FireBreath 1.4: Enum types can be used as a return value, but they will simply be converted to an integral type before being returned to the browser