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