SwfdecAsObject

SwfdecAsObject — the base object type for scriptable objects

Synopsis


#include <swfdec/swfdec.h>

                    SwfdecAsObject;
SwfdecAsObject*     swfdec_as_object_new                (SwfdecAsContext *context);
SwfdecAsObject*     swfdec_as_object_new_empty          (SwfdecAsContext *context);
void                swfdec_as_object_create             (SwfdecAsFunction *fun,
                                                         guint n_args,
                                                         const SwfdecAsValue *args,
                                                         SwfdecAsValue *return_value);
void                swfdec_as_object_set_constructor    (SwfdecAsObject *object,
                                                         SwfdecAsObject *construct);
enum                SwfdecAsVariableFlag;
#define             swfdec_as_object_get_variable       (object, variable, value)
gboolean            swfdec_as_object_get_variable_and_flags
                                                        (SwfdecAsObject *object,
                                                         const char *variable,
                                                         SwfdecAsValue *value,
                                                         guint *flags,
                                                         SwfdecAsObject **pobject);
#define             swfdec_as_object_set_variable       (object, variable, value)
void                swfdec_as_object_set_variable_and_flags
                                                        (SwfdecAsObject *object,
                                                         const char *variable,
                                                         const SwfdecAsValue *value,
                                                         guint default_flags);
void                swfdec_as_object_add_variable       (SwfdecAsObject *object,
                                                         const char *variable,
                                                         SwfdecAsFunction *get,
                                                         SwfdecAsFunction *set,
                                                         SwfdecAsVariableFlag default_flags);
void                swfdec_as_object_set_variable_flags (SwfdecAsObject *object,
                                                         const char *variable,
                                                         SwfdecAsVariableFlag flags);
void                swfdec_as_object_unset_variable_flags
                                                        (SwfdecAsObject *object,
                                                         const char *variable,
                                                         SwfdecAsVariableFlag flags);
SwfdecAsObject*     swfdec_as_object_has_variable       (SwfdecAsObject *object,
                                                         const char *variable);
SwfdecAsDeleteReturn swfdec_as_object_delete_variable   (SwfdecAsObject *object,
                                                         const char *variable);
void                swfdec_as_object_delete_all_variables
                                                        (SwfdecAsObject *object);
gboolean            (*SwfdecAsVariableForeach)          (SwfdecAsObject *object,
                                                         const char *variable,
                                                         SwfdecAsValue *value,
                                                         guint flags,
                                                         gpointer data);
gboolean            swfdec_as_object_foreach            (SwfdecAsObject *object,
                                                         SwfdecAsVariableForeach func,
                                                         gpointer data);
void                swfdec_as_object_run                (SwfdecAsObject *object,
                                                         SwfdecScript *script);
gboolean            swfdec_as_object_call               (SwfdecAsObject *object,
                                                         const char *name,
                                                         guint argc,
                                                         SwfdecAsValue *argv,
                                                         SwfdecAsValue *return_value);
SwfdecAsFunction*   swfdec_as_object_add_function       (SwfdecAsObject *object,
                                                         const char *name,
                                                         SwfdecAsNative native);
SwfdecAsFunction*   swfdec_as_object_add_constructor    (SwfdecAsObject *object,
                                                         const char *name,
                                                         GType construct_type,
                                                         SwfdecAsNative native,
                                                         SwfdecAsObject *prototype);
char*               swfdec_as_object_get_debug          (SwfdecAsObject *object);
SwfdecAsObject*     swfdec_as_object_resolve            (SwfdecAsObject *object);

Object Hierarchy

  GObject
   +----SwfdecGcObject
         +----SwfdecAsObject
               +----SwfdecAsArray
               +----SwfdecAsFunction

Description

This is the basic object type in Swfdec. Every object used by the script engine must be a SwfdecAsObject. It handles memory management and assigning variables to it. Almost all functions that are called on objects require that the objects have been added to the garbage collector previously. For custom-created objects, you need to do this using swfdec_as_object_add(), built-in functions that create objects do this manually.

Note that you cannot know the lifetime of a SwfdecAsObject, since scripts may assign it as a variable to other objects. So you should not assume to know when an object gets removed.

