Move WebCore into Source
[WebKit-https.git] / Source / WebCore / bindings / objc / WebScriptObject.h
1 /*
2  *  Copyright (C) 2004, 2006, 2007 Apple Inc. All rights reserved.
3  *
4  * Redistribution and use in source and binary forms, with or without
5  * modification, are permitted provided that the following conditions
6  * are met:
7  * 1. Redistributions of source code must retain the above copyright
8  *    notice, this list of conditions and the following disclaimer.
9  * 2. Redistributions in binary form must reproduce the above copyright
10  *    notice, this list of conditions and the following disclaimer in the
11  *    documentation and/or other materials provided with the distribution.
12  *
13  * THIS SOFTWARE IS PROVIDED BY APPLE INC. ``AS IS'' AND ANY
14  * EXPRESS OR IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE
15  * IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS FOR A PARTICULAR
16  * PURPOSE ARE DISCLAIMED.  IN NO EVENT SHALL APPLE INC. OR
17  * CONTRIBUTORS BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL, SPECIAL,
18  * EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
19  * PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR
20  * PROFITS; OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY
21  * OF LIABILITY, WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT
22  * (INCLUDING NEGLIGENCE OR OTHERWISE) ARISING IN ANY WAY OUT OF THE USE
23  * OF THIS SOFTWARE, EVEN IF ADVISED OF THE POSSIBILITY OF SUCH DAMAGE. 
24  */
25
26 #import <Foundation/Foundation.h>
27 #import <JavaScriptCore/JSBase.h>
28 #import <JavaScriptCore/WebKitAvailability.h>
29
30 #if WEBKIT_VERSION_MAX_ALLOWED >= WEBKIT_VERSION_1_3
31
32 // NSObject (WebScripting) -----------------------------------------------------
33
34 /*
35     Classes may implement one or more methods in WebScripting to export interfaces 
36     to WebKit's JavaScript environment.
37
38     By default, no properties or functions are exported. A class must implement 
39     +isKeyExcludedFromWebScript: and/or +isSelectorExcludedFromWebScript: to 
40     expose selected properties and methods, respectively, to JavaScript.
41
42     Access to exported properties is done using KVC -- specifically, the following
43     KVC methods:
44
45         - (void)setValue:(id)value forKey:(NSString *)key
46         - (id)valueForKey:(NSString *)key
47
48     Clients may also intercept property set/get operations that are made by the 
49     scripting environment for properties that are not exported. This is done using 
50     the KVC methods:
51
52         - (void)setValue:(id)value forUndefinedKey:(NSString *)key
53         - (id)valueForUndefinedKey:(NSString *)key
54     
55     Similarly, clients may intercept method invocations that are made by the
56     scripting environment for methods that are not exported. This is done using
57     the method:
58
59         - (id)invokeUndefinedMethodFromWebScript:(NSString *)name withArguments:(NSArray *)args;
60
61     If clients need to raise an exception in the script environment
62     they can call [WebScriptObject throwException:]. Note that throwing an
63     exception using this method will only succeed if the method that throws the exception
64     is being called within the scope of a script invocation.
65
66     Not all methods are exposed. Only those methods whose parameters and return
67     type meets the export criteria are exposed. Valid types are Objective-C instances
68     and scalars. Other types are not allowed.
69
70     Types will be converted automatically between JavaScript and Objective-C in 
71     the following manner:
72
73     JavaScript              ObjC
74     ----------              ----------
75     null            =>      nil
76     undefined       =>      WebUndefined
77     number          =>      NSNumber
78     boolean         =>      CFBoolean
79     string          =>      NSString
80     object          =>      id
81     
82     The object => id conversion occurs as follows: if the object wraps an underlying
83     Objective-C object (i.e., if it was created by a previous ObjC => JavaScript conversion),
84     then the underlying Objective-C object is returned. Otherwise, a new WebScriptObject
85     is created and returned.
86     
87     The above conversions occur only if the declared ObjC type is an object type. 
88     For primitive types like int and char, a numeric cast is performed.
89
90     ObjC                    JavaScript
91     ----                    ----------
92     NSNull          =>      null
93     nil             =>      undefined
94     WebUndefined    =>      undefined
95     CFBoolean       =>      boolean
96     NSNumber        =>      number
97     NSString        =>      string
98     NSArray         =>      array object
99     WebScriptObject =>      object
100
101     The above conversions occur only if the declared ObjC type is an object type. 
102     For primitive type like int and char, a numeric cast is performed.
103 */
104 @interface NSObject (WebScripting)
105
106 /*!
107     @method webScriptNameForSelector:
108     @param selector The selector that will be exposed to the script environment.
109     @discussion Use the returned string as the exported name for the selector
110     in the script environment. It is the responsibility of the class to ensure
111     uniqueness of the returned name. If nil is returned or this
112     method is not implemented the default name for the selector will
113     be used. The default name concatenates the components of the
114     Objective-C selector name and replaces ':' with '_'.  '_' characters
115     are escaped with an additional '$', i.e. '_' becomes "$_". '$' are
116     also escaped, i.e.
117         Objective-C name        Default script name
118         moveTo::                move__
119         moveTo_                 moveTo$_
120         moveTo$_                moveTo$$$_
121     @result Returns the name to be used to represent the specified selector in the
122     scripting environment.
123 */
124 + (NSString *)webScriptNameForSelector:(SEL)selector;
125
126 /*!
127     @method isSelectorExcludedFromWebScript:
128     @param selector The selector the will be exposed to the script environment.
129     @discussion Return NO to export the selector to the script environment.
130     Return YES to prevent the selector from being exported to the script environment. 
131     If this method is not implemented on the class no selectors will be exported.
132     @result Returns YES to hide the selector, NO to export the selector.
133 */
134 + (BOOL)isSelectorExcludedFromWebScript:(SEL)selector;
135
136 /*!
137     @method webScriptNameForKey:
138     @param name The name of the instance variable that will be exposed to the
139     script environment. Only instance variables that meet the export criteria will
140     be exposed.
141     @discussion Provide an alternate name for a property.
142     @result Returns the name to be used to represent the specified property in the
143     scripting environment.
144 */
145 + (NSString *)webScriptNameForKey:(const char *)name;
146
147 /*!
148     @method isKeyExcludedFromWebScript:
149     @param name The name of the instance variable that will be exposed to the
150     script environment.
151     @discussion Return NO to export the property to the script environment.
152     Return YES to prevent the property from being exported to the script environment.
153     @result Returns YES to hide the property, NO to export the property.
154 */
155 + (BOOL)isKeyExcludedFromWebScript:(const char *)name;
156
157 /*!
158     @method invokeUndefinedMethodFromWebScript:withArguments:
159     @param name The name of the method to invoke.
160     @param arguments The arguments to pass the method.
161     @discussion If a script attempts to invoke a method that is not exported, 
162     invokeUndefinedMethodFromWebScript:withArguments: will be called.
163     @result The return value of the invocation. The value will be converted as appropriate
164     for the script environment.
165 */
166 - (id)invokeUndefinedMethodFromWebScript:(NSString *)name withArguments:(NSArray *)arguments;
167
168 /*!
169     @method invokeDefaultMethodWithArguments:
170     @param arguments The arguments to pass the method.
171     @discussion If a script attempts to call an exposed object as a function, 
172     this method will be called.
173     @result The return value of the call. The value will be converted as appropriate
174     for the script environment.
175 */
176 - (id)invokeDefaultMethodWithArguments:(NSArray *)arguments;
177
178 /*!
179     @method finalizeForWebScript
180     @discussion finalizeForScript is called on objects exposed to the script
181     environment just before the script environment garbage collects the object.
182     Subsequently, any references to WebScriptObjects made by the exposed object will
183     be invalid and have undefined consequences.
184 */
185 - (void)finalizeForWebScript;
186
187 @end
188
189
190 // WebScriptObject --------------------------------------------------
191
192 @class WebScriptObjectPrivate;
193 @class WebFrame;
194
195 /*!
196     @class WebScriptObject
197     @discussion WebScriptObjects are used to wrap script objects passed from
198     script environments to Objective-C. WebScriptObjects cannot be created
199     directly. In normal uses of WebKit, you gain access to the script
200     environment using the "windowScriptObject" method on WebView.
201
202     The following KVC methods are commonly used to access properties of the
203     WebScriptObject:
204
205         - (void)setValue:(id)value forKey:(NSString *)key
206         - (id)valueForKey:(NSString *)key
207
208     As it possible to remove attributes from web script objects, the following
209     additional method augments the basic KVC methods:
210
211         - (void)removeWebScriptKey:(NSString *)name;
212
213     Also, since the sparse array access allowed in script objects doesn't map well
214     to NSArray, the following methods can be used to access index based properties:
215
216         - (id)webScriptValueAtIndex:(unsigned)index;
217         - (void)setWebScriptValueAtIndex:(unsigned)index value:(id)value;
218 */
219 @interface WebScriptObject : NSObject
220 {
221     WebScriptObjectPrivate *_private;
222 }
223
224 /*!
225     @method throwException:
226     @discussion Throws an exception in the current script execution context.
227     @result Either NO if an exception could not be raised, YES otherwise.
228 */
229 + (BOOL)throwException:(NSString *)exceptionMessage;
230
231 /*!
232     @method JSObject
233     @result The equivalent JSObjectRef for this WebScriptObject.
234     @discussion Use this method to bridge between the WebScriptObject and 
235     JavaScriptCore APIs.
236 */
237 - (JSObjectRef)JSObject WEBKIT_OBJC_METHOD_ANNOTATION(AVAILABLE_WEBKIT_VERSION_3_0_AND_LATER);
238
239 /*!
240     @method callWebScriptMethod:withArguments:
241     @param name The name of the method to call in the script environment.
242     @param arguments The arguments to pass to the script environment.
243     @discussion Calls the specified method in the script environment using the
244     specified arguments.
245     @result Returns the result of calling the script method.
246     Returns WebUndefined when an exception is thrown in the script environment.
247 */
248 - (id)callWebScriptMethod:(NSString *)name withArguments:(NSArray *)arguments;
249
250 /*!
251     @method evaluateWebScript:
252     @param script The script to execute in the target script environment.
253     @discussion The script will be executed in the target script environment. The format
254     of the script is dependent of the target script environment.
255     @result Returns the result of evaluating the script in the script environment.
256     Returns WebUndefined when an exception is thrown in the script environment.
257 */
258 - (id)evaluateWebScript:(NSString *)script;
259
260 /*!
261     @method removeWebScriptKey:
262     @param name The name of the property to remove.
263     @discussion Removes the property from the object in the script environment.
264 */
265 - (void)removeWebScriptKey:(NSString *)name;
266
267 /*!
268     @method stringRepresentation
269     @discussion Converts the target object to a string representation. The coercion
270     of non string objects type is dependent on the script environment.
271     @result Returns the string representation of the object.
272 */
273 - (NSString *)stringRepresentation;
274
275 /*!
276     @method webScriptValueAtIndex:
277     @param index The index of the property to return.
278     @discussion Gets the value of the property at the specified index.
279     @result The value of the property. Returns WebUndefined when an exception is
280     thrown in the script environment.
281 */
282 - (id)webScriptValueAtIndex:(unsigned)index;
283
284 /*!
285     @method setWebScriptValueAtIndex:value:
286     @param index The index of the property to set.
287     @param value The value of the property to set.
288     @discussion Sets the property value at the specified index.
289 */
290 - (void)setWebScriptValueAtIndex:(unsigned)index value:(id)value;
291
292 /*!
293     @method setException:
294     @param description The description of the exception.
295     @discussion Raises an exception in the script environment in the context of the
296     current object.
297 */
298 - (void)setException:(NSString *)description;
299
300 @end
301
302
303 // WebUndefined --------------------------------------------------------------
304
305 /*!
306     @class WebUndefined
307 */
308 @interface WebUndefined : NSObject <NSCoding, NSCopying>
309
310 /*!
311     @method undefined
312     @result The WebUndefined shared instance.
313 */
314 + (WebUndefined *)undefined;
315
316 @end
317
318 #endif