- fixed <rdar://problem/3855573> Remove reference to "WebScriptMethods" from...
[WebKit-https.git] / JavaScriptCore / bindings / objc / WebScriptObject.h
1 /*
2     Copyright (C) 2004 Apple Computer, Inc. All rights reserved.    
3     
4     Public header file.
5  */
6
7 #import <Foundation/Foundation.h>
8
9 // NSObject (WebScripting) ----------------------------------------------------- 
10
11 /*
12     The methods in WebScripting are optionally implemented by classes whose
13     interfaces are exported (wrapped) to a web scripting environment.  The 
14     scripting environment currently supported by WebKit uses the JavaScript
15     language.
16     
17     Instances automatically reflect their interfaces in the scripting environment.  This
18     automatic reflection can be overriden using the class methods defined in the WebScripting
19     informal protocol.
20     
21     Access to the attributes of an instance is done using KVC. Specifically the following
22     KVC methods:
23         
24         - (void)setValue:(id)value forKey:(NSString *)key
25         - (id)valueForKey:(NSString *)key
26         
27     Instances may also intercept property set/get operations and method invocations that are
28     made by the scripting environment, but not reflected.  This is done using the KVC
29     methods:
30
31         - (void)setValue:(id)value forUndefinedKey:(NSString *)key
32         - (id)valueForUndefinedKey:(NSString *)key
33     
34     If clients need to raise an exception in the script environment
35     they can call [WebScriptObject throwException:].  Note that throwing an
36     exception using this method will only succeed if the method that throws the exception
37     is being called within the scope of a script invocation.
38     
39     By default all attributes, as defined by KVC, will be exposed.  However, a
40     class may further exclude properties that they do not want to expose
41     to web script.
42         
43     Not all methods are exposed.  Only those methods whose parameters and return
44     type meets the export criteria will exposed.  Valid types are ObjectiveC instances
45     and scalars.  Other types are not allowed.  Classes may further exclude method
46     that they do not want to expose.
47     
48     Types will be converted to appropriate types in the scripting environment.
49     After any KVC coercion occurs the ObjectiveC types will converted to a type
50     appropriate for the script environment.  For JavaScript NSNumber will be
51     converted to numbers.  NSString will be converted to strings.  NSArray will
52     be mapped to a special read-only array.  NSNull will be converted to null.  
53     WebUndefined will be converted to undefined.  WebScriptObjects will be unwrapped.
54     Instances of other classes will be wrapped when passed to the script environment
55     and unwrapped when returned to ObjectiveC.  Similar conversion happens in the
56     other direction.
57 */
58 @interface NSObject (WebScripting)
59
60 /*!
61     @method webScriptNameForSelector:
62     @param aSelector The selector that will be exposed to the script environment.
63     @discussion Use the returned string as the exported name for the selector
64     in the script environment.  It is the responsibility of the class to ensure
65     uniqueness of the returned name.  If nil is returned or this
66     method is not implemented the default name for the selector will
67     be used.  The default name concatenates the components of the
68     ObjectiveC selector name and replaces ':' with '_'.  '_' characters
69     are escaped with an additional '$', i.e. '_' becomes "$_".  '$' are
70     also escaped, i.e.
71         ObjectiveC name         Default script name
72         moveTo::                move__
73         moveTo_                 moveTo$_
74         moveTo$_                moveTo$$$_
75     @result Returns the name to be used to represent the specificed selector in the
76     scripting environment.
77 */
78 + (NSString *)webScriptNameForSelector:(SEL)aSelector;
79
80 /*!
81     @method isSelectorExcludedFromWebScript:
82     @param aSelect  The selector the will be exposed to the script environment.
83     @discussion Return YES to prevent the selector appearing in the script
84     environment.  Return NO to expose the selector in the script environment.
85     If this method is not implemented on the class all the selector that match
86     the export criteria will be exposed.
87     @result Returns YES to hide the selector, NO to expose the selector.
88 */
89 + (BOOL)isSelectorExcludedFromWebScript:(SEL)aSelector;
90
91 /*!
92     @method webScriptNameForKey:
93     @param name The name of the instance variable that will be exposed to the
94     script enviroment.  Only that properties that meet the export criteria will
95     be exposed.
96     @discussion Provide an alternate name for a property.
97     @result Returns the name to be used to represent the specificed property in the
98     scripting environment.
99 */
100 + (NSString *)webScriptNameForKey:(const char *)name;
101
102 /*!
103     @method isKeyExcludedFromWebScript:
104     @param name The name of the instance variable that will be exposed to the
105     scrip environment.
106     @discussion Return YES to exclude the property from visibility in the script environement.
107     Return NO to expose the instance varible to the script environment.
108     @result Returns YES to hide the property, NO to expose the property.
109 */
110 + (BOOL)isKeyExcludedFromWebScript:(const char *)name;
111
112 /*!
113     @method invokeUndefinedMethodFromWebScript:withArguments:
114     @param name The name of the method to invoke.
115     @param args The args to pass the method.
116     @discussion If a script attempt to invoke a method that is not an exposed
117     method, scriptInvocation:withArgs: will be called.
118     @result The return value of the invocation.  The value will be converted as appropriate
119     for the script environment.
120 */
121 - (id)invokeUndefinedMethodFromWebScript:(NSString *)name withArguments:(NSArray *)args;
122
123 /*!
124     @method invokeDefaultMethodWithArguments:
125     @param args The args to pass the method.
126     @discussion If a script attempts to invoke a method on an exposed object
127     directly this method will be called.
128 */
129 - (id)invokeDefaultMethodWithArguments:(NSArray *)args;
130
131 /*!
132     @method finalizeForWebScript
133     @discussion finalizeForScript is called on objects exposed to the script
134     environment just before the script environment releases the object.  After calls to
135     finalizeForWebScript the object will no longer be referenced by the script environment.
136     Further, any references to WebScriptObjects made by the exposed object will
137     be invalid and have undefined consequences.
138 */
139 - (void)finalizeForWebScript;
140
141 @end
142
143
144 // WebScriptObject -------------------------------------------------- 
145
146 @class WebScriptObjectPrivate;
147
148 /*!
149     @class WebScriptObject
150     @discussion WebScriptObjects are used to wrap script objects passed from
151     script environments to ObjectiveC.  WebScriptObjects cannot be created
152     directly.  In normal uses of WebKit, you gain access to the script
153     environment using the "windowScriptObject" method on WebView.
154     
155     The following KVC methods are commonly used to access properties of the
156     WebScriptObject:
157     
158         - (void)setValue:(id)value forKey:(NSString *)key
159         - (id)valueForKey:(NSString *)key
160         
161         As it possible to remove attributes from web script objects the following
162         additional method augments the basic KVC methods:
163         
164         - (void)removeWebScriptKey:(NSString *)name;
165         
166         Also the sparse array access allowed in web script objects doesn't map well to NSArray, so
167         the following methods can be used to access index based properties:
168         
169         - (id)webScriptValueAtIndex:(unsigned int)index;
170         - (void)setWebScriptValueAtIndex:(unsigned int)index value:(id)value;
171 */
172 @interface WebScriptObject : NSObject
173 {
174     WebScriptObjectPrivate *_private;
175 }
176
177 /*!
178     @method throwException:
179     @discussion Throws an exception in the current script execution context.
180     @result Either NO if an exception could not be raised, YES otherwise.
181 */
182 + (BOOL)throwException:(NSString *)exceptionMessage;
183
184 /*!
185     @method callWebScriptMethod:withArguments:
186     @param name The name of the method to call in the script environment.
187     @param args The arguments to pass to the script environment.
188     @discussion Calls the specified method in the script environment using the
189     specified arguments.
190     @result Returns the result of calling the script method.
191 */
192 - (id)callWebScriptMethod:(NSString *)name withArguments:(NSArray *)args;
193
194 /*!
195     @method evaluateWebScript:
196     @param script The script to execute in the target script environment.
197     @discussion The script will be executed in the target script environment.  The format
198     of the script is dependent of the target script environment.
199     @result Returns the result of evaluating the script in the script environment.
200 */
201 - (id)evaluateWebScript:(NSString *)script;
202
203 /*!
204     @method removeWebScriptKey:
205     @param name The name of the property to remove.
206     @discussion Removes the property from the object in the script environment.
207 */
208 - (void)removeWebScriptKey:(NSString *)name;
209
210 /*!
211     @method toString
212     @discussion Converts the target object to a string representation.  The coercion
213     of non string objects type is dependent on the script environment.
214     @result Returns the string representation of the object.
215 */
216 - (NSString *)stringRepresentation;
217
218 /*!
219     @method propertyAtIndex:
220     @param index The index of the property to return.  Index based access is dependent 
221     @discussion Gets the value of the property at the specified index.
222     @result The value of the property.
223 */
224 - (id)webScriptValueAtIndex:(unsigned int)index;
225
226 /*!
227     @method setPropertyAtIndex:value:
228     @param index The index of the property to set.
229     @param value The value of the property to set.
230     @discussion Sets the property value at the specified index.
231 */
232 - (void)setWebScriptValueAtIndex:(unsigned int)index value:(id)value;
233
234 /*!
235     @method setException:
236     @param description The description of the exception.
237     @discussion Raises an exception in the script environment in the context of the
238     current object.
239 */
240 - (void)setException: (NSString *)description;
241
242 @end
243
244
245 // WebUndefined --------------------------------------------------------------
246
247 /*!
248     @class WebUndefined
249 */
250 @interface WebUndefined : NSObject <NSCoding, NSCopying>
251 {
252 }
253
254 /*!
255     @method undefined
256     @result The WebUndefined shared instance.
257 */
258 + (WebUndefined *)undefined;
259
260 @end