Details

SwfdecAsObject

typedef struct _SwfdecAsObject SwfdecAsObject;

Every object value inside the Swfdec script engine must be a SwfdecAsObject. If you want to add custom objects to your script engine, you need to create a subclass. The class provides a number of virtual functions that you can override to achieve the desired behaviour.

swfdec_as_object_new ()

SwfdecAsObject*     swfdec_as_object_new                (SwfdecAsContext *context);

Allocates a new Object. This does the same as the Actionscript code "new Object()".

context :

 a SwfdecAsContext

Returns :

 the new object

swfdec_as_object_new_empty ()

SwfdecAsObject*     swfdec_as_object_new_empty          (SwfdecAsContext *context);

Creates an empty object. The prototype and constructor properties of the returned object will not be set. You probably want to call swfdec_as_object_set_constructor() on the returned object yourself. You may want to use swfdec_as_object_new() instead.

context :

 a SwfdecAsContext

Returns :

 A new SwfdecAsObject added to context

swfdec_as_object_create ()

void                swfdec_as_object_create             (SwfdecAsFunction *fun,
                                                         guint n_args,
                                                         const SwfdecAsValue *args,
                                                         SwfdecAsValue *return_value);

Creates a new object for the given constructor and runs the constructor.

fun :

 constructor

n_args :

 number of arguments

args :

 arguments to pass to constructor

return_value :

 pointer for return value or NULL to push the return value to the stack

swfdec_as_object_set_constructor ()

void                swfdec_as_object_set_constructor    (SwfdecAsObject *object,
                                                         SwfdecAsObject *construct);

Sets the constructor variables for object. Most objects get these variables set automatically, but for objects you created yourself, you want to call this function. This is essentially the same as the following script code: 

 object.constructor = construct;
object.__proto__ = construct.prototype;

object :

 a SwfdecAsObject

construct :

 the constructor of object

enum SwfdecAsVariableFlag

typedef enum {
  SWFDEC_AS_VARIABLE_HIDDEN = (1 << 0),
  SWFDEC_AS_VARIABLE_PERMANENT = (1 << 1),
  SWFDEC_AS_VARIABLE_CONSTANT = (1 << 2),

  SWFDEC_AS_VARIABLE_VERSION_6_UP = (1 << 7),
  SWFDEC_AS_VARIABLE_VERSION_NOT_6 = (1 << 8),
  SWFDEC_AS_VARIABLE_VERSION_7_UP = (1 << 10),
  SWFDEC_AS_VARIABLE_VERSION_8_UP = (1 << 12),
  SWFDEC_AS_VARIABLE_VERSION_9_UP = (1 << 13),
} SwfdecAsVariableFlag;

These flags are used to describe various properties of a variable inside Swfdec. You can manually set them with swfdec_as_object_set_variable_flags().

SWFDEC_AS_VARIABLE_HIDDEN

 Do not include variable in enumerations and swfdec_as_object_foreach().

SWFDEC_AS_VARIABLE_PERMANENT

 Do not allow swfdec_as_object_delete_variable() to delete this variable.

SWFDEC_AS_VARIABLE_CONSTANT

 Do not allow changing the value with swfdec_as_object_set_variable().

SWFDEC_AS_VARIABLE_VERSION_6_UP

 This symbol is only visible in version 6 and above.

SWFDEC_AS_VARIABLE_VERSION_NOT_6

 This symbols is visible in all versions but version 6.

SWFDEC_AS_VARIABLE_VERSION_7_UP

 This symbol is only visible in version 7 and above.

SWFDEC_AS_VARIABLE_VERSION_8_UP

 This symbol is only visible in version 8 and above.

SWFDEC_AS_VARIABLE_VERSION_9_UP

 This symbol is only visible in version 9 and above.

swfdec_as_object_get_variable()

#define             swfdec_as_object_get_variable(object, variable, value)

Gets the value of the given variable on object. It walks the prototype chain. This is a shortcut macro for swfdec_as_object_get_variable_and_flags().

object :

 a SwfdecAsObject

variable :

 a garbage-collected string containing the name of the variable

value :

 pointer to a SwfdecAsValue that takes the return value or NULL

