X-Git-Url: https://git.saurik.com/apple/javascriptcore.git/blobdiff_plain/93a3786624b2768d89bfa27e46598dc64e2fb70a..HEAD:/API/JSExport.h diff --git a/API/JSExport.h b/API/JSExport.h index 96e9fec..2d78dcc 100644 --- a/API/JSExport.h +++ b/API/JSExport.h @@ -27,103 +27,125 @@ #if JSC_OBJC_API_ENABLED -// When a JavaScript value is created from an instance of an Objective-C class -// for which no copying conversion is specified a JavaScript wrapper object will -// be created. -// -// In JavaScript inheritance is supported via a chain of prototype objects, and -// for each Objective-C class (and per JSContext) an object appropriate for use -// as a prototype will be provided. For the class NSObject the prototype object -// will be the JavaScript context's Object Prototype. For all other Objective-C -// classes a Prototype object will be created. The Prototype object for a given -// Objective-C class will have its internal [Prototype] property set to point to -// the Prototype object of the Objective-C class's superclass. As such the -// prototype chain for a JavaScript wrapper object will reflect the wrapped -// Objective-C type's inheritance hierarchy. -// -// In addition to the Prototype object a JavaScript Constructor object will also -// be produced for each Objective-C class. The Constructor object has a property -// named 'prototype' that references the Prototype object, and the Prototype -// object has a property named 'constructor' that references the Constructor. -// The Constructor object is not callable. -// -// By default no methods or properties of the Objective-C class will be exposed -// to JavaScript, however methods and properties may explicitly be exported. -// For each protocol that a class conforms to, if the protocol incorporates the -// protocol JSExport, then the protocol will be interpreted as a list of methods -// and properties to be exported to JavaScript. -// -// For each instance method being exported, a corresponding JavaScript function -// will be assigned as a property of the Prototype object, for each Objective-C -// property being exported a JavaScript accessor property will be created on the -// Prototype, and for each class method exported a JavaScript function will be -// created on the Constructor object. For example: -// -// @protocol MyClassJavaScriptMethods -// - (void)foo; -// @end -// -// @interface MyClass : NSObject -// - (void)foo; -// - (void)bar; -// @end -// -// Data properties that are created on the prototype or constructor objects have -// the attributes: writable:true, enumerable:false, configurable:true. Accessor -// properties have the attributes: enumerable:false and configurable:true. -// -// If an instance of MyClass is converted to a JavaScript value, the resulting -// wrapper object will (via its prototype) export the method "foo" to JavaScript, -// since the class conforms to the MyClassJavaScriptMethods protocol, and this -// protocol incorporates JSExport. "bar" will not be exported. -// -// Properties, arguments, and return values of the following types are -// supported: -// -// Primitive numbers: signed values of up to 32-bits are converted in a manner -// consistent with valueWithInt32/toInt32, unsigned values of up to 32-bits -// are converted in a manner consistent with valueWithUInt32/toUInt32, all -// other numeric values are converted consistently with valueWithDouble/ -// toDouble. -// BOOL: values are converted consistently with valueWithBool/toBool. -// id: values are converted consistently with valueWithObject/toObject. -// : - where the type is a pointer to a specified Objective-C -// class, conversion is consistent with valueWithObjectOfClass/toObject. -// struct types: C struct types are supported, where JSValue provides support -// for the given type. Support is built in for CGPoint, NSRange, CGRect, and -// CGSize. -// block types: In addition to support provided by valueWithObject/toObject for -// block types, if a JavaScript Function is passed as an argument, where the -// type required is a block with a void return value (and where the block's -// arguments are all of supported types), then a special adaptor block -// will be created, allowing the JavaScript function to be used in the place -// of a block. -// -// For any interface that conforms to JSExport the normal copying conversion for -// built in types will be inhibited - so, for example, if an instance that -// derives from NSString but conforms to JSExport is passed to valueWithObject: -// then a wrapper object for the Objective-C object will be returned rather than -// a JavaScript string primitive. +/*! +@protocol +@abstract JSExport provides a declarative way to export Objective-C instance methods, + class methods, and properties to JavaScript code. + +@discussion When a JavaScript value is created from an instance of an Objective-C class + for which no copying conversion is specified a JavaScript wrapper object will + be created. + + In JavaScript, inheritance is supported via a chain of prototype objects, and + for each Objective-C class (and per JSContext) an object appropriate for use + as a prototype will be provided. For the class NSObject the prototype object + will be the JavaScript context's Object Prototype. For all other Objective-C + classes a Prototype object will be created. The Prototype object for a given + Objective-C class will have its internal [Prototype] property set to point to + the Prototype object of the Objective-C class's superclass. As such the + prototype chain for a JavaScript wrapper object will reflect the wrapped + Objective-C type's inheritance hierarchy. + + In addition to the Prototype object a JavaScript Constructor object will also + be produced for each Objective-C class. The Constructor object has a property + named 'prototype' that references the Prototype object, and the Prototype + object has a property named 'constructor' that references the Constructor. + The Constructor object is not callable. + + By default no methods or properties of the Objective-C class will be exposed + to JavaScript; however methods and properties may explicitly be exported. + For each protocol that a class conforms to, if the protocol incorporates the + protocol JSExport, then the protocol will be interpreted as a list of methods + and properties to be exported to JavaScript. + + For each instance method being exported a corresponding JavaScript function + will be assigned as a property of the Prototype object. For each Objective-C + property being exported a JavaScript accessor property will be created on the + Prototype. For each class method exported a JavaScript function will be + created on the Constructor object. For example: + +
+@textblock
+    @protocol MyClassJavaScriptMethods 
+    - (void)foo;
+    @end
+
+    @interface MyClass : NSObject 
+    - (void)foo;
+    - (void)bar;
+    @end
+@/textblock
+
+ + Data properties that are created on the prototype or constructor objects have + the attributes: writable:true, enumerable:false, configurable:true. + Accessor properties have the attributes: enumerable:false and configurable:true. + + If an instance of MyClass is converted to a JavaScript value, the resulting + wrapper object will (via its prototype) export the method foo to JavaScript, + since the class conforms to the MyClassJavaScriptMethods protocol, and this + protocol incorporates JSExport. bar will not be exported. + + Properties, arguments, and return values of the following types are + supported: + + Primitive numbers: signed values of up to 32-bits are converted in a manner + consistent with valueWithInt32/toInt32, unsigned values of up to 32-bits + are converted in a manner consistent with valueWithUInt32/toUInt32, all + other numeric values are converted consistently with valueWithDouble/ + toDouble. + + BOOL: values are converted consistently with valueWithBool/toBool. + + id: values are converted consistently with valueWithObject/toObject. + + Objective-C Class: - where the type is a pointer to a specified Objective-C + class, conversion is consistent with valueWithObjectOfClass/toObject. + + struct types: C struct types are supported, where JSValue provides support + for the given type. Support is built in for CGPoint, NSRange, CGRect, and + CGSize. + + block types: Blocks can only be passed if they had been converted + successfully by valueWithObject/toObject previously. + + For any interface that conforms to JSExport the normal copying conversion for + built in types will be inhibited - so, for example, if an instance that + derives from NSString but conforms to JSExport is passed to valueWithObject: + then a wrapper object for the Objective-C object will be returned rather than + a JavaScript string primitive. +*/ @protocol JSExport @end -// When a selector that takes one or more arguments is converted to a JavaScript -// property name, by default a property name will be generated by performing the -// following conversion: -// - All colons are removed from the selector -// - Any lowercase letter that had followed a colon will be capitalized. -// Under the default conversion a selector "doFoo:withBar:" will be exported as -// "doFooWithBar". The default conversion may be overriden using the JSExportAs -// macro, for example to export a method "doFoo:withBar:" as "doFoo": -// -// @protocol MyClassJavaScriptMethods -// JSExportAs(doFoo, -// - (void)doFoo:(id)foo withBar:(id)bar -// ); -// @end -// -// Note that the JSExport macro may only be applied to a selector that takes one -// or more argument. +/*! +@define +@abstract Rename a selector when it's exported to JavaScript. +@discussion When a selector that takes one or more arguments is converted to a JavaScript + property name, by default a property name will be generated by performing the + following conversion: + + - All colons are removed from the selector + + - Any lowercase letter that had followed a colon will be capitalized. + + Under the default conversion a selector doFoo:withBar: will be exported as + doFooWithBar. The default conversion may be overriden using the JSExportAs + macro, for example to export a method doFoo:withBar: as doFoo: + +
+@textblock
+    @protocol MyClassJavaScriptMethods 
+    JSExportAs(doFoo,
+    - (void)doFoo:(id)foo withBar:(id)bar
+    );
+    @end
+@/textblock
+
+ + Note that the JSExport macro may only be applied to a selector that takes one + or more argument. +*/ #define JSExportAs(PropertyName, Selector) \ @optional Selector __JS_EXPORT_AS__##PropertyName:(id)argument; @required Selector