[Top][All Lists]
[Date Prev][Date Next][Thread Prev][Thread Next][Date Index][Thread Index]
[Gnash-commit] gnash ChangeLog doc/C/internals.xml doc/C/Makef...
|
From: |
Ann Barcomb |
|
Subject: |
[Gnash-commit] gnash ChangeLog doc/C/internals.xml doc/C/Makef... |
|
Date: |
Mon, 19 Mar 2007 14:40:13 +0000 |
CVSROOT: /sources/gnash
Module name: gnash
Changes by: Ann Barcomb <ann> 07/03/19 14:40:13
Modified files:
. : ChangeLog
doc/C : internals.xml Makefile.am
Added files:
doc/C : actionscript.xml
doc/C/actionscript: main.xml
Log message:
ActionScript has been removed from the Gnash manual.
A new ActionScript manual has been created. Most of
the material has been rewritten and incorporates Sandro's
feedback on the previous version.
CVSWeb URLs:
http://cvs.savannah.gnu.org/viewcvs/gnash/ChangeLog?cvsroot=gnash&r1=1.2624&r2=1.2625
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/internals.xml?cvsroot=gnash&r1=1.59&r2=1.60
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/Makefile.am?cvsroot=gnash&r1=1.33&r2=1.34
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/actionscript.xml?cvsroot=gnash&rev=1.1
http://cvs.savannah.gnu.org/viewcvs/gnash/doc/C/actionscript/main.xml?cvsroot=gnash&rev=1.1
Patches:
Index: ChangeLog
===================================================================
RCS file: /sources/gnash/gnash/ChangeLog,v
retrieving revision 1.2624
retrieving revision 1.2625
diff -u -b -r1.2624 -r1.2625
--- ChangeLog 19 Mar 2007 14:10:21 -0000 1.2624
+++ ChangeLog 19 Mar 2007 14:40:12 -0000 1.2625
@@ -1,3 +1,10 @@
+2007-03-19 Ann Barcomb <address@hidden>
+
+ * ActionScript has been removed from the Gnash manual.
+ A new ActionScript manual has been created. Most of
+ the material has been rewritten and incorporates Sandro's
+ feedback on the previous version.
+
2007-03-19 Bastiaan Jacques <address@hidden>
* testsuite/misc-ming.all/ming_utils.h: Add Ming defines available only
in
Index: doc/C/internals.xml
===================================================================
RCS file: /sources/gnash/gnash/doc/C/internals.xml,v
retrieving revision 1.59
retrieving revision 1.60
diff -u -b -r1.59 -r1.60
--- doc/C/internals.xml 5 Mar 2007 21:35:27 -0000 1.59
+++ doc/C/internals.xml 19 Mar 2007 14:40:12 -0000 1.60
@@ -335,477 +335,6 @@
</sect2>
- <sect2 id="as">
- <title>ActionScript Support</title>
-
- <sect3 id="asadd">
- <title>Adding New ActionScript Classes</title>
-
- <para>
- Adding a new ActionScript class is a relatively simple
- process. A new file is created to hold the code, with an
- associated header file. The file name is usually the name of
- the ActionScript class itself, something like
- <emphasis>XML</emphasis>. All implementations are written in
- <emphasis>C++</emphasis>. In the CVS source tree for Gnash, there is a
- utility file called <emphasis>gen-asclass.sh</emphasis> which
- can be used to generate a header file and a C++ source file template
- for an ActionScript class. Templates have already been generated
- for all documented ActionScript classes.
- </para>
-
- <sect4 id="defclass">
- <title>Defining a new ActionScript Class</title>
-
- <para>
- The header file defines the class and its methods. The symbol
- name used to look up the code which implements the ActionScript
- class is added later.
- </para>
-
- <para>
- Each class needs an associated version which is a derived form
- of the <emphasis>as_object</emphasis> class used to internally
- represent objects in Gnash. At its simplest, this structure
- just encapsulates an object of the desired class.
-
- <programlisting>
- class Foo {
- public:
- foo() {};
- ~foo() {};
- bool GetBar() { return _bar; }
- private:
- bool _bar;
- }
- struct foo_as_object : public gnash::as_object {
- Foo obj;
- }
- </programlisting>
- The <emphasis>obj</emphasis> is an instantiation of the data for
- this object. It isn't required unless this object needs
- internal data that has to stay resident in the player.
- </para>
-
- <para>
- Whenever this object is being handed the code for this
- class, it is initially accessed by its derived
- binding. Internal data for this object can be accessed
- through the <emphasis>obj</emphasis>.
-
- <programlisting>
- // ensureFoo(as_object*) should be defined as
- // checking the type of given pointer being
- // a foo_as_object, throwing an ActionException
- // if this is not the case.
- foo_as_object *foo = ensureFoo(fn.this_ptr);
- bool result = foo->obj.GetBar();
- </programlisting>
-
- </para>
-
- <para>
- A more complex example might be to add hooks to the
- constructor and destructor for the class to keep track of
- memory allocations and cleanup. In this case only a debug
- statement is printed.
-
- <programlisting>
- struct foo_as_object : public gnash::as_object {
- Foo obj;
- foo_as_object() {
- log_msg("\tCreating foo_as_object at %p \n", this);
- };
- ~foo_as_object() {
- log_msg("\tDeleting foo_as_object at %p \n", this);
- };
- }:
- </programlisting>
- </para>
-
- <para>
- An even more complex example might be to add hooks to how
- the list of member of a class is kept. The element
- <emphasis>m_members</emphasis>, is a list of each symbol name and its
- associated code. Normally this is kept internally within the
- interpreter engine, but in this example for certain methods we
- want to return a pointer to itself, instead of getting the data
- from the list.
-
- <programlisting>
- struct xml_as_object : public gnash::as_object {
- XML obj;
- xmlnode_as_object() {
- log_msg("\tCreating xmlnode_as_object at %p \n", this);
- };
- ~xmlnode_as_object() {
- log_msg("\tDeleting xmlnode_as_object at %p \n", this);
- };
- virtual bool get_member(const tu_stringi& name, as_value*
val) {
- if ((name == "firstChild") || (name == "childNodes")) {
- val->set_as_object(this);
- return true;
- }
- if (m_members.get(name, val) == false) {
- if (m_prototype != NULL) {
- return m_prototype->get_member(name, val);
- }
- return false;
- }
- return true;
- }
- };
- </programlisting>
- </para>
- </sect4>
-
- <sect4 id="instclass">
- <title>Instantiating a new Class</title>
-
- <para>
- To add a new object, create an init method similar to the
- one below, then call it in the constructor in
- <emphasis>Global.cpp</emphasis> using the syntax
- <emphasis>xml_class_init(*this);</emphasis>
- <programlisting>
- // Example init method
-
- void xml_class_init(as_object& global)
- {
- // GNASH_REPORT_FUNCTION;
- // This is going to be the global XML "class"/"function"
- static boost::intrusive_ptr<builtin_function> cl;
-
- if ( cl == NULL ) {
- cl=new builtin_function(&xml_new, getXMLInterface());
- // replicate all interface to class, to be able to access
- // all methods as static functions
- attachXMLInterface(*cl);
- }
-
- // Register _global.String
- global.init_member("XML", cl.get());
-
- }
- </programlisting>
- </para>
- <para>
- The function used to instantiate a new object is passed the
- creation data in a <emphasis>fn_call</emphasis> data structure. This
is
- used to pass data both into and returned from this function.
- </para>
-
- <para>
- The <emphasis>fn_call</emphasis> data structure has several methods
- for operating on the data for the
- function. <emphasis>fn_call::nargs</emphasis> is a variable that
- specifies how many arguments are being passed in. All the
- arguments are on a stack. To pop an argument off the stack,
- use <emphasis>fn.env->top(0)</emphasis>. In this case popping the
- first argument off the stack.
- </para>
-
- <para>
- The object popped off the stack also has its own methods. The
- main one of interest is <emphasis>is_function</emphasis>,
- <emphasis>is_as_function</emphasis>, <emphasis>is_string</emphasis>,
- and so on. A list of these methods, which indicate if a argument
- is of a specified type, can be found in
- <emphasis>as_value.h</emphasis>.
- <programlisting>
- if (fn.env->top(0).is_string()) {
- ...
- }
- </programlisting>
- Another option is to use <emphasis>typeOf</emphasis>, which will
- return a string describing the argument type.
- </para>
-
- <para>
- The supported data types for an object are
- <emphasis>NULLTYPE</emphasis>
- <emphasis>BOOLEAN</emphasis>, <emphasis>STRING</emphasis>,
- <emphasis>NUMBER</emphasis>, <emphasis>OBJECT</emphasis>,
- <emphasis>C_FUNCTION</emphasis>, <emphasis>AS_FUNCTION</emphasis>,
- and <emphasis>MOVIECLIP</emphasis>. Because
- they are defined as part of the as_value class, they need to
- always have the class name prefixed to use these as a
- constant. You can retrieve the value of an
- <emphasis>as_value</emphasis> using the conversion methods. For
- example, <emphasis>to_std_string</emphasis> returns the value
- as a std::string. Similarly,
- <emphasis>to_number</emphasis> would return this same value as a
- <emphasis>double.</emphasis>
- </para>
-
- <para>
- To add methods to the class, a new class needs to be
- instantiated as an object. Each ActionScript object can
- have child methods, which are attached to the object in a
- manner similar to how the object itself is initialized using
- <emphasis>init_member</emphasis>.
- <programlisting>
- xml_obj = new xml_as_object;
- xml_obj->init_member("load", new builtin_function(xml_load));
- </programlisting>
- </para>
- <para>
- To activate the object within the interpreter and increment
- the reference count of the object, the new object should
- be returned (in ActionScript) by the function. This should
- be done using the <emphasis>fn_call</emphasis> typed parameter.
- <programlisting>
- fn.result->set_as_object(xml_obj);
- </programlisting>
- </para>
-
- <para>
- A complete example of a function used to instantiate a new
- ActionScript object is as follows. This example also calls
- internally defined methods in the class, in this case to
- process and XML file, and to create the parsed XML tree.
-
- <programlisting>
- void
- xml_new(const fn_call& fn)
- {
- as_value inum;
- XML *xml_obj;
-
- if (fn.nargs > 0) {
- as_object* obj = fn.env->top(0).to_object();
-
- if (! obj ) {
- xml_obj = new XML;
- tu_string datain = fn.env->top(0).to_tu_string();
- xml_obj->parseXML(datain);
- xml_obj->setupFrame(xml_obj, xml_obj->firstChild(),
true);
- } else {
- assert(dynamic_cast<XML*>(obj));
- XML* xml_obj = (XML*)obj;
- fn.result->set_as_object(xml_obj);
- return;
- }
- } else {
- xml_obj = new XML;
- }
-
- fn.result->set_as_object(xml_obj);
- }
-
- </programlisting>
- </para>
-
- <sect5 id="defprop">
- <title>Adding a Property</title>
-
- <para>
- Adding a new new property to an object is similar to
- adding a callback for a method. Instead of using a C
- function, a string or number is used.
-
- <programlisting>
- as_obj->init_member("nodeName", as_value("HelloWorld"));
- </programlisting>
-
- When a Flash movie looks this up as a property, the value
- can be found directly without a function call.
- This scrap of ActionScript code as compiled by
- Ming's <emphasis>makeswf</emphasis> compiler shows the
- difference.
-
- <programlisting>
- // Call the hasChildNodes() function
- if (node.hasChildNodes() == true) {
- trace("CHILDREN");
- }
- // Get the value of the nodeName property
- if (node.nodeName == "HelloWorld") {
- trace("MATCHED");
- }
- </programlisting>
-
- </para>
- </sect5>
- </sect4>
- </sect3>
-
- <sect3 id="parameters">
- <title>Parameter Passing</title>
-
- <para>
- Parameters are passed to the callback functions for a class's
- methods and properties using the <emphasis>fn_call</emphasis> data
- structure. This data structure contains all the incoming
- parameters for a callback, and contains the final
- result from the callback to be passed back into the
- player.
- </para>
-
- <sect4 id="parain">
- <title>Getting Parameter Data</title>
- <para>
- Parameter data is passed on the stack in a similar way to
- any function call in any language. There are several fields
- of the <emphasis>fn_call</emphasis> data structure that get used in
- this example:
-
- <programlisting>
- xml_as_object *xml_obj = static_cast < xml_as_object* >
(fn.this_ptr);
- if (fn.nargs) {
- filespec =
fn.env->bottom(fn.first_arg_bottom_index).to_string();
- }
- </programlisting>
- </para>
- <para>
- Using the <emphasis>fn</emphasis> variable which was passed as the
- sole parameter of the callback, we can access the data. The
- <emphasis>fn.this_ptr</emphasis> returns a reference to the class
- which is invoking this method. This is how the object data
- can be retrieved. The <emphasis>fn.nargs</emphasis> is a count of
- how many objects are being passed into the callback.
- </para>
-
- <para>
- The current stack of the player is passed in via the
- <emphasis>fn.env</emphasis> field. This is used to access the data
- passes to this callback. To find the location of this
- particular stack frame, the
- <emphasis>fn.first_arg_bottom_index</emphasis> field is used to
- point to the stack frame. More detail on the environment stack
- can <link linkend="envstack">be found here.</link>.
- </para>
-
- <para>
- For this example, the stack has a
- <emphasis>as_environment::top()</emphasis> and a
- <emphasis>as_environment::bottom()</emphasis> that are used to pull
- arguments off the stack. When using
- <emphasis>fn.first_arg_bottom_index</emphasis>, the
- <emphasis>as_environment::bottom()</emphasis> method should be used
- as in the example.
- </para>
-
- <para>
- The top of the stack for this frame can also be accessed
- using the <emphasis>as_environment::top()</emphasis> method. Top
- takes an integer index as to which value to retrieve,
- </para>
-
- <programlisting>
- if (fn.nargs > 0) {
- name = fn.env->top(0).to_string());
- }
- </programlisting>
-
- <para>
- If the type of the object is needed, the methods
- <emphasis>is_function</emphasis>,
<emphasis>is_as_function</emphasis>,
- and so on can be used. A list of these methods can be found in
- <emphasis>as_value.h</emphasis>.
- More information about types of values can be found in the
- <link linkend="handval">Handling Values</link> section of
- this manual.
- </para>
-
- <programlisting>
- if (fn.nargs > 0) {
- if (fn.env->top(0).is_string()) {
- name = fn.env->top(0).to_string);
- }
- if (fn.env->top(0).is_number()) {
- value = fn.env->top(0).to_number);
- }
- }
- </programlisting>
-
- <para>
- The internal data for this object can be accessed through
- the base class. Any data set using this object will stay
- resident in the player.
-
- <programlisting>
- foo_as_object *foo_obj = static_cast < foo_as_object* >
(fn.this_ptr);
- bool bar = foo_obj->obj.GetBar();
- </programlisting>
-
- </para>
-
- </sect4>
-
- <sect4 id="paramout">
- <title>Returning Data</title>
-
- <para>
- Data is also returned in the data structure passed to the
- callback. This example calls a method of the object passed
- in on the stack, and then sets the return code to be the
- return code of calling the method.
- <programlisting>
- // Set the argument to the function event handler based on
- // whether the load was successful or failed.
- ret = xml_obj->obj.load(filespec);
- fn.result->set_bool(ret);
- </programlisting>
- </para>
-
- <para>
- The <emphasis>result</emphasis> field of the <emphasis>fn</emphasis>
- variable is a <emphasis>gnash::as_value</emphasis> object, so it's
- possible to set the value of several data types.
- </para>
-
- <para>
- Here is a short list of the most often used data types
- returned from callbacks:
- <variablelist>
- <varlistentry>
- <term>as_value::set_bool()</term>
- <listitem>
- <para>
- Set the result to a boolean value.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::set_int()</term>
- <listitem>
- <para>
- Set the result to an integer value.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::set_double()</term>
- <listitem>
- <para>
- Set the result to a floating point double value.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::set_string()</term>
- <listitem>
- <para>
- Set the result to a <emphasis>const char*</emphasis> value.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::set_as_object()</term>
- <listitem>
- <para>
- Set the result to an object value.
- </para>
- </listitem>
- </varlistentry>
- </variablelist>
- </para>
- </sect4>
-
- </sect3>
- </sect2>
-
&opcodes;
<sect2 id="engine">
@@ -827,287 +356,6 @@
FIXME:
</para>
</sect3>
-
- <sect3 id="handval">
- <title>Handling Values</title>
-
- <para>
- All of the main values in Gnash as used by the interpreter,
- are usually an <emphasis>as_value</emphasis> class. This is a generic
- object to hold data. The supported data types for an object
- are <emphasis>BOOLEAN</emphasis>, <emphasis>STRING</emphasis>,
- <emphasis>NUMBER</emphasis>, <emphasis>OBJECT</emphasis>,
- <emphasis>C_FUNCTION</emphasis>, <emphasis>AS_FUNCTION</emphasis>. You
can
- retrieve the value of an <emphasis>as_value</emphasis> using the
- conversion methods. For example, <emphasis>to_tu_string</emphasis>
- returns the value as string using the Gnash small STL
- library. Similarly, <emphasis>to_number</emphasis> would return this
- same value as a <emphasis>double.</emphasis>
- </para>
-
- <para>
- <emphasis>as_value</emphasis> is often used as the initializer for a
- property or the data for a callback. This is done so the
- type of the object is specified along with the data.
-
- <programlisting>
- // Set the callback for a new XML object
- obj->set_member("XML", as_value(xml_new));
-
- // Set the property to the value of text
- obj->set_member("nodeName", as_value(text));
-
- // Set the property to null, but at least it exists
- obj->set_member("nodeValue", as_value(""));
- </programlisting>
- </para>
-
- <para>
-
- <programlisting>
- // Get the name of an object
- name = fn.env->top(0).to_string());
-
- // Get the value of an object
- value = fn.env->top(1).to_number);
-
- </programlisting>
- </para>
-
- <sect4 id="valset">
- <title>as_value set methods</title>
-
- <para>
- While <emphasis>as_value</emphasis> allows you to use any of the
- supported data types when invoking the constructor (as in
- the prior example). This is a common way to set the data
- and type of a value. Often it's necessary to set the value
- of an object after it is created, or to change the
- existing value. The <emphasis>=</emphasis> operator is also
- supported, so it is also possible to set a value and its
- type this way as well. I sort of lean towards the explicit
- style of setting a type, so here's all the methods that
- explicitly set a value.
- </para>
-
- <variablelist>
- <varlistentry>
- <term>as_value::set_bool(bool)</term>
- <listitem>
- <para>
- Set the value to a boolean value.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::set_int(int)</term>
- <listitem>
- <para>
- Set the value to an integer value.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::set_double(double)</term>
- <listitem>
- <para>
- Set the value to a floating point double value.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::set_string(const char*)</term>
- <listitem>
- <para>
- Set the value to a <emphasis>const char*</emphasis> value.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::set_tu_string(int)</term>
- <listitem>
- <para>
- Set the value to an tu_string value. Once all the
- containers have been converted to using standard
- STL classes, this method will go away.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::set_nan(int)</term>
- <listitem>
- <para>
- Set the value to an NaN (Not a Number) value.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::set_null()</term>
- <listitem>
- <para>
- Set the value so this is a <emphasis>NULL</emphasis>
- object.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::set_undefined()</term>
- <listitem>
- <para>
- Set the value so this is an <emphasis>undefined</emphasis>
- object.
- </para>
- </listitem>
- </varlistentry>
-
-
- <varlistentry>
- <term>as_value::set_as_object_interface(as_object *)</term>
- <listitem>
- <para>
- Set the value to an object value.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>as_value::set_as_c_function_ptr(int)</term>
- <listitem>
- <para>
- Set the value.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::set_function_as_object(int)</term>
- <listitem>
- <para>
- Set the value.
- </para>
- </listitem>
- </varlistentry>
-
-
- </variablelist>
- </sect4>
-
- <sect4 id="valget">
- <title>as_value get methods</title>
-
- <para>
- </para>
-
- <variablelist>
- <varlistentry>
- <term>as_value::to_bool(bool)</term>
- <listitem>
- <para>
- Return the value as a boolean.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::to_number()</term>
- <listitem>
- <para>
- Return the value as a number object.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::to_string()</term>
- <listitem>
- <para>
- Return the value as a <emphasis>const char*</emphasis>.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::to_tu_string(int)</term>
- <listitem>
- <para>
- Return the value as a tu_string value. Once all the
- containers have been converted to using standard
- STL classes, this method will go away.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::is_nan()</term>
- <listitem>
- <para>
- Return true if set to NaN (Not a Number).
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::is_inf()</term>
- <listitem>
- <para>
- Returns true if the number has an infinite value.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::is_finite()</term>
- <listitem>
- <para>
- Returns true if the number has an finite value.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>as_value::to_object()</term>
- <listitem>
- <para>
- Return the value as an
- <emphasis>as_object_interface</emphasis>. This is often used
- as the "handle" for an object within Gnash. You
- would use this when you need to do
- <emphasis>set_member()</emphasis> or
- <emphasis>get_member()</emphasis> operations.
- </para>
- </listitem>
- </varlistentry>
-
- <varlistentry>
- <term>as_value::to_c_function()</term>
- <listitem>
- <para>
- Return the value as a C function pointer.
- </para>
- </listitem>
- </varlistentry>
- <varlistentry>
- <term>as_value::to_as_function()</term>
- <listitem>
- <para>
- Return the value as an ActionScript function.
- </para>
- </listitem>
- </varlistentry>
-
-
- </variablelist>
- </sect4>
-
- </sect3>
-
- <sect3 id="handobj">
- <title>Handling Objects</title>
- <para>
- FIXME:
- </para>
- </sect3>
-
- <sect3 id="envstack">
- <title>The Environment Stack</title>
- <para>
- FIXME:
- </para>
- </sect3>
-
</sect2>
<sect2 id="soundhandlers">
Index: doc/C/Makefile.am
===================================================================
RCS file: /sources/gnash/gnash/doc/C/Makefile.am,v
retrieving revision 1.33
retrieving revision 1.34
diff -u -b -r1.33 -r1.34
--- doc/C/Makefile.am 16 Feb 2007 05:34:21 -0000 1.33
+++ doc/C/Makefile.am 19 Mar 2007 14:40:12 -0000 1.34
@@ -84,12 +84,13 @@
#noinst_SCRIPT = gen-doc.sh
dist_man_MANS = gnash.1
-html: gnash.html
-pdf: gnash.pdf
+html: gnash.html actionscript.html
+pdf: gnash.pdf actionscript.pdf
man: gnash.1
-texi: gnash.texi
-info: gnash.info
+texi: gnash.texi actionscript.texi
+info: gnash.info actionscript.info
gnash.pdf gnash.html gnash.texi: $(xml_files)
+actionscript.pdf actionscript.html actionscript.texi: actionscript.xml
actionscript/main.xml
SUFFIXES = .xml .html .texi .pdf .info .1 .fo
@@ -97,8 +98,11 @@
$(xml_files) \
$(omffile) \
gnash.texi \
+ actionscript.texi \
gnash-man.xml \
+ actionscript.info \
gnash.info \
+ actionscript.html \
gnash.html \
gnash.1
Index: doc/C/actionscript.xml
===================================================================
RCS file: doc/C/actionscript.xml
diff -N doc/C/actionscript.xml
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ doc/C/actionscript.xml 19 Mar 2007 14:40:12 -0000 1.1
@@ -0,0 +1,126 @@
+<?xml version="1.0"?>
+<!DOCTYPE article PUBLIC "-//OASIS//DTD DocBook XML V4.1.2//EN"
+ "http://www.oasis-open.org/docbook/xml/4.1.2/docbookx.dtd"; [
+ <!ENTITY legal SYSTEM "legal.xml">
+ <!ENTITY fdl-app SYSTEM "fdl-appendix.xml">
+ <!ENTITY appversion "0.7.2">
+ <!ENTITY manrevision "0.1">
+ <!ENTITY date "March 2007">
+ <!ENTITY app "<application>Gnash</application>">
+ <!ENTITY appname "Gnash">
+ <!ENTITY actionscript "ActionScript">
+ <!ENTITY fn_call "<emphasis>fn_call</emphasis>">
+ <!ENTITY gen_asclass "<emphasis>gen-asclass.sh</emphasis>">
+ <!ENTITY version "0.7.2">
+
+ <!ENTITY main SYSTEM "actionscript/main.xml">
+ ]
+>
+
+ <!-- =============Document Header ============================= -->
+ <article id="index" lang="en">
+
+
+<!-- please do not change the id; for translations, change lang to -->
+<!-- appropriate code -->
+ <articleinfo>
+ <title>&actionscript; Manual V&manrevision;</title>
+ <copyright>
+ <year>2007</year>
+ <holder>Free Software Foundation</holder>
+ </copyright>
+
+
+<!-- translators: uncomment this:
+ <copyright>
+ <year>2007</year>
+ <holder>ME-THE-TRANSLATOR (Latin translation)</holder>
+ </copyright>
+ -->
+
+<!-- An address can be added to the publisher information. If a role is
+ not specified, the publisher/author is the same for all versions of the
+ document. -->
+ <publisher>
+ <publishername>Gnash Documentation Project </publishername>
+ </publisher>
+
+
+<!--
+ Copyright (c) 2007, Free Software Foundation, Inc.
+ Permission is granted to copy, distribute and/or modify this document
+ under the terms of the GNU Free Documentation License, Version 1.2
+ or any later version published by the Free Software Foundation;
+ with no Invariant Sections, no Front-Cover Texts, and no Back-Cover
+ Texts. A copy of the license is included in the section entitled "GNU
+ Free Documentation License".
+-->
+
+ <!-- This file contains link to license for the documentation (GNU FDL),
and
+ other legal stuff such as "NO WARRANTY" statement. Please do not
change
+ any of this. -->
+ &legal;
+
+
+
+ <authorgroup>
+ <author>
+ <firstname>Rob</firstname>
+ <surname>Savoye</surname>
+ <affiliation>
+ <address>
+ <email>address@hidden</email>
+ </address>
+ </affiliation>
+ </author>
+ <author>
+ <firstname>Ann</firstname>
+ <surname>Barcomb</surname>
+ </author>
+
+<!-- This is appropriate place for other contributors: translators,
+ maintainers, etc. Commented out by default.
+ <othercredit role="translator">
+ <firstname>Latin</firstname>
+ <surname>Translator 1</surname>
+ <affiliation>
+ <orgname>Latin Translation Team</orgname>
+ <address> <email>address@hidden</email> </address>
+ </affiliation>
+ <contrib>Latin translation</contrib>
+ </othercredit>
+-->
+ </authorgroup>
+
+ <revhistory>
+ <revision>
+ <revnumber>&actionscript; Manual V&manrevision;</revnumber>
+ <date>&date;</date>
+ <revdescription>
+ <para role="author">Rob Savoye
+ <email>address@hidden</email>
+ </para>
+ <para role="author">Ann Barcomb
+ </para>
+ <para role="publisher">Free Software Foundation</para>
+ </revdescription>
+ </revision>
+ </revhistory>
+
+ <releaseinfo>This manual describes how &appname; &actionscript; classes
+ are written.
+ </releaseinfo>
+ </articleinfo>
+
+ <indexterm zone="index">
+ <primary>Gnash</primary>
+ </indexterm>
+
+<!-- ============= Document Body ============================= -->
+ &main;
+
+<!-- ============= Application License ============================= -->
+
+ &fdl-app;
+
+</article>
Index: doc/C/actionscript/main.xml
===================================================================
RCS file: doc/C/actionscript/main.xml
diff -N doc/C/actionscript/main.xml
--- /dev/null 1 Jan 1970 00:00:00 -0000
+++ doc/C/actionscript/main.xml 19 Mar 2007 14:40:12 -0000 1.1
@@ -0,0 +1,326 @@
+ <sect1 id="introduction">
+ <title>Introduction</title>
+
+ <para>
+ In this document, the term 'ActionScript class' refers to the
+ C++ class which is instantiated by Gnash when some ActionScript
+ code instantiates a corresponding class. The C++ class
+ stores instance data and implements the methods which are
+ called on the object in the ActionScript code.
+ </para>
+
+ <sect2 id="overview">
+ <title>Object Creation Overview</title>
+ <para>
+ When Gnash starts, the <emphasis>class_init()</emphasis> method
+ for each ActionScript class (listed in Global.cpp) is called.
+ This method constructs a prototype, which is implemented as an
+ <emphasis>as_object</emphasis>. In addition, the method
+ registers the constructor to be used for future object creation,
+ and attaches methods and properties to the prototype.
+ </para>
+
+ <para>
+ When a new object is needed, instance data is added to
+ the methods and properties inherited from the prototype.
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="newclass">
+ <title>Adding New ActionScript Class</title>
+
+ <para>
+ Adding a new ActionScript class is relatively simple, but the
+ process is complicated by the fact that the interface has evolved
+ over time and the current code base represents several different
+ formats. This document describes the current interface. The
+ Boolean class should be considered the authoritative example of
+ a modern ActionScript class.
+ </para>
+
+ <para>
+ ActionScript classes contain a header file and a C++
+ implementation. The name is usually the name of the
+ class as it is called in the ActionScript specifications;
+ for instance <emphasis>Boolean.cpp</emphasis> for the Boolean class.
+ </para>
+
+ <para>
+ In the CVS source tree, there is a utility file named
+ &gen_asclass; which can be used to
+ create the header file and a C++ source file stub for
+ an ActionScript class.
+ </para>
+
+ <sect2 id="prototype">
+ <title>Prototype</title>
+
+ <para>
+ In ActionScript, a prototype is a base object which contains
+ all the methods that an instantiated object will contain.
+ In short, it contains every part of the class except for
+ the portions dealing with the storage of instance data.
+ </para>
+ <para>
+ In Gnash, the prototype of an ActionScript object is
+ implemented as an <emphasis>as_object</emphasis>.
+ At startup, the methods and properties of the ActionScript class
+ are attached to the <emphasis>as_object</emphasis>. The
+ following example demonstrates how methods can be attached:
+ <programlisting>
+ static void
+ attachBooleanInterface(as_object& o)
+ {
+ o.init_member("toString", new
builtin_function(boolean_tostring));
+ o.init_member("valueOf", new
builtin_function(boolean_valueof));
+ }
+ </programlisting>
+ This code was generated using &gen_asclass;.
+ Typically, you will need to customize the attach method to include
+ any new methods you add to the class.
+ </para>
+ <para>
+ Static properties can also be added to the ActionScript prototype
+ (<link linkend="properties">dynamic properties</link>
+ are addressed later). They are attached in a similar way:
+ <programlisting>
+ o.init_member("myProperty", as_value("HelloWorld"));
+ </programlisting>
+ </para>
+ <para>
+ Properties which have been added in this manner can be
+ directly accessed in ActionScript code without a function
+ call, as this piece of ActionScript code compiled by Ming's
+ <emphasis>makeswf</emphasis> compiler demonstrates:
+ <programlisting>
+ // Get the value of the myProperty property
+ if (node.myProperty == "HelloWorld") {
+ trace("MATCHED");
+ }
+ </programlisting>
+ </para>
+ </sect2>
+
+ <sect2 id="declaration">
+ <title>Declaration</title>
+
+ <para>
+ A new class should derive from <emphasis>as_object</emphasis>,
+ which is the base class of every ActionScript object in Gnash.
+ The class declaration will also be generated when you use
+ &gen_asclass;.
+ </para>
+ </sect2>
+
+ <sect2 id="instantiation">
+ <title>Instantiation</title>
+
+ <para>
+ The class should contain an init method; this is included
+ in the stub when &gen_asclass; is
+ used.
+ </para>
+ <para>
+ The init method should be called in the constructor in
+ <emphasis>Global.cpp</emphasis>, where all other ActionScript
+ classes are similarly referenced.
+ </para>
+ </sect2>
+
+ <sect2 id="methods">
+ <title>Methods</title>
+
+ <para>
+ Every method you implement and
+ <link linkend="prototype">attach</link> will receive an
+ &fn_call; data structure as an argument when it is called.
+ The most important members of the &fn_call; structure are
+ the <link linkend="arguments">stack of arguments</link>
+ to the function and a
+ <link linkend="return">pointer to the result</link>, which will
+ be returned to the (ActionScript) caller. The remainder
+ of the <link linkend="additional_fn_call">&fn_call;
+ structure</link> is described later in this section.
+ </para>
+
+ <sect3 id="arguments">
+ <title>Accessing Arguments</title>
+ <para>
+ The arguments stored in &fn_call;
+ should be accessed using <emphasis>arg()</emphasis>. For
+ instance, the first element can be popped with
+ <emphasis>fn.arg(0)</emphasis>.
+ </para>
+ <para>
+ The element popped off the stack is an
+ <link linkend="as_value"><emphasis>as_value</emphasis>
+ object</link>.
+ </para>
+ </sect3>
+
+ <sect3 id="return">
+ <title>Returning a Value to ActionScript</title>
+ <para>
+ The return value should be set <emphasis>result</emphasis>
+ pointer of the &fn_call; structure. For example:
+ <programlisting>
+ fn.result->set_string('Goodbye, cruel world.');
+ </programlisting>
+ </para>
+ <para>
+ The return value is an
+ <link linkend="as_value"><emphasis>as_value</emphasis>
+ object</link>.
+ </para>
+ </sect3>
+
+ <sect3 id="additional_fn_call">
+ <title>Additional &fn_call; Members</title>
+ <para>
+ In addition to the aforementioned
+ <link linkend="return">result pointer</link>, there
+ are two other useful members of the &fn_call;
+ structure, namely <emphasis>this_ptr</emphasis> and
+ <emphasis>nargs</emphasis>. The former points to the
+ class which is invoking this method, while the latter
+ is a count of the number of
+ <link linkend="arguments">arguments in the stack</link>.
+ You may also see instances of the <emphasis>env</emphasis>
+ pointer being used, but it has been deprecated.
+ </para>
+ <para>
+ Beyond the <emphasis><link
+ linkend="arguments">arg()</link></emphasis> method, there
+ is one method of note. <emphasis>dump_args()</emphasis>
+ can be used in debugging to output the entire argument
+ stack.
+ </para>
+ </sect3>
+ </sect2>
+
+ <sect2 id="properties">
+ <title>Dynamic Properties</title>
+ <para>
+ This section describes accessors to dynamic properties.
+ Read-only properties are described
+ in the <link linkend="prototype">prototype</link> section.
+ </para>
+ <para>
+ Dynamic properties are not created by the &gen_asclass;
+ script. Accessors should be written as
+ a single get/set method. Previously this was done by
+ overriding <emphasis>get_member()</emphasis> and
+ <emphasis>set_member()</emphasis>, but this practice
+ is deprecated.
+ </para>
+ <para>
+ The accessor is written so that it sets the property
+ if it is called with an argument, and puts the property in
+ the <link linkend="methods">&fn_call;</link>
+ <link linkend="return">result pointer</link>. For instance:
+ <programlisting>
+ void
+ MyClass::myProperty_getset(const fn_call& fn)
+ {
+
+ MyClass* ptr = ensureMyClass(fn.this_ptr);
+
+ // setter
+ if ( fn.nargs > 0 )
+ {
+ bool h = fn.arg(0).to_bool();
+ ptr->MyMethod(h);
+ return;
+ }
+
+ // getter
+ bool h = ptr->MyMethod();
+ fn.result->set_bool(h);
+ }
+ </programlisting>
+ </para>
+ <para>
+ It has not yet been decided whether properties should be set
+ in the <link linkend="prototype">exported interface</link>
+ or attached to instances of the class. A property is attached
+ in the following manner:
+ <programlisting>
+ boost::intrusive_ptr<builtin_function> gettersetter;
+ gettersetter = new
builtin_function(&MyClass::myProperty_getset, NULL);
+ o.init_property("myProperty", *gettersetter, *gettersetter);
+ </programlisting>
+ </para>
+ </sect2>
+ </sect1>
+
+ <sect1 id="as_value">
+ <title>The <emphasis>as_value</emphasis> Object Type</title>
+ <para>
+ The <emphasis>as_value</emphasis> class is used throughout
+ the interpreter to create generic objects to hold data.
+ </para>
+
+ <sect2 id="data_types">
+ <title>Data Types</title>
+ <para>
+ The following data types are supported:
+ <emphasis>NULLTYPE</emphasis>,
+ <emphasis>BOOLEAN</emphasis>, <emphasis>STRING</emphasis>,
+ <emphasis>NUMBER</emphasis>, <emphasis>OBJECT</emphasis>,
+ <emphasis>AS_FUNCTION</emphasis>, and
+ <emphasis>MOVIECLIP</emphasis>.
+ The type <emphasis>C_FUNCTION</emphasis> is being deprecated.
+ </para>
+ </sect2>
+
+ <sect2 id="is_methods">
+ <title>Determining the Type</title>
+ <para>
+ Several methods allow you to determine if a value stored in
+ <emphasis>as_value</emphasis> is of a specific type. These
+ follow the form of <emphasis>is_TYPE</emphasis>, for example
+ <emphasis>is_as_function()</emphasis> and
+ <emphasis>is_number()</emphasis>.
+ </para>
+ </sect2>
+
+ <sect2 id="to_methods">
+ <title>Fetching the Value</title>
+ <para>
+ Another set of methods will return a representation of
+ the value as a particular type. They follow the
+ <emphasis>to_TYPE</emphasis> naming convention. Examples
+ are <emphasis>to_number()</emphasis> and
+ <emphasis>to_bool()</emphasis>.
+ </para>
+ </sect2>
+
+ <sect2 id="set_methods">
+ <title>Setting the Value and Type</title>
+ <para>
+ Finally, there is the <emphasis>set_TYPE</emphasis> series
+ of methods. They change the type to the type specified in
+ the method name, and set the value to the one given as an
+ argument. It is also possible to accomplish the same thing
+ with the <emphasis>=</emphasis> operator.
+ </para>
+ </sect2>
+
+ <sect2 id="further_as_value_reading">
+ <title>Further Reading</title>
+ <para>
+ Please refer to <emphasis>as_value.h</emphasis> or the
+ Doxygen documentation (see 'Processing The Documentation'
+ in the &appname; manual for instructions on generating
+ documents with Doxygen) for more information
+ about which methods are available for the
+ <emphasis>as_value</emphasis> object.
+ </para>
+ <para>
+ Note that the <emphasis>tu_string</emphasis> and related
+ methods are deprecated.
+ </para>
+ </sect2>
+
+ </sect1>
| [Prev in Thread] |
Current Thread |
[Next in Thread] |
- [Gnash-commit] gnash ChangeLog doc/C/internals.xml doc/C/Makef...,
Ann Barcomb <=