swfdec_as_object_get_variable_and_flags ()

gboolean            swfdec_as_object_get_variable_and_flags
                                                        (SwfdecAsObject *object,
                                                         const char *variable,
                                                         SwfdecAsValue *value,
                                                         guint *flags,
                                                         SwfdecAsObject **pobject);

Looks up variable on object. It also walks the object's prototype chain. If the variable exists, its value, flags and the real object containing the variable will be set and TRUE will be returned.

object :

 a SwfdecAsObject

variable :

 a garbage-collected string containing the name of the variable

value :

 pointer to a SwfdecAsValue that takes the return value or NULL

flags :

 pointer to a guint taking the variable's flags or NULL

pobject :

 pointer to set to the object that really holds the property or NULL

Returns :

 TRUE if the variable exists, FALSE otherwise

swfdec_as_object_set_variable()

#define             swfdec_as_object_set_variable(object, variable, value)

Sets a variable on object. It is not guaranteed that getting the variable after setting it results in the same value. This is a mcaro that calls swfdec_as_object_set_variable_and_flags()

object :

 a SwfdecAsObject

variable :

 garbage-collected name of the variable to set

value :

 value to set the variable to

swfdec_as_object_set_variable_and_flags ()

void                swfdec_as_object_set_variable_and_flags
                                                        (SwfdecAsObject *object,
                                                         const char *variable,
                                                         const SwfdecAsValue *value,
                                                         guint default_flags);

Sets a variable on object. It is not guaranteed that getting the variable after setting it results in the same value, because various mechanisms (like the Actionscript Object.addProperty function or constant variables) can avoid this.

object :

 a SwfdecAsObject

variable :

 garbage-collected name of the variable to set

value :

 value to set the variable to

default_flags :

 flags to use if creating the variable anew - the flags will be ignored if the property already exists.

swfdec_as_object_add_variable ()

void                swfdec_as_object_add_variable       (SwfdecAsObject *object,
                                                         const char *variable,
                                                         SwfdecAsFunction *get,
                                                         SwfdecAsFunction *set,
                                                         SwfdecAsVariableFlag default_flags);

Adds a variable to object in the same way as the Actionscript code "object.addProperty()" would do. Accessing the variable will from now on be handled by calling the get or set functions. A previous value of the variable or a previous call to this function will be overwritten.

object :

 a SwfdecAsObject

variable :

 name of the variable

get :

 getter function to call when reading the variable

set :

 setter function to call when writing the variable or NULL if read-only

default_flags :

 flags to use if creating the variable anew - the flags will be ignored if the property already exists.

swfdec_as_object_set_variable_flags ()

void                swfdec_as_object_set_variable_flags (SwfdecAsObject *object,
                                                         const char *variable,
                                                         SwfdecAsVariableFlag flags);

Sets the given flags for the given variable.

object :

 a SwfdecAsObject

variable :

 the variable to modify

flags :

 flags to set

swfdec_as_object_unset_variable_flags ()

void                swfdec_as_object_unset_variable_flags
                                                        (SwfdecAsObject *object,
                                                         const char *variable,
                                                         SwfdecAsVariableFlag flags);

Unsets the given flags for the given variable. The variable must exist in object.

object :

 a SwfdecAsObject

variable :

 the variable to modify

flags :

 flags to unset

swfdec_as_object_has_variable ()

SwfdecAsObject*     swfdec_as_object_has_variable       (SwfdecAsObject *object,
                                                         const char *variable);

Checks if a user-set variable with the given name exists on object. This function does not check variables that are available via an overwritten get function of the object's class.

object :

 a SwfdecAsObject

variable :

 garbage-collected variable name

Returns :

 the object in the prototype chain that contains variable or NULL if the object does not contain this variable.

swfdec_as_object_delete_variable ()

SwfdecAsDeleteReturn swfdec_as_object_delete_variable   (SwfdecAsObject *object,
                                                         const char *variable);

Deletes the given variable if possible. If the variable is protected from deletion, it will not be deleted.

object :

 a SwfdecAsObject

variable :

 garbage-collected name of the variable

Returns :

 See SwfdecAsDeleteReturn for details of the return value.

swfdec_as_object_delete_all_variables ()

