FireBreath学习之三 JSAPIAuto类的成员函数说明和插件调用DOM方法/属性一般形式

类FB JSAPIAuto

构造函数

FB::variant FB::JSAPIAuto::Construct(const std::vector& args)[virtual]

由浏览器调用构造JSAPI对象

var x = new MyJSAPIObject();

args:参数

返回值：新对象

//

FireJSEvent //触发事件，before 1.5.0

void FB::JSAPIAuto::FireJSEvent(const std::string&   eventName,

const FB:VariantMap&  members,  const FB::VariantList& args)[virtual]

注册一个异步事件到javascript，使用W3C-compliant事件参数

//js中添加事件,与FB版本无关

//IE

document.getElementById("plugin").attachEvent("on" + "eventName", function(){/*codes*/});

//非IE

document.getElementById("plugin").addEventListener("eventName", function(){/*codes*/}, false);

//触发事件, 可以在任何一个线程中触发事件，

//before 1.5.0

FireEvent("on" + "eventName", FB::variant_list_of("param1")(2)(3.0));

//注册事件，必须在构造函数中，before 1.5.0

registerEvent("on" + "eventName");

//after 1.5.0

//.h

public:

FB_JSAPI_EVENT(eventName, 参数个数， (参数类型列表s));   //注册，eventName不带on

//..

//.cpp

void MyAPI::FireAllEvents()

{

fire_eventName();                                    //触发

}

//

get_valid

bool FB::JSAPIAuto::get_valid()[inline, virtual]

提供给javascript的，用来确保JSAPI是否正在工作。

返回值： 成功返回true， 失败返回false。

//

getAttribute

public virtual FB::variant FB::JSAPIAuto::getAttribute(const std::string& name)[virtual]

功能：根据指定的attribute名字，返回attribute， 如果没有则返回空variant。

参数：name，attribute的名字

返回值：FB::variant

相关：registerAttribute, setAttribute, removeAttribute

///

getMemberCount

size_t FB::JSAPIAuto::getMemberCount() const [virtual]

功能：返回类成员数量

//

getMemberNames //获得成员名字

void FB::JSAPIAuto::getMemberNames(std::vector& nameVector) const [vritual]

它必须由任何继承JSAPI的类直接实现， JSAPIAuto已经为你实现了。

参数：[out]， vector

///

GetMethodObject 

FB::JSAPIPtr FB::JSAPIAuto::GetMethodObject(const std::string* methodObjName) [virtual]

通常使用这个函数来返回一个JSAPI对象作为一个属性，并且调用这个对象的的默认方法。这看起来像在javascript中是

一样的，除非你能保存这个函数对象。

参见FB:JSFunction 学习怎么样创建一个函数对象。

参数：methodName， methodObj的名字

返回值：methodObj值

///

GetProperty  //0， 有重载

FB::variant FB::JSAPIAuto::GetProperty(const std::string& propertyName) [virtual]

功能：根据属性名返回属性值

GetProperty  //1, 重载

FB:variant FB::JSAPIAuto::GetProperty(int idx) [virtual]

功能：返回执行索引号的属性值, idx从0开始

这可以用来在对象上提供一个数组风格的访问方式，下面的形式会调用GetProperty返回idx为12的属性值

//js方式和下面的方式功能相同

var propertyValue = document.getElementById("plugin")[12];

//和上面功能相同

std::string propertyValue = obj.GetProperty(12);

//

HasMethod

bool FB::JSAPIAuto::HasMethod(const std::string& methodName) const [virtual]

功能：查询是否这个JSAPI对象有methodName这个方法

返回值：这个方法存在返回true， 否则返回false

HasMethodObject

bool FB::JSAPIAuto::HasMethodObject(const std::string& methodObjName) const [virtual]

功能：查询methodObjName是否是一个可用的函数对象。

参数: methodObjName, Name of the method to fetch an object for.

返回值：methodObj存在返回true， 否则返回false。

HasProperty  //0, 有重载

bool FB::JSAPIAuto::HasProperty(const std::string& propertyName) const [virtual]

功能：查询 propertyName是否是一个可用的属性

参数：属性名

返回值：如果该属性存在返回true， 否则返回false

/

HasProperty    //1, 重载

bool FB::JSAPIAuto::HasProperty(int idx) const [virtual]

功能：查询属性索引值为idx的属性是否存在

和HasMethod(int idx)类似，这也能为对象提供一个数组风格的访问方式，下面在js中和在C++的两种形式结果相同

//js

document.getElementById("plugin")[7];    //为何和GetProperty(int idx)在js中访问一样呢？？？ 不明白

//.cpp

boo ret = obj.HasProperty(7);

///

Invoke

FB::variant FB::JSAPIAuto::Invoke(const std::string& methodName,

const std::vector& args)  [virtual]

功能：由浏览器来调用JSAPI对象的一个方法

参数：对象的方法名，  参数

返回值：对象的方法的返回值

//

isReserved

public bool FB::JSAPIAuto::isReserved(const std::string& propertyName) const [inline]

功能：如果指定的属性名是一个保留的attribute则返回true，否则返回false

参数：要检查的attribute的名字

JSAPIAuto

FB::JSAPIAuto::JSAPIAuto(const std::string& description = "")

功能：用ToString()来描述的

///

registerAttribute

public void FB::JSAPIAuto::registerAttribute(const std::string& name,

const FB::variant& value, bool readOnly = false) [virtual]

功能：注册一个attribute，可以在任意一个（除析构函数外）函数中调用此函数来注册attribute，

默认为非只读（即读写）。

