gecko-dev/xpcom/sample

<center><b><font size=+2>XPConnect Sample</font></b>

<p>
<a href="mailto:arielb@netscape.com">Ariel Blackeroth &lt;arielb@netscape.com&gt;</a>
<br>
<a href="mailto:mang@subcarrier.org">Michael Ang &lt;mang@subcarrier.org&gt;</a>
<br>
Last modified July 9, 1999
</center>

<hr>
<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><b>Overview</b>
<br>This sample is located in the Mozilla tree at mozilla/xpcom/sample
and is a simple demonstration of XPConnect.&nbsp; 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.
The sample demonstrates how a JavaScript call can access and manipulate
a XPCOM interface.<b></b>
<p><b>nsISample.idl</b>
<br>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>nsSample.cpp</b>
<br>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 mozilla/xpcom/public/nsISupportsUtils.h
defines the inherited methods from nsISupports.h.
<br><tt>NS_IMPL_ISUPPORTS(SampleImpl, nsISample::GetIID());</tt>
<br>In the constructor, the macro NS_INIT_REFCNT is called which sets the
reference count to 0.
<p><b>nsSampleFactory.cpp</b>
<br>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/tplist/catFlow/modunote.htm#Basics">
Modularization techniques document</a>.
<p><b>xpconnect-sample.html</b>
<br>This contains the calls from JavaScript to the XPCOM object.
In the first two lines JavaScript obtains a reference to the XPCOM object.
<br><tt>var sample = Components.classes["component://netscape/sample/sample-world"].createInstance();</tt>
<br><tt>sample = sample.QueryInterface(Components.interfaces.nsISample);</tt>
<br>After these instructions, the sample object is available seemlessly
to the script.
<p><b>Compiling the idl</b>
<br>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>.
<br>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>
<br>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>. 
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>
<br>To build the Sample just enter
<br><tt>d:\mozilla\xpcom\sample>nmake /f makefile.win</tt>
<br>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>
<br>Using your mozilla browser, load the xpconnect-sample.html document.
The mozilla binary is located at <tt>\mozilla\dist\WIN32_D.OBJ\bin\apprunner.exe</tt>.
Set the url to <tt>file:///D|/mozilla/xpcom/sample/xpconnect-sample.html
</tt>or wherever you have the samle html file located. Pay attention
to the console when clicking write. Notice that the value printed is calculated in C++ code
defined in nsSample.cpp.

<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 &lt;mang@subcarrier.org&gt;</a>