libcore/as_function.h

   1 //
   2 //   Copyright (C) 2005, 2006, 2007, 2008, 2009, 2010 Free Software
   3 //   Foundation, Inc
   4 //
   5 // This program is free software; you can redistribute it and/or modify
   6 // it under the terms of the GNU General Public License as published by
   7 // the Free Software Foundation; either version 3 of the License, or
   8 // (at your option) any later version.
   9 //
  10 // This program is distributed in the hope that it will be useful,
  11 // but WITHOUT ANY WARRANTY; without even the implied warranty of
  12 // MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  13 // GNU General Public License for more details.
  14 //
  15 // You should have received a copy of the GNU General Public License
  16 // along with this program; if not, write to the Free Software
  17 // Foundation, Inc., 51 Franklin St, Fifth Floor, Boston, MA  02110-1301  USA
  18
  19 #ifndef GNASH_AS_FUNCTION_H
  20 #define GNASH_AS_FUNCTION_H
  21
  22 #include <string>
  23 #include "as_object.h" // for inheritance
  24
  25 // Forward declarations
  26 namespace gnash {
  27     class NativeFunction;
  28     class Global_as;
  29     template <typename T> class FunctionArgs;
  30 }
  31
  32 namespace gnash {
  33
  34 /// ActionScript Function, either builtin or SWF-defined
  35 //
  36 /// In ActionScript, every Function is also a class.
  37 /// The *exported interface* of the class is defined
  38 /// as a 'prototype' member of the function object.
  39 ///
  40 /// Any instance of the class defined by this function will
  41 /// inherit any member of the class 'prototype'.
  42 /// To have an object inherit from a class you can set its
  43 /// __proto__ member so to point to the class prototype, ie:
  44 ///
  45 ///   function MyClass() {}
  46 ///   MyClass.prototype.doit = function() { trace("doing it"; }
  47 ///
  48 ///   var myobj = new Object;
  49 ///   myobj.__proto__ = MyClass.prototype;
  50 ///
  51 /// The 'prototype' of a class must provide a 'constructor'
  52 /// member, which would point back to the Function object
  53 /// itself, which is used as the constructor, so given the
  54 /// code above you can assert that:
  55 ///
  56 ///   myobj.__proto__.constructor == MyClass
  57 ///
  58 /// This class will automatically setup the 'prototype' member
  59 /// if not explicitly provided (ie: will set 'constructor' so
  60 /// that it points to the instance).
  61 class as_function : public as_object
  62 {
  63 public:
  64
  65         /// Decrement refcount on the exported interface.
  66         virtual ~as_function() {}
  67
  68         // Avoid RTTI
  69         as_function* to_function() { return this; }
  70
  71         /// Function dispatch.  //
  72     /// Override from as_object, although as_objects cannot generally
  73     /// be called.
  74         virtual as_value call(const fn_call& fn) = 0;
  75
  76     virtual const std::string& stringValue() const;
  77
  78         /// Run this function as a constructor on an object
  79     //
  80     /// This function assigns various constructor properties and runs the
  81     /// constructor.
  82     //
  83     /// NB: This function does not make the object an 'instance of' the
  84     /// constructor, i.e. it does not assign a __proto__ property. For
  85     /// ActionScript compatibility, callers should ensure this is already
  86     /// done.
  87     //
  88     /// @param newobj   The object to construct. This will be used as the
  89     ///                 'this' object in the constructor.
  90         /// @param env      The environment to use for stack, local variables,
  91         ///                     registers and scope chain.
  92         /// @param args     Arguments for the constructor invocation
  93     /// @return         The constructed object. TODO: return void; currently
  94     ///                 there is a hack to cope with some remaining bogus
  95     ///                 constructors (Microphone and Camera), which
  96     ///                 necessitates returning a different object from the
  97     ///                 passed 'this' pointer.
  98     as_object* construct(as_object& newobj, const as_environment& env,
  99             FunctionArgs<as_value>& args);
 100
 101         /// Return true if this is a built-in class.
 102         virtual bool isBuiltin() { return false; }
 103
 104         /// Return the built-in Function constructor
 105         static NativeFunction* getFunctionConstructor();
 106
 107 protected:
 108
 109     /// Construct a function with no interface
 110         //
 111         /// For SWF>5 the function object will have derive from Function.
 112         ///
 113         as_function(Global_as& gl);
 114
 115 };
 116
 117
 118 /// Construct a new object from the given constructor
 119 //
 120 /// This function takes care of creating the new object and assigning the
 121 /// __proto__ property. The construct() function is then called with the
 122 /// new object as its 'this' object.
 123 //
 124 /// @param ctor     The constructor to run.
 125 /// @param env      The environment to use for the function call.
 126 /// @param arg      The arguments to pass to the constructor function.
 127 /// @return         A newly-created object constructed by the specified
 128 ///                 function.
 129 as_object* constructInstance(as_function& ctor, const as_environment& env,
 130         FunctionArgs<as_value>& args);
 131
 132 /// Initialize the global Function constructor
 133 void function_class_init(as_object& global, const ObjectURI& uri);
 134 void registerFunctionNative(as_object& global);
 135
 136 } // gnash namespace
 137
 138 #endif
 139