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