void                swfdec_as_object_delete_all_variables
                                                        (SwfdecAsObject *object);

Deletes all user-set variables from the given object.

object :

 a SwfdecAsObject

SwfdecAsVariableForeach ()

gboolean            (*SwfdecAsVariableForeach)          (SwfdecAsObject *object,
                                                         const char *variable,
                                                         SwfdecAsValue *value,
                                                         guint flags,
                                                         gpointer data);

Function prototype for the swfdec_as_object_foreach() function.

object :

 The object this function is run on

variable :

 garbage-collected name of the current variables

value :

 value of the current variable

flags :

 Flags associated with the current variable

data :

 User data passed to swfdec_as_object_foreach()

Returns :

 TRUE to continue running the foreach function, FALSE to stop

swfdec_as_object_foreach ()

gboolean            swfdec_as_object_foreach            (SwfdecAsObject *object,
                                                         SwfdecAsVariableForeach func,
                                                         gpointer data);

Calls func for every variable of object or until func returns FALSE. The variables of object must not be modified by func.

object :

 a SwfdecAsObject

func :

 function to call

data :

 data to pass to func

Returns :

 TRUE if func always returned TRUE

swfdec_as_object_run ()

void                swfdec_as_object_run                (SwfdecAsObject *object,
                                                         SwfdecScript *script);

Executes the given script with object as this pointer.

object :

 a SwfdecAsObject

script :

 script to execute

swfdec_as_object_call ()

gboolean            swfdec_as_object_call               (SwfdecAsObject *object,
                                                         const char *name,
                                                         guint argc,
                                                         SwfdecAsValue *argv,
                                                         SwfdecAsValue *return_value);

Calls the function named name on the given object. This function is essentially equal to the folloeing Actionscript code: 

@return_value = @object.@name (@argv[0], ..., @argv[argc-1]);

object :

 a SwfdecAsObject

name :

 garbage-collected string naming the function to call.

argc :

 number of arguments to provide to function

argv :

 arguments or NULL when argc is 0

return_value :

 location to take the return value of the call or NULL to ignore the return value.

Returns :

 TRUE if object had a function with the given name, FALSE otherwise

swfdec_as_object_add_function ()

SwfdecAsFunction*   swfdec_as_object_add_function       (SwfdecAsObject *object,
                                                         const char *name,
                                                         SwfdecAsNative native);

Adds native as a variable named name to object. The newly added variable will not be enumerated.

object :

 a SwfdecAsObject

name :

 name of the function. The string does not have to be garbage-collected.

native :

 a native function or NULL to just not do anything

Returns :

 the newly created SwfdecAsFunction

swfdec_as_object_add_constructor ()

SwfdecAsFunction*   swfdec_as_object_add_constructor    (SwfdecAsObject *object,
                                                         const char *name,
                                                         GType construct_type,
                                                         SwfdecAsNative native,
                                                         SwfdecAsObject *prototype);

Adds native as a constructor named name to object. The newly added variable will not be enumerated.

object :

 a SwfdecAsObject

name :

 name of the function. The string does not have to be garbage-collected.

construct_type :

 type used when using this function as a constructor. May be 0 to use the default type.

native :

 a native function or NULL to just not do anything

prototype :

 An optional object to be set as the "prototype" property of the new function. The prototype will be hidden and constant.

Returns :

 the newly created SwfdecAsFunction

swfdec_as_object_get_debug ()

char*               swfdec_as_object_get_debug          (SwfdecAsObject *object);

Gets a representation string suitable for debugging. This function is guaranteed to not modify the state of the script engine, unlike swfdec_as_value_to_string() for example.

object :

 a SwfdecAsObject

Returns :

 A newly allocated string. Free it with g_free() after use.

swfdec_as_object_resolve ()

SwfdecAsObject*     swfdec_as_object_resolve            (SwfdecAsObject *object);

Resolves the object to its real object. Some internal objects should not be exposed to scripts, for example SwfdecAsFrame objects. If an object you want to expose might be internal, call this function to resolve it to an object that is safe to expose.

object :

 a SwfdecAsObject

Returns :

 a non-internal object
Generated by GTK-Doc V1.10