Doc only. Merged README.html into xpconnect-sample.html.
This commit is contained in:
mang%subcarrier.org
Родитель
d070b44190
Коммит
1217e35037
|
|
@ -1,9 +1,112 @@
|
||||||
<html>
|
|
||||||
<head>
|
|
||||||
<title>XPConnect Example</title>
|
|
||||||
</head>
|
|
||||||
|
|
||||||
<body>
|
<center><b><font size=+2>XPConnect Sample</font></b>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
<a href="mailto:arielb@netscape.com">Ariel Blackenroth <arielb@netscape.com></a>
|
||||||
|
<br>
|
||||||
|
<a href="mailto:mang@subcarrier.org">Michael Ang <mang@subcarrier.org></a>
|
||||||
|
<br>
|
||||||
|
Last modified Aug 4, 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>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>
|
||||||
|
var sample = Components.classes["component://netscape/sample/sample-world"].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>nsISample.idl</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>nsSample.cpp</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 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>
|
||||||
|
<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/tplist/catFlow/modunote.htm#Basics">
|
||||||
|
Modularization techniques document</a>.
|
||||||
|
|
||||||
|
<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/seamonky/source/xpcom/sample/nsSample.cpp">nsSample.cpp</a>.
|
||||||
|
|
||||||
|
<!-- XXX keep in sync with stuff in pre tag below -->
|
||||||
<script>
|
<script>
|
||||||
var sample = Components.classes["component://netscape/sample/sample-world"].createInstance();
|
var sample = Components.classes["component://netscape/sample/sample-world"].createInstance();
|
||||||
sample = sample.QueryInterface(Components.interfaces.nsISample);
|
sample = sample.QueryInterface(Components.interfaces.nsISample);
|
||||||
|
|
@ -33,6 +136,7 @@ function write()
|
||||||
}
|
}
|
||||||
</script>
|
</script>
|
||||||
|
|
||||||
|
<p>
|
||||||
<form name="form">
|
<form name="form">
|
||||||
<input type="button" value="Get" onclick="get();">
|
<input type="button" value="Get" onclick="get();">
|
||||||
<input type="button" value="Set" onclick="set();">
|
<input type="button" value="Set" onclick="set();">
|
||||||
|
|
@ -40,5 +144,59 @@ function write()
|
||||||
<input type="text" id="Value">
|
<input type="text" id="Value">
|
||||||
<input type="button" value="Write" onclick="write();">
|
<input type="button" value="Write" onclick="write();">
|
||||||
<form>
|
<form>
|
||||||
</body>
|
|
||||||
</html>
|
<hr>
|
||||||
|
|
||||||
|
<p>
|
||||||
|
JavaScript and form source:
|
||||||
|
|
||||||
|
<!-- XXX keep in sync with actual script -->
|
||||||
|
<pre>
|
||||||
|
<script>
|
||||||
|
var sample = Components.classes["component://netscape/sample/sample-world"].createInstance();
|
||||||
|
sample = sample.QueryInterface(Components.interfaces.nsISample);
|
||||||
|
dump("sample = " + sample + "\n");
|
||||||
|
|
||||||
|
function get()
|
||||||
|
{
|
||||||
|
var field = document.getElementById('Value');
|
||||||
|
field.value = sample.Value;
|
||||||
|
}
|
||||||
|
|
||||||
|
function set()
|
||||||
|
{
|
||||||
|
var field = document.getElementById('Value');
|
||||||
|
sample.Value = field.value;
|
||||||
|
}
|
||||||
|
|
||||||
|
function poke()
|
||||||
|
{
|
||||||
|
var field = document.getElementById('Value');
|
||||||
|
sample.Poke(field.value);
|
||||||
|
}
|
||||||
|
|
||||||
|
function write()
|
||||||
|
{
|
||||||
|
sample.WriteValue("here is what I'm writing!" + Components.interfaces.nsISample.MY_CONST_THINGIE);
|
||||||
|
}
|
||||||
|
</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="write();">
|
||||||
|
<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>
|
||||||
|
|
|
||||||
Загрузка…
Ссылка в новой задаче