IDL Best Practices
We're currently working on this documentation. New stuff will be added
on an ongoing basis. Please send any questions or comments to
netscape.public.mozilla.xpcom.
enums and
consts
Constants defined inside an interface in XPIDL appear as JavaScript
properties of instances of classes that implement that interface.
Recall that constants must be of type short or long.
It is possible to implement constants of other type (string,
for example)
by holding the value in an attribute of the interface, or returning it
through a method.
| XPIDL code | Example JavaScript |
interface nsIFoo {
const ONE = 1;
};
|
var myFoo = Components.classes["component://netscape/sample/sample-foo"].CreateInstance();
var myFoo = myFoo.QueryInteface(Components.intefaces.nsIFoo);
print(myFoo.ONE);
|
Return types
You should use a return type other than void so that
script writers will be able to use the return value directly.
(In C++ the return value is converted into a trailing out
parameter.)
native
and raw C++ types
Any interface that contains native or raw C++ types cannot be
made scriptable. The XPIDL compiler will treat it as an error
if an interface or method is marked as scriptable and it contains
native or raw C++ types.
Individual methods in an interface may be marked as not scriptable by
using the [noscript] attribute before the problem method.
Methods marked with [noscript] will not be available for
use from scripting languages.
| XPIDL code | Comment |
native nsNativeType(nsFileSpec);
[scriptable] interface foo {
void BadMethod(in nsNativeType aNativeType);
};
|
Compiler exits with error:
cannot_script.idl:4: Error: methods in [scriptable] interfaces which are non-scriptable because they refer to native types (parameter "aNativeType") must be marked [noscript]
|
native nsNativeType(nsFileSpec);
[scriptable] interface foo {
[noscript] void BadMethod(in nsNativeType aNativeType);
};
|
C++ header file is generated as normal. BadMethod is
not available from JavaScript.
|
String Passing
All strings that are returned through out parameters in C++
must be allocated using the nsIAllocator so that
the string's lifetime can be managed by XPConnect. If a string is
not allocated with nsIAllocator, then the string will
get lost, resulting in a memory leak or crash.
See the XPConnect FAQ
item "How do I make 'out string' work right?"
for details on how to properly pass strings out of a method.
[Rules and Syntax] [Best Practices]
[Keywords]
Mike Ang
Last modified: Fri Aug 27 19:27:55 PDT 1999
|