参数： name:js中看到的attribute名字，  value：默认值， readOnly:是否只读

/

registerMethod

void FB::JSAPIAuto::registerMethod(const std::string& name,

const CallMethodFunctor& func)  [virtual]

功能：注册函数，在构造函数中，只需要注册提供给js访问的函数即可。

eg.

registerMethod("add", make_method(this, &MyAPI::addTwoNums));

其中add是提供给js访问的函数，addTwoNums是类的成员函数。

///

registerProperty

void FB::JSAPIAuto::registerProperty(const std::string& name,

const PropertyFunctors& propFuncs)   [virtual]

功能：注册一个属性，暴露给js， 在类的构造函数中

FB的属性和C#的属性类似，都是通过get和set函数获得的，如果是只读属性则只有get函数没有set函数。

eg.

//.h

registerProperty("name", make_property(this, &MyAPI::get_name, &MyAPI::set_name));

protected: 

std::string m_sName;

public:

void set_name(std::string name);

std::string get_name();

//.cpp

void MyAPI::set_name(std::string name)

{

this->name = name;

}

std::string MyAPI::get_name()

{

return this->name;

}

///

RemoveProperty      //0, 有重载

void FB::JSAPIAuto::RemoveProperty(const std::string& propertyName) [virtual]

功能：把一个类的指定属性去除

RemoveProperty       //1, 重载

void FB::JSAPIAuto::RemoveProperty(int idx) [virtual]

功能：按照索引去除属性

和GetProperty(int idx)及HasProperty(int idx)类似，在js中如下方式：

//js

delete document.getElementById("plugin")[6];  //和下面C++中效果相同

//cpp

obj.RemoveProperty(6);

//

setAttribute

public virtual void FB::JSAPIAuto::setAttribute(const std::string& name,

const FB::variant& value)   [virtual]

功能：给一个指定的atttibute赋值（如果不是保留或者只读）

参数：name:attribute名字，  value:值

///

SetProperty     //0, 有重载

void FB::JSAPIAuto::SetProperty(const std::string& propertyName,

const variant& value)  [virtual]

功能：给属性设定值

参数： propertyName:属性名，   value：值

//

SetProperty()  //1, 重载

void FB::JSAPIAuto::SetProperty(int idx, const variant& value) [virtual]

功能：按照指定索引，给属性赋值

//js

document.getElementById("plugin")[5] = "new value";

//.cpp

obj.SetProperty(5, "new value");

///

setReserved

public void FB::JSAPIAuto::setReserved(const std::string& name) [inline, virtual]

功能: 保护attributes不被javascript使用相同的名字来创建

这通常只在保护你的插件的attributes免于在js中被重写， 例如id, name, width都是默认保留的。

 

ToString

std::string FB::JSAPIAuto::ToString() [inline, virtual]

功能：当一个scriptable对象需要string值时默认调用的函数

根据需要重写这个函数， 否则它返回传递给构造函数的描述。

/

unregisterMethod

void FB::JSAPIAuto::unregisterMethod(const std::string& name) [virtual]

功能：把一个已经暴露给js的函数反注册，即不在提供给js访问。

参数：js可以访问的函数名

unregisterProperty

void FB::JSAPIAuto::unregisterProperty(const std::string& name) [virtual]

功能：把一个已经暴露给js访问的属性反注册，即不再让js访问该属性。

参数：js可以访问的属性名。

///

注意：RemoveProperty和unregisterProperty的区别，

RemoveProperty: 对象不再有此属性，当然js更不可能访问到。

unregisterProperty: 反注册此属性，对象有此属性，但是不再让js访问到。

在C++中调用DOM上的方法

//插件调用window.alert

#include "DOM/Window.h"

using namespace FB; 

//..

FB::DOM::WindowPtr window = m_host->getDOMWindow();

if(window && window->getJSObject()->HasProperty("window"))

{

FB::JSObjectPtr obj = window.getProperty("window");

//调用alert

obj->Invoke("alert", FB::variant_list_of("I am a alert!"));

}

//..

//插件调用console.log

#include "DOM/Window.h"

using namespace FB;        //如写此句可省略后面的FB::

//..

FB::DOM::WindowPtr window = m_host->getDOMWindow();

if(window && window->getJSObject()->HasProperty("console"))

{

//创建一个浏览器console对象的引用

FB::JSObjectPtr obj = window->getProperty("console");

//调用lgo方法

obj->Invoke("log", FB::variant_list_of("this is message for console..."));

}

//..

///

//插件调用JSON.parse

#include "DOM/Window.h"

//...

    // Retrieve a reference to the DOM Window

    FB::DOM::WindowPtr window = m_host->getDOMWindow();

 

    // A place to put the parse result

    FB::variant json_object;

 

    // Check if the DOM Window has an in-built JSON Parser

    if (window && window->getJSObject()->HasProperty("JSON")) {

        // Create a reference to the browswer JSON parser

        FB::JSObjectPtr obj = window->getProperty("JSON");

 

        // Invoke the "parse" method on the browser JSON object

        json_object = obj->Invoke("parse", FB::variant_list_of("{\"this is a test\":true}"));

    }

//...

///

//插件调用DOM属性

#include "DOM/Window.h"

//...

    // Retrieve a reference to the DOM Window

    FB::DOM::WindowPtr window = m_host->getDOMWindow();

 

    // Check if the DOM Window has the navigator object

    if (window && window->getJSObject()->HasProperty("navigator")) {

         std::string userAgent = window->getNode("navigator")->getProperty("userAgent");

    }