75fa3929cef459a40a2621c2d30d16cacb0e0815
[WebKit-https.git] / WebKit / Plugins.subproj / 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
10 // NSObject (WebScriptMethods) ----------------------------------------------------- 
11
12 /*
13     The methods in WebScriptMethods are optionally implemented by classes whose
14     interfaces are exported (wrapped) to a scripting environment in the context of WebKit.
15     The scripting environment currently supported by WebKit uses the JavaScript
16     language.
17     
18     Instances automatically reflect their interfaces in the scripting environment.  This
19     automatic reflection can be overriden using the class methods defined in the WebScriptMethods
20     informal protocol.
21     
22     Instances may also intercept property set/get operations and method invocations that are
23     made by the scripting environment, but not reflected.
24     
25     Not all methods are exposed.  Only those methods whose parameters and return
26     type meets the export criteria will exposed.  Valid types are ObjectiveC instances
27     and scalars.  Other types are not allowed.
28     
29     Types will be converted to appropriate types in the scripting environment.
30     Scalars and NSNumber will be converted to numbers.  NSString will be converted
31     to strings.  NSNull will be converted to null.  WebUndefined will be converted
32     to undefined.  WebScriptObjects will be unwrapped.  Instances of other classes
33     will be wrapped when passed to the script environment and unwrapped when
34     returned to ObjectiveC.  Similar conversion happens in the other direction.
35     
36     If an instance variable of an object is set directly from a script, and it is
37     an object, the previous value will be released and the new value will be retained.
38 */
39 @interface NSObject (WebScriptMethods)
40
41 /*!
42         @method scriptNameForSelector:
43         @param aSelector The selector that will be exposed to the script environment.
44     @discussion Use the returned string as the exported name for the selector
45     in the script environment.  It is the responsibility of the class to ensure
46     uniqueness of the returned name.  If nil is returned or this
47     method is not implemented the default name for the selector will
48     be used.  The default name concatenates the components of the
49     ObjectiveC selector name and replaces ':' with '_'.  '_' characters
50     are escaped with an additional '$', i.e. '_' becomes "$_".  '$' are
51     also escaped, i.e.
52         ObjectiveC name         Default script name
53         moveTo::                move__
54         moveTo_                 moveTo$_
55         moveTo$_                moveTo$$$_
56     @result Returns the name to be used to represent the specificed selector in the
57     scripting environment.
58 */
59 + (NSString *)scriptNameForSelector:(SEL)aSelector;
60
61 /*!
62     @method isSelectorExcludedFromScript:
63     @param aSelect  The selector the will be exposed to the script environment.
64     @discussion Return NO to prevent the selector appearing in the script
65     environment.  Return YES to expose the selector in the script environment.
66     If this method is not implemented on the class all the selector that match
67     the export criteria will be exposed.
68     @result Returns NO to hide the selector, YES to expose the selector.
69 */
70 + (BOOL)isSelectorExcludedFromScript:(SEL)aSelector;
71
72 /*!
73     @method scriptNameForProperty:
74         @param name The name of the instance variable that will be exposed to the
75     script enviroment.  Only that properties that meet the export criteria will
76     be exposed.
77     @discussion Provide an alternate name for a property.
78     @result Returns the name to be used to represent the specificed property in the
79     scripting environment.
80 */
81 + (NSString *)scriptNameForProperty:(const char *)name;
82
83 /*!
84     @method isPropertyExcludedFromScript:
85     @param name The name of the instance variable that will be exposed to the
86     scrip environment.
87     @discussion Return NO to exclude the property from visibility in the script environement.
88     Return YES to expose the instance varible to the script environment.
89     @result Returns NO to hide the property, YES to expose the property.
90 */
91 + (BOOL)isPropertyExcludedFromScript:(const char *)name;
92
93 /*!
94     @method setObject:forScriptProperty:exceptionMessage:
95     @param value The vale to be set for the property name.
96     @param name The name of the property being set.
97     @param exceptionMessage Set to the a message that will be used to contruct a script exception.
98     @discussion If a script attempts to set a property that is not an exposed
99     instance variable, setObject:forScriptProperty: will be called.  Setting the
100     *exceptionMessage to a non-nil value will cause an exception to be raised in the script
101     environment.  
102 */
103 - (void)setObject:(id)value forScriptProperty:(NSString *)name exceptionMessage:(NSString **)exceptionMessage;
104
105 /*!
106     @method objectForScriptProperty:exceptionMessage:
107     @param name
108     @param exceptionMessage Set to the a message that will be used to contruct a script exception.
109     @discussion If a script attempts to get a property that is not an exposed
110     instance variable, objectForScriptProperty: will be be called.
111     @result The value of the property.  Setting the *exceptionMessage to a non-nil value will
112     cause an exception to be raised in the script environment.  The return value will be
113     ignored if an exception message is set.
114 */
115 - (id)objectForScriptProperty:(NSString *)name exceptionMessage:(NSString **)exceptionMessage;
116
117 /*!
118     @method scriptInvocation:withArgs:exceptionMessage:
119     @param name The name of the method to invoke.
120     @param args The args to pass the method.
121     @param exceptionMessage Set to the a message that will be used to contruct a script exception.
122     @discussion If a script attempt to invoke a method that is not an exposed
123     method, scriptInvocation:withArgs: will be called.
124     @result The return value of the invocation.  The value will be converted as appropriate
125     for the script environment.  Setting the *exceptionMessage to a non-nil value will
126     cause an exception to be raised in the script environment.  The return value will be
127     ignored if an exception message is set.
128 */
129 - (id)scriptInvocation:(NSString *)name withArgs:(NSArray *)args exceptionMessage:(NSString **)exceptionMessage;
130
131 /*!
132     @method finalizeForScript
133     @discussion finalizeForScript is called on objects exposed to the script
134     environment just before the script environment is reset.  After calls to
135     finalizeForScript 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)finalizeForScript;
140
141 @end
142
143
144
145 // WebView (WebScriptMethods) --------------------------------------- 
146
147 @interface WebView (WebScriptMethods)
148
149 /*!
150     @method windowScriptObject
151     @discussion windowScriptObject return a WebScriptObject that represents the
152     window object from the script environment.
153     @result Returns the window object from the script environment.
154 */
155 - (WebScriptObject *)windowScriptObject;
156 @end
157
158
159
160 // WebScriptObject -------------------------------------------------- 
161
162 @class WebScriptObjectPrivate;
163
164 /*!
165     @class WebScriptObject
166     @discussion WebScriptObjects are used to wrap script objects passed from
167     script environments to ObjectiveC.  WebScriptObjects cannot be created
168     directly.  In normal uses of WebKit, you gain access to the script
169     environment using the "windowScriptObject" method on WebView.
170 */
171 @interface WebScriptObject : NSObject
172 {
173     WebScriptObjectPrivate *_private;
174 }
175
176 /*!
177     @method callScriptMethod:withArguments:
178     @param name The name of the method to call in the script environment.
179     @param args The arguments to pass to the script environment.
180     @discussion Calls the specified method in the script environment using the
181     specified arguments.
182     @result Returns the result of calling the script method.
183 */
184 - (id)callScriptMethod:(NSString *)name withArguments:(NSArray *)args;
185
186 /*!
187     @method evaluateScript:
188     @param script The script to execute in the target script environment.
189     @discussion The script will be executed in the target script environment.  The format
190     of the script is dependent of the target script environment.
191     @result Returns the result of evaluating the script in the script environment.
192 */
193 - (id)evaluateScript:(NSString *)script;
194
195 /*!
196     @method objectForScriptProperty:
197     @param name The name of the property to return.
198     @discussion Returns the property of the object from the script environment.
199     @result Returns the property of the object from the script environment.
200 */
201 - (id)objectForScriptProperty:(NSString *)name;
202
203 /*!
204     @method setObject:forScriptProperty:
205     @param name The name of the property to set.
206     @param value The value of the property.
207     @discussion Set the property of the object in the script environment.
208 */
209 - (void)setObject:(id)value forScriptProperty:(NSString *)name;
210
211 /*!
212     @method removeScriptProperty:
213     @param name The name of the property to remove.
214     @discussion Removes the property from the object in the script environment.
215 */
216 - (void)removeScriptProperty:(NSString *)name;
217
218 /*!
219     @method toString
220     @discussion Converts the target object to a string representation.  The coercion
221     of non string objects type is dependent on the script environment.
222     @result Returns the string representation of the object.
223 */
224 - (NSString *)toString;
225
226 /*!
227     @method propertyAtIndex:
228     @param index The index of the property to return.  Index based access is dependent 
229     @discussion Gets the value of the property at the specified index.
230     @result The value of the property.
231 */
232 - (id)scriptPropertyAtIndex:(unsigned int)index;
233
234 /*!
235     @method setPropertyAtIndex:value:
236     @param index The index of the property to set.
237     @param value The value of the property to set.
238     @discussion Sets the property value at the specified index.
239 */
240 - (void)setScriptPropertyAtIndex:(unsigned int)index value:(id)value;
241
242 /*!
243     @method setException:
244     @param description The description of the exception.
245     @discussion Raises an exception in the script environment.
246 */
247 - (void)setException: (NSString *)description;
248
249 @end
250
251
252
253 // WebUndefined --------------------------------------------------------------
254
255 /*!
256     @class WebUndefined
257 */
258 @interface WebUndefined : NSObject <NSCoding, NSCopying>
259
260 /*!
261     @method undefined
262     @result The WebUndefined shared instance.
263 */
264 + (WebUndefined *)undefined;
265
266 @end
267
268
269 @interface NSObject (WebFrameLoadDelegate) ...
270 /*!
271     @method webView:windowScriptObjectAvailable:
272     @abstract Notifies the delegate that the scripting object for a page is available.  This is called
273     before the page is loaded.  It may be useful to allow delegates to bind native objects to the window.
274     @param webView The webView sending the message.
275     @param windowScriptObject The WebScriptObject for the window in the scripting environment.
276 */
277 - (void)webView:(WebView *)webView windowScriptObjectAvailable:(WebScriptObject *)windowScriptObject;
278 @end
279
280
281 // NSObject (WebScriptablePlugin) -------------------------------------------- 
282
283 @interface NSObject (WebPlugin) ...
284 /*!
285     @method objectForScript
286     @discussion objectForScript is used to expose a plugin's API.  The methods of the
287     object are exposed to the script environment.  See the WebScriptMethod informal
288     protocol for more details.
289     @result Returns the object that exposes the plugin's interface.  The class of this
290     object can implement methods from the WebScriptMethods informal protocol.
291 */
292 - (id)objectForScript;
293 @end
294
295
296
297 // NSObject (WebPluginContainer) --------------------------------------------- 
298
299 @interface NSObject (WebPluginContainer) ...
300 /*!
301     @method webFrame
302     @discussion The webFrame method allows the plugin to access the WebFrame that
303     contains the plugin.  This method is optionally implemented on classes
304     that implement the WebPluginContainer protocol.
305     @result Return the WebFrame that contains the plugin.
306 */
307 - (WebFrame *)webFrame;
308 @end
309
310
311
312 // DOMObject ------------------------------------------------------------------
313 // All DOM objects may be manipulated using the formal DOM API, or indirectly via
314 // their scripting interface.  This requires a change in DOMObject's inheritance.
315
316 /*!
317         @class DOMObject
318         @discussion     All DOM objects may be manipulated using the formal DOM API, or indirectly via
319         their scripting interface.  This requires a change in DOMObject's inheritance.
320         ...
321 */
322 @interface DOMObject : WebScriptObject <NSCopying>
323 {
324     DOMObjectInternal *_internal;
325 }
326 ...
327 @end
328