diff options
Diffstat (limited to 'src/libs/xpcom18a4/xpcom/sample/xpconnect-sample.html')
| -rw-r--r-- | src/libs/xpcom18a4/xpcom/sample/xpconnect-sample.html | 220 |
1 files changed, 220 insertions, 0 deletions
diff --git a/src/libs/xpcom18a4/xpcom/sample/xpconnect-sample.html b/src/libs/xpcom18a4/xpcom/sample/xpconnect-sample.html new file mode 100644 index 00000000..78e91be1 --- /dev/null +++ b/src/libs/xpcom18a4/xpcom/sample/xpconnect-sample.html @@ -0,0 +1,220 @@ + +<center><b><font size=+2>XPConnect Sample</font></b> + +<p> +<a href="mailto:arielb@rice.edu">Ariel Blackenroth <arielb@rice.edu></a> +<br> +<a href="mailto:mang@subcarrier.org">Michael Ang <mang@subcarrier.org></a> +<br> +Last modified +<script> +document.write(document.lastModified); +</script> +</center> + +<p>In the spirit of "worse is better" this somewhat rough guide is being +released to the world. It will be expanded upon and improved. + +<p>XPConnect allows JavaScript +to transparantly access and manipulate XPCOM objects; this communication +between JavaScript and +native code is done by having their interfaces defined in the XPIDL interface +definition language. See the <a href="http://www.mozilla.org/scriptable/roadmap.html">Roadmap +for documentation on XPCOM, XPConnect, XPTCall and XPIDL</a> for more information. + +<p><b>Overview</b> + +<p> +This sample demonstrates accessing a XPCOM object through XPConnect. +The JavaScript executed when this page loads creates an instance +of the object by +using the <tt>Components</tt> object, then accesses it through +the <a href="http://lxr.mozilla.org/seamonkey/source/xpcom/sample/nsISample.idl">nsISample</a> interface by calling <tt>QueryInterface</tt>: +<br> +<pre> +netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); +var sample = Components.classes["@mozilla.org/sample;1"].createInstance(); +sample = sample.QueryInterface(Components.interfaces.nsISample); +</pre> + +<p> +The buttons on the form are connected to JavaScript event handlers which +call the methods defined in C++. + + +<p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsISample.idl">nsISample.idl</a></b> +<p>This is the interface declaration for the XPCOM object. It defines +two functions, their parameters, and one attribute. It also defines +the interface's id. The idl file is compiled by the xpidl compiler +into a C++ header, nsISample.h and a .xpt file which is a binary representation +of the interface used at runtime. +<br><tt>attribute string value;</tt> +<br><tt>void writeValue(in string aPrefix);</tt> +<br><tt>void poke(in string aValue);</tt><b></b> +<p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsSample.cpp">nsSample.cpp</a></b> +<p>This contains the implementation of nsISample.idl. SampleImpl +inherits from nsISample.h, the header dynamically created by the xpidl +compiler. The attribute Value has been expanded into a get and set +and the return values have been modified to NS_IMETHOD, a success status +for the method. The macro NS_DECL_ISUPPORTS, defined in <a href="http://lxr.mozilla.org/mozilla/source/xpcom/base/nsISupportsUtils.h">mozilla/xpcom/public/nsISupportsUtils.h</a> +defines the inherited methods from nsISupports.h. +<br><tt>NS_IMPL_ISUPPORTS1(SampleImpl, nsISample)</tt> +<br>In the constructor, the macro NS_INIT_REFCNT is called which sets the +reference count to 0.<p> +Note that the methods in the C++ bindings use InterCaps style, while the IDL +and JavaScript versions should use interCaps naming. The JavaScript binding +matches the case of the IDL, <b>except</b> <a +href="http://bugzilla.mozilla.org/show_bug.cgi?id=14460">QueryInterface</a>. +<p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsSampleFactory.cpp">nsSampleFactory.cpp</a></b> +<p>This is the class which builds the instance of the nsSample class. +The COM framework uses factories to create instance of implementations +rather than having the implementations instatiate themselves in order to +increase portability of code. This factory inherits from nsFactory, +which is also an XPCOM object. To gain more knowledge of factories +see the <a href="http://www.mozilla.org/projects/xpcom/generic-factory.html">generic +factory document</a> or the <a href="http://www.mozilla.org/docs/modunote.htm#Basics">Modularization techniques document</a>. +<p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsSample.js">nsSample.js</a></b> +<p>This file implements the nsISample interface, and associated factory glue, +in JavaScript. + +<p><b>Compiling the idl</b> + +<p>The XPIDL compiler (xpidl on Unix, xpidl.exe on Windows, and a CodeWarrior plugin on Mac) +is compiled at build time (except on Mac) thus +you will have to build mozilla in order to test this out. If you +have already built mozilla then the compiler will be located at <tt>mozilla\dist\WIN32_D.OBJ\bin\xpidl.exe</tt>. + +<p>Once you have the XPIDL compiler enter the following command at your +prompt: +<br><tt>D:\mozilla\xpcom\sample>d:\mozilla\dist\WIN32_D.OBJ\bin\xpidl -I +d:\mozilla\dist\idl -m header nsISample.idl</tt> + +<p>The <tt>-I d:\mozilla\dist\idl</tt> points the compiler to the folder +containing the other idl files, needed because nsISample.idl inherits from +nsISupports.idl. The <tt>-m header</tt> instruction tells the compiler +to build the C++ header. To build the .xpt file substitute <tt>-m +typelib</tt>. + +<p> +For more information on compilation see the <a href="http://www.mozilla.org/scriptable/xpidl/">xpidl +compiler page</a>. + +<p><b>Building the Sample</b> + +<p>To build the Sample just enter +<br><tt>d:\mozilla\xpcom\sample>nmake /f makefile.win</tt> + +<p>In order to do this you need to have your environment variables set +correctly. See the <a href="http://www.mozilla.org/build/">Build</a> +page for more information. + +<p><b>Running the sample</b> +<p>Using Mozilla, load +<a href="resource://res/samples/xpconnect-sample.html">resource://res/samples/xpconnect-sample.html</a> (i.e. what +you're reading now). Pay attention +to the console when clicking "write". Notice that the value +printed is calculated in C++ code defined in <a href="http://lxr.mozilla.org/seamonkey/source/xpcom/sample/nsSample.cpp">nsSample.cpp</a>. + +<!-- XXX keep in sync with stuff in pre tag below --> +<script> +/* to use nsSample.js version, use "@mozilla.org/jssample;1" */ +netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); +var sample = Components.classes["@mozilla.org/sample;1"].createInstance(); +sample = sample.QueryInterface(Components.interfaces.nsISample); +dump("sample = " + sample + "\n"); + +function get() +{ + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); + var field = document.getElementById('Value'); + field.value = sample.value; +} + +function set() +{ + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); + var field = document.getElementById('Value'); + sample.value = field.value; +} + +function poke() +{ + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); + var field = document.getElementById('Value'); + sample.poke(field.value); +} + +function sampleWrite() +{ + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); + sample.writeValue("here is what I'm writing: "); +} +</script> + +<p> +<form name="form"> +<input type="button" value="Get" onclick="get();"> +<input type="button" value="Set" onclick="set();"> +<input type="button" value="Poke" onclick="poke();"> +<input type="text" id="Value"> +<input type="button" value="Write" onclick="sampleWrite();"> +<form> + +<hr> + +<p> +JavaScript and form source: + +<!-- XXX keep in sync with actual script --> +<pre> +<script> +/* to use nsSample.js version, use "@mozilla.org/jssample;1" */ +netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); +var sample = Components.classes["@mozilla.org/sample;1"].createInstance(); +sample = sample.QueryInterface(Components.interfaces.nsISample); +dump("sample = " + sample + "\n"); + +function get() +{ + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); var field = document.getElementById('Value'); + field.value = sample.value; +} + +function set() +{ + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); var field = document.getElementById('Value'); + sample.value = field.value; +} + +function poke() +{ + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); var field = document.getElementById('Value'); + sample.poke(field.value); +} + +function sampleWrite() +{ + netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); + sample.writeValue("here is what I'm writing: "); +} +</script> + +<form name="form"> +<input type="button" value="Get" onclick="get();"> +<input type="button" value="Set" onclick="set();"> +<input type="button" value="Poke" onclick="poke();"> +<input type="text" id="Value"> +<input type="button" value="Write" onclick="sampleWrite();"> +<form> + +</pre> + +<p> +<hr> +<b>Resources:</b> +<ul> +<li><a href="http://lxr.mozilla.org/seamonkey/source/xpcom/sample/">mozilla/xpcom/sample source directory</a> +</ul> +<hr> +<b>Comments to:</b> +<a href="mailto:mang@subcarrier.org?Subject=XPCOM sample documentation">Michael Ang <mang@subcarrier.org></a> |