The Tor Browser / file comparison

comparison: xpcom/sample/xpconnect-sample.html

xpcom/sample/xpconnect-sample.html

changeset 0
6474c204b198
equal deleted inserted replaced
-1:000000000000 0:e84e1bcad099
1 <!-- This Source Code Form is subject to the terms of the Mozilla Public
2 - License, v. 2.0. If a copy of the MPL was not distributed with this
3 - file, You can obtain one at http://mozilla.org/MPL/2.0/. -->
4
5
6 <center><b><font size=+2>XPConnect Sample</font></b>
7
8 <p>
9 <a href="mailto:arielb@rice.edu">Ariel Blackenroth &lt;arielb@rice.edu&gt;</a>
10 <br>
11 <a href="mailto:mang@subcarrier.org">Michael Ang &lt;mang@subcarrier.org&gt;</a>
12 <br>
13 Last modified
14 <script>
15 document.write(document.lastModified);
16 </script>
17 </center>
18
19 <p>In the spirit of "worse is better" this somewhat rough guide is being
20 released to the world. It will be expanded upon and improved.
21
22 <p>XPConnect allows JavaScript
23 to transparantly access and manipulate XPCOM objects; this communication
24 between JavaScript and
25 native code is done by having their interfaces defined in the XPIDL interface
26 definition language. See the <a href="http://www.mozilla.org/scriptable/roadmap.html">Roadmap
27 for documentation on XPCOM, XPConnect, XPTCall and XPIDL</a> for more information.
28
29 <p><b>Overview</b>
30
31 <p>
32 This sample demonstrates accessing a XPCOM object through XPConnect.
33 The JavaScript executed when this page loads creates an instance
34 of the object by
35 using the <tt>Components</tt> object, then accesses it through
36 the <a href="http://lxr.mozilla.org/seamonkey/source/xpcom/sample/nsISample.idl">nsISample</a> interface by calling <tt>QueryInterface</tt>:
37 <br>
38 <pre>
39 netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
40 var sample = Components.classes["@mozilla.org/sample;1"].createInstance();
41 sample = sample.QueryInterface(Components.interfaces.nsISample);
42 </pre>
43
44 <p>
45 The buttons on the form are connected to JavaScript event handlers which
46 call the methods defined in C++.
47
48
49 <p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsISample.idl">nsISample.idl</a></b>
50 <p>This is the interface declaration for the XPCOM object. It defines
51 two functions, their parameters, and one attribute. It also defines
52 the interface's id. The idl file is compiled by the xpidl compiler
53 into a C++ header, nsISample.h and a .xpt file which is a binary representation
54 of the interface used at runtime.
55 <br><tt>attribute string value;</tt>
56 <br><tt>void writeValue(in string aPrefix);</tt>
57 <br><tt>void poke(in string aValue);</tt><b></b>
58 <p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsSample.cpp">nsSample.cpp</a></b>
59 <p>This contains the implementation of nsISample.idl. SampleImpl
60 inherits from nsISample.h, the header dynamically created by the xpidl
61 compiler. The attribute Value has been expanded into a get and set
62 and the return values have been modified to NS_IMETHOD, a success status
63 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>
64 defines the inherited methods from nsISupports.h.
65 <br><tt>NS_IMPL_ISUPPORTS(SampleImpl, nsISample)</tt>
66 <br>In the constructor, the macro NS_INIT_REFCNT is called which sets the
67 reference count to 0.<p>
68 Note that the methods in the C++ bindings use InterCaps style, while the IDL
69 and JavaScript versions should use interCaps naming. The JavaScript binding
70 matches the case of the IDL, <b>except</b> <a
71 href="http://bugzilla.mozilla.org/show_bug.cgi?id=14460">QueryInterface</a>.
72 <p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsSampleFactory.cpp">nsSampleFactory.cpp</a></b>
73 <p>This is the class which builds the instance of the nsSample class.
74 The COM framework uses factories to create instance of implementations
75 rather than having the implementations instantiate themselves in order to
76 increase portability of code. This factory inherits from nsFactory,
77 which is also an XPCOM object. To gain more knowledge of factories
78 see the <a href="http://www.mozilla.org/projects/xpcom/generic-factory.html">generic
79 factory document</a> or the <a href="http://www.mozilla.org/docs/modunote.htm#Basics">Modularization techniques document</a>.
80 <p><b><a href="http://lxr.mozilla.org/mozilla/source/xpcom/sample/nsSample.js">nsSample.js</a></b>
81 <p>This file implements the nsISample interface, and associated factory glue,
82 in JavaScript.
83
84 <p><b>Compiling the idl</b>
85
86 <p>The XPIDL compiler (xpidl on Unix, xpidl.exe on Windows, and a CodeWarrior plugin on Mac)
87 is compiled at build time (except on Mac) thus
88 you will have to build mozilla in order to test this out. If you
89 have already built mozilla then the compiler will be located at <tt>mozilla\dist\WIN32_D.OBJ\bin\xpidl.exe</tt>.
90
91 <p>Once you have the XPIDL compiler enter the following command at your
92 prompt:
93 <br><tt>D:\mozilla\xpcom\sample>d:\mozilla\dist\WIN32_D.OBJ\bin\xpidl -I
94 d:\mozilla\dist\idl -m header nsISample.idl</tt>
95
96 <p>The <tt>-I d:\mozilla\dist\idl</tt> points the compiler to the folder
97 containing the other idl files, needed because nsISample.idl inherits from
98 nsISupports.idl. The <tt>-m header</tt> instruction tells the compiler
99 to build the C++ header. To build the .xpt file substitute <tt>-m
100 typelib</tt>.
101
102 <p>
103 For more information on compilation see the <a href="http://www.mozilla.org/scriptable/xpidl/">xpidl
104 compiler page</a>.
105
106 <p><b>Building the Sample</b>
107
108 <p>To build the Sample just enter
109 <br><tt>d:\mozilla\xpcom\sample>nmake /f makefile.win</tt>
110
111 <p>In order to do this you need to have your environment variables set
112 correctly. See the <a href="http://www.mozilla.org/build/">Build</a>
113 page for more information.
114
115 <p><b>Running the sample</b>
116 <p>Using Mozilla, load
117 <a href="resource://res/samples/xpconnect-sample.html">resource://res/samples/xpconnect-sample.html</a> (i.e. what
118 you're reading now). Pay attention
119 to the console when clicking "write". Notice that the value
120 printed is calculated in C++ code defined in <a href="http://lxr.mozilla.org/seamonkey/source/xpcom/sample/nsSample.cpp">nsSample.cpp</a>.
121
122 <!-- XXX keep in sync with stuff in pre tag below -->
123 <script>
124 /* to use nsSample.js version, use "@mozilla.org/jssample;1" */
125 netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
126 var sample = Components.classes["@mozilla.org/sample;1"].createInstance();
127 sample = sample.QueryInterface(Components.interfaces.nsISample);
128 dump("sample = " + sample + "\n");
129
130 function get()
131 {
132 netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
133 var field = document.getElementById('Value');
134 field.value = sample.value;
135 }
136
137 function set()
138 {
139 netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
140 var field = document.getElementById('Value');
141 sample.value = field.value;
142 }
143
144 function poke()
145 {
146 netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
147 var field = document.getElementById('Value');
148 sample.poke(field.value);
149 }
150
151 function sampleWrite()
152 {
153 netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
154 sample.writeValue("here is what I'm writing: ");
155 }
156 </script>
157
158 <p>
159 <form name="form">
160 <input type="button" value="Get" onclick="get();">
161 <input type="button" value="Set" onclick="set();">
162 <input type="button" value="Poke" onclick="poke();">
163 <input type="text" id="Value">
164 <input type="button" value="Write" onclick="sampleWrite();">
165 <form>
166
167 <hr>
168
169 <p>
170 JavaScript and form source:
171
172 <!-- XXX keep in sync with actual script -->
173 <pre>
174 &lt;script&gt;
175 /* to use nsSample.js version, use "@mozilla.org/jssample;1" */
176 netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
177 var sample = Components.classes["@mozilla.org/sample;1"].createInstance();
178 sample = sample.QueryInterface(Components.interfaces.nsISample);
179 dump("sample = " + sample + "\n");
180
181 function get()
182 {
183 netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); var field = document.getElementById('Value');
184 field.value = sample.value;
185 }
186
187 function set()
188 {
189 netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); var field = document.getElementById('Value');
190 sample.value = field.value;
191 }
192
193 function poke()
194 {
195 netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect"); var field = document.getElementById('Value');
196 sample.poke(field.value);
197 }
198
199 function sampleWrite()
200 {
201 netscape.security.PrivilegeManager.enablePrivilege("UniversalXPConnect");
202 sample.writeValue("here is what I'm writing: ");
203 }
204 &lt;/script&gt;
205
206 &lt;form name=&quot;form&quot;&gt;
207 &lt;input type=&quot;button&quot; value=&quot;Get&quot; onclick=&quot;get();&quot;&gt;
208 &lt;input type=&quot;button&quot; value=&quot;Set&quot; onclick=&quot;set();&quot;&gt;
209 &lt;input type=&quot;button&quot; value=&quot;Poke&quot; onclick=&quot;poke();&quot;&gt;
210 &lt;input type=&quot;text&quot; id=&quot;Value&quot;&gt;
211 &lt;input type=&quot;button&quot; value=&quot;Write&quot; onclick=&quot;sampleWrite();&quot;&gt;
212 &lt;form>
213
214 </pre>
215
216 <p>
217 <hr>
218 <b>Resources:</b>
219 <ul>
220 <li><a href="http://lxr.mozilla.org/seamonkey/source/xpcom/sample/">mozilla/xpcom/sample source directory</a>
221 </ul>
222 <hr>
223 <b>Comments to:</b>
224 <a href="mailto:mang@subcarrier.org?Subject=XPCOM sample documentation">Michael Ang &lt;mang@subcarrier.org&gt;</a>

Mercurial Repository: The Tor Browser

Europalab SCM Repository Server

mercurial