CpgObject

CpgObject — Basis for all cpg objects

Synopsis

#define             CPG_OBJECT_ERROR
#define             CPG_OBJECT_CONST                    (obj)
enum                CpgObjectError;
struct              CpgObject;
void                (*CpgForeachExpressionFunc)         (CpgExpression *expression,
                                                         gpointer userdata);
struct              CpgObjectClass;
GQuark              cpg_object_error_quark              (void);
CpgObject *         cpg_object_new                      (const gchar *id);
CpgObject *         cpg_object_new_from_template        (CpgObject *templ,
                                                         GError **error);
const gchar *       cpg_object_get_id                   (CpgObject *object);
void                cpg_object_set_id                   (CpgObject *object,
                                                         const gchar *id);
gboolean            cpg_object_add_property             (CpgObject *object,
                                                         CpgProperty *property,
                                                         GError **error);
CpgProperty *       cpg_object_get_property             (CpgObject *object,
                                                         const gchar *name);
gboolean            cpg_object_has_property             (CpgObject *object,
                                                         const gchar *name);
gboolean            cpg_object_remove_property          (CpgObject *object,
                                                         const gchar *name,
                                                         GError **error);
gboolean            cpg_object_verify_remove_property   (CpgObject *object,
                                                         const gchar *name,
                                                         GError **error);
GSList *            cpg_object_get_properties           (CpgObject *object);
CpgObject *         cpg_object_get_parent               (CpgObject *object);
gboolean            cpg_object_get_auto_imported        (CpgObject *object);
void                cpg_object_set_auto_imported        (CpgObject *object,
                                                         gboolean auto_imported);
void                cpg_object_reset                    (CpgObject *object);
void                cpg_object_foreach_expression       (CpgObject *object,
                                                         CpgForeachExpressionFunc func,
                                                         gpointer userdata);
void                cpg_object_taint                    (CpgObject *object);
gboolean            cpg_object_is_compiled              (CpgObject *object);
gboolean            cpg_object_compile                  (CpgObject *object,
                                                         CpgCompileContext *context);
gboolean            cpg_object_equal                    (CpgObject *first,
                                                         CpgObject *second);
void                cpg_object_clear                    (CpgObject *object);
const GSList *      cpg_object_get_actors               (CpgObject *object);
const GSList *      cpg_object_get_applied_templates    (CpgObject *object);
const GSList *      cpg_object_get_template_applies_to  (CpgObject *object);
CpgObject *         cpg_object_copy                     (CpgObject *object);
gboolean            cpg_object_apply_template           (CpgObject *object,
                                                         CpgObject *templ,
                                                         GError **error);
gboolean            cpg_object_unapply_template         (CpgObject *object,
                                                         CpgObject *templ,
                                                         GError **error);
CpgObject *         cpg_object_get_property_template    (CpgObject *object,
                                                         CpgProperty *property,
                                                         gboolean match_full);
gchar *             cpg_object_get_full_id              (CpgObject *object);
gchar *             cpg_object_get_full_id_for_display  (CpgObject *object);
gchar *             cpg_object_get_relative_id          (CpgObject *object,
                                                         CpgObject *parent);
gchar *             cpg_object_get_relative_id_for_display
                                                        (CpgObject *object,
                                                         CpgObject *parent);
const GSList *      cpg_object_get_links                (CpgObject *object);
void                cpg_object_add_event_handler        (CpgObject *object,
                                                         CpgParserCode *code);
void                cpg_object_remove_event_handler     (CpgObject *object,
                                                         CpgParserCode *code);
const GSList *      cpg_object_get_event_handlers       (CpgObject *object);
                    CpgObjectPrivate;

Object Hierarchy

  GEnum
   +----CpgObjectError
  GObject
   +----CpgObject
         +----CpgFunction
         +----CpgGroup
         +----CpgInput
         +----CpgIntegrator
         +----CpgLink

Implemented Interfaces

CpgObject implements CpgUsable, CpgAnnotatable, CpgLayoutable and CpgTaggable.

Properties

  "auto-imported"            gboolean              : Read / Write / Construct
  "id"                       gchar*                : Read / Write / Construct
  "parent"                   CpgObject*            : Read

Signals

  "compiled"                                       : Run Last
  "copied"                                         : Run Last
  "property-added"                                 : Run Last
  "property-changed"                               : Run Last
  "property-removed"                               : Run Last
  "resetted"                                       : Run Last
  "tainted"                                        : Run Last
  "template-applied"                               : Run Last
  "template-unapplied"                             : Run Last
  "verify-remove-property"                         : Run Last

Description

CpgObject is a base class for all the objects which can be added to a network. It provides property storage and virtual methods which can be implemented that drive the simulation process.

Details

CPG_OBJECT_ERROR

#define CPG_OBJECT_ERROR (cpg_object_error_quark ())


CPG_OBJECT_CONST()

#define CPG_OBJECT_CONST(obj)      (G_TYPE_CHECK_INSTANCE_CAST ((obj), CPG_TYPE_OBJECT, CpgObject const))


enum CpgObjectError

typedef enum
{
	CPG_OBJECT_ERROR_PROPERTY_UNKNOWN,
	CPG_OBJECT_ERROR_PROPERTY_NOT_FOUND,
	CPG_OBJECT_ERROR_PROPERTY_IN_USE,
	CPG_OBJECT_ERROR_PROPERTY_FROM_TEMPLATE,
	CPG_OBJECT_ERROR_INVALID_PROPERTY_NAME,
	CPG_OBJECT_ERROR_TEMPLATE_ALREADY_APPLIED,
	CPG_OBJECT_ERROR_TEMPLATE_NOT_FOUND,
	CPG_OBJECT_NUM_ERRORS
} CpgObjectError;

Enum used to indicate an error when removing a property

CPG_OBJECT_ERROR_PROPERTY_UNKNOWN

unknown

CPG_OBJECT_ERROR_PROPERTY_NOT_FOUND

property not found

CPG_OBJECT_ERROR_PROPERTY_IN_USE

property in use

CPG_OBJECT_ERROR_PROPERTY_FROM_TEMPLATE

CPG_OBJECT_ERROR_INVALID_PROPERTY_NAME

CPG_OBJECT_ERROR_TEMPLATE_ALREADY_APPLIED

CPG_OBJECT_ERROR_TEMPLATE_NOT_FOUND

CPG_OBJECT_NUM_ERRORS

num errors

struct CpgObject

struct CpgObject;


CpgForeachExpressionFunc ()

void                (*CpgForeachExpressionFunc)         (CpgExpression *expression,
                                                         gpointer userdata);

A function callback called on each expression found in an object.

expression :

a CpgExpression

userdata :

user data

struct CpgObjectClass

struct CpgObjectClass {
	gboolean      (*compile)         (CpgObject                          *object,
	                                  CpgCompileContext                  *context,
	                                  CPG_FORWARD_DECL (CpgCompileError) *error);

	void          (*reset)           (CpgObject *object);

	void          (*foreach_expression) (CpgObject                *object,
	                                     CpgForeachExpressionFunc  func,
	                                     gpointer                  userdata);

	gboolean      (*apply_template)  (CpgObject  *object,
	                                  CpgObject  *templ,
	                                  GError    **error);

	gboolean      (*unapply_template)  (CpgObject  *object,
	                                    CpgObject  *templ,
	                                    GError    **error);

	void          (*copy)            (CpgObject *object,
	                                  CpgObject *source);

	GType         (*get_copy_type)   (CpgObject *object);

	void          (*taint)           (CpgObject *object);

	GSList       *(*get_properties)  (CpgObject    *object);
	CpgProperty  *(*get_property)    (CpgObject    *object,
	                                  const gchar  *name);

	gboolean      (*has_property)    (CpgObject    *object,
	                                  const gchar  *name);

	gboolean      (*add_property)    (CpgObject    *object,
	                                  CpgProperty  *property,
	                                  GError      **error);

	gboolean      (*remove_property) (CpgObject    *object,
	                                  const gchar  *name,
	                                  GError      **error);

	gboolean      (*verify_remove_property) (CpgObject    *object,
	                                         const gchar  *name,
	                                         GError      **error);

	void          (*clear)           (CpgObject    *object);

	gboolean      (*equal)           (CpgObject    *first,
	                                  CpgObject    *last);

	/* signals */
	void          (*compiled)         (CpgObject   *object);
	void          (*resetted)         (CpgObject   *object);
	void          (*tainted)          (CpgObject   *object);

	void          (*copied)           (CpgObject   *object,
	                                   CpgObject   *copy);

	void          (*property_added)   (CpgObject   *object,
	                                   CpgProperty *property);
	void          (*property_removed) (CpgObject   *object,
	                                   CpgProperty *property);
	void          (*property_changed) (CpgObject   *object,
	                                   CpgProperty *property);

	void          (*template_applied) (CpgObject   *object,
	                                   CpgObject   *templ);
	void          (*template_unapplied) (CpgObject *object,
	                                     CpgObject *templ);
};

The CpgObject class

reset ()

reset virtual function

foreach_expression ()

call callback for each expression

apply_template ()

apply template virtual function

unapply_template ()

unapply template virtual function

copy ()

copy virtual function

get_copy_type ()

get copy type virtual function

taint ()

taint virtual function

get_properties ()

get properties virtual function

get_property ()

get property virtual function

has_property ()

has property virtual function

add_property ()

add property virtual function

remove_property ()

remove property virtual function

verify_remove_property ()

verify remove property virtual function

clear ()

clear virtual function

equal ()

equal virtual function

compiled ()

compiled signal default handler

resetted ()

resetted signal default handler

tainted ()

tainted signal default handler

copied ()

property_added ()

property added signal default handler

property_removed ()

property added signal default handler

property_changed ()

property added signal default handler

template_applied ()

template_unapplied ()


cpg_object_error_quark ()

GQuark              cpg_object_error_quark              (void);


cpg_object_new ()

CpgObject *         cpg_object_new                      (const gchar *id);

Creates a new CpgObject.

id :

the object id

Returns :

the newly created CpgObject

cpg_object_new_from_template ()

CpgObject *         cpg_object_new_from_template        (CpgObject *templ,
                                                         GError **error);

Create a new CpgObject based on the template templ.

templ :

A CpgObject

Returns :

A CpgObject

cpg_object_get_id ()

const gchar *       cpg_object_get_id                   (CpgObject *object);

Gets the object id

object :

a CpgObject

Returns :

the object id. [transfer none]

cpg_object_set_id ()

void                cpg_object_set_id                   (CpgObject *object,
                                                         const gchar *id);

Sets the object id

object :

a CpgObject

id :

the new object id

cpg_object_add_property ()

gboolean            cpg_object_add_property             (CpgObject *object,
                                                         CpgProperty *property,
                                                         GError **error);

Add a new property to the object. Note that if a property with the same name already exists, the property information is transfered to the existing property instance. This means that the specified property might not actually be added to the object. Also, since a CpgProperty is a GInitiallyUnowned, property will be destroyed after the call to cpg_object_add_property in the above described case, unless you explicitly sink the floating reference.

In the case that you can not know whether a property is overriding an existing property in object, never use property after a call to cpg_object_add_property. Instead, retrieve the corresponding property using cpg_object_get_property after the call to cpg_object_add_property.

object :

the CpgObject

property :

the CpgProperty to add

error :

a GError

Returns :

TRUE if the property was added successfully, FALSE otherwise

cpg_object_get_property ()

CpgProperty *       cpg_object_get_property             (CpgObject *object,
                                                         const gchar *name);

Get a CpgProperty from the object by name

object :

a CpgObject

name :

a property name

Returns :

the CpgProperty with name name, or NULL if no such property could be found. [transfer none][allow-none]

cpg_object_has_property ()

gboolean            cpg_object_has_property             (CpgObject *object,
                                                         const gchar *name);

Get whether object has a property with name name

object :

a CpgObject

name :

a property name

Returns :

TRUE if object has a property with name name, FALSE otherwise

cpg_object_remove_property ()

gboolean            cpg_object_remove_property          (CpgObject *object,
                                                         const gchar *name,
                                                         GError **error);

Remove the property name from object. If the property was not found or could not be removed, error will be appropriately set

object :

a CpgObject

name :

a property name

error :

a GError

Returns :

TRUE if the property could be removed, FALSE otherwise

cpg_object_verify_remove_property ()

gboolean            cpg_object_verify_remove_property   (CpgObject *object,
                                                         const gchar *name,
                                                         GError **error);

Remove the property name from object. If the property was not found or could not be removed, error will be appropriately set

object :

a CpgObject

name :

a property name

error :

a GError

Returns :

TRUE if the property could be removed, FALSE otherwise

cpg_object_get_properties ()

GSList *            cpg_object_get_properties           (CpgObject *object);

Gets the object properties.

object :

a CpgObject

Returns :

a list of CpgProperty. [element-type CpgProperty][transfer container]

cpg_object_get_parent ()

CpgObject *         cpg_object_get_parent               (CpgObject *object);

Get the parent of the object.

object :

A CpgObject

Returns :

A CpgObject. [transfer none]

cpg_object_get_auto_imported ()

gboolean            cpg_object_get_auto_imported        (CpgObject *object);

Get whether the object was automatically imported.

object :

A CpgObject

Returns :

TRUE if the object was automatically imported, FALSE otherwise

cpg_object_set_auto_imported ()

void                cpg_object_set_auto_imported        (CpgObject *object,
                                                         gboolean auto_imported);

Set whether the object was automatically imported.

object :

A CpgObject

auto_imported :

a boolean

cpg_object_reset ()

void                cpg_object_reset                    (CpgObject *object);

Reset all properties to their initial values

object :

the CpgObject

cpg_object_foreach_expression ()

void                cpg_object_foreach_expression       (CpgObject *object,
                                                         CpgForeachExpressionFunc func,
                                                         gpointer userdata);

Iterate over each expression defined in the object. For normal objects, this means all the property expressions. Classes that inherit from CpgObject can implement their own iteration for additional expressions (see for example CpgGroup).

object :

A CpgObject

func :

A CpgForeachExpressionFunc. [scope call]

userdata :

The userdata that will be supplied to func

cpg_object_taint ()

void                cpg_object_taint                    (CpgObject *object);

Mark the object as tainted. This emits the "tainted" signal. The CpgNetwork in which the object is added acts on this signal to mark the network tainted and as such the object will be properly recompiled when the network needs to be simulated

object :

a CpgObject

cpg_object_is_compiled ()

gboolean            cpg_object_is_compiled              (CpgObject *object);

Get whether the object is compiled.

object :

A CpgObject

Returns :

TRUE if the object is compiled, FALSE otherwise

cpg_object_compile ()

gboolean            cpg_object_compile                  (CpgObject *object,
                                                         CpgCompileContext *context);

Compile the object.

object :

A CpgObject

context :

A CpgCompileContext

Returns :

TRUE if the object compiled successfully, FALSE otherwise. If the compilation failed and error was set, the reason for the compile failure is set in error.

cpg_object_equal ()

gboolean            cpg_object_equal                    (CpgObject *first,
                                                         CpgObject *second);

Check if two objects are equal.

first :

A CpgObject

second :

A CpgObject

Returns :

TRUE if the objects are equal, FALSE otherwise

cpg_object_clear ()

void                cpg_object_clear                    (CpgObject *object);

Clear all properties from the object.

object :

A CpgObject

cpg_object_get_actors ()

const GSList *      cpg_object_get_actors               (CpgObject *object);

Get the properties which are acted upon by links.

object :

A CpgObject

Returns :

A GSList of CpgProperty. [element-type CpgProperty][transfer none]

cpg_object_get_applied_templates ()

const GSList *      cpg_object_get_applied_templates    (CpgObject *object);

Get the list of applied templates.

object :

A CpgObject

Returns :

A GSList of CpgObject. [element-type CpgObject][transfer none]

cpg_object_get_template_applies_to ()

const GSList *      cpg_object_get_template_applies_to  (CpgObject *object);

Get the list objects that this object (as a template) applies to

object :

A CpgObject

Returns :

A GSList of CpgObject. [element-type CpgObject][transfer none]

cpg_object_copy ()

CpgObject *         cpg_object_copy                     (CpgObject *object);

Create a copy of the given object. This will create a new object with the same id and with a copy of all the properties defined on the object. The copied object will not have the same links, nor will it have a parent. See the documentation of specific subclasses of CpgObject to see the copy semantics for those classes.

object :

The source object

Returns :

A CpgObject. [transfer full]

cpg_object_apply_template ()

gboolean            cpg_object_apply_template           (CpgObject *object,
                                                         CpgObject *templ,
                                                         GError **error);

Apply a template to the object. This will apply all of the characteristics of the template to the object. Note that object should be of the same type, or inheriting from, the type of templ.

object :

A CpgObject

templ :

The template

error :

The GError

Returns :

TRUE if the template could be successfully applied, FALSE otherwise

cpg_object_unapply_template ()

gboolean            cpg_object_unapply_template         (CpgObject *object,
                                                         CpgObject *templ,
                                                         GError **error);

Unapply a template from the object.

object :

A CpgObject

templ :

The template

error :

The GError

Returns :

TRUE if the template could be successfully unapplied, FALSE otherwise

cpg_object_get_property_template ()

CpgObject *         cpg_object_get_property_template    (CpgObject *object,
                                                         CpgProperty *property,
                                                         gboolean match_full);

Get the template on which property is defined, if any. If match_full is TRUE, the template will only be possitively matched if both properties are equal (i.e. if a property originated from a template, but was later modified, this function will not return the original template object).

object :

A CpgObject

property :

A CpgProperty

match_full :

How to match the property

Returns :

A CpgObject. [transfer none]

cpg_object_get_full_id ()

gchar *             cpg_object_get_full_id              (CpgObject *object);

Get the full id of the object. This is the id that can be used in the outer most parent to refer to this object (i.e. cpg_group_find_object (top_parent, cpg_object_get_full_id (deep_child)) == deep_child)

object :

A CpgObject

Returns :

The full id of the object. This is a newly allocated string that should be freed with g_free.

cpg_object_get_full_id_for_display ()

gchar *             cpg_object_get_full_id_for_display  (CpgObject *object);


cpg_object_get_relative_id ()

gchar *             cpg_object_get_relative_id          (CpgObject *object,
                                                         CpgObject *parent);


cpg_object_get_relative_id_for_display ()

gchar *             cpg_object_get_relative_id_for_display
                                                        (CpgObject *object,
                                                         CpgObject *parent);


cpg_object_get_links ()

const GSList *      cpg_object_get_links                (CpgObject *object);

Get a list of links that act on this object.

object :

A CpgObject

Returns :

A list of CpgLink. [element-type CpgLink]

cpg_object_add_event_handler ()

void                cpg_object_add_event_handler        (CpgObject *object,
                                                         CpgParserCode *code);


cpg_object_remove_event_handler ()

void                cpg_object_remove_event_handler     (CpgObject *object,
                                                         CpgParserCode *code);


cpg_object_get_event_handlers ()

const GSList *      cpg_object_get_event_handlers       (CpgObject *object);


CpgObjectPrivate

typedef struct _CpgObjectPrivate CpgObjectPrivate;

Property Details

The "auto-imported" property

  "auto-imported"            gboolean              : Read / Write / Construct

Set to TRUE when the object was automatically imported.

Default value: FALSE


The "id" property

  "id"                       gchar*                : Read / Write / Construct

The CpgObject id.

Default value: NULL


The "parent" property

  "parent"                   CpgObject*            : Read

The CpgObject parent.

Signal Details

The "compiled" signal

void                user_function                      (CpgObject *object,
                                                        gpointer   user_data)      : Run Last

Emitted when the object is compiled

object :

a CpgObject

user_data :

user data set when the signal handler was connected.

The "copied" signal

void                user_function                      (CpgObject *object,
                                                        CpgObject *copy,
                                                        gpointer   user_data)      : Run Last

Emitted when the object is copied

object :

a CpgObject

copy :

the copy

user_data :

user data set when the signal handler was connected.

The "property-added" signal

void                user_function                      (CpgObject   *object,
                                                        CpgProperty *property,
                                                        gpointer     user_data)      : Run Last

Emitted when a property is added to the object

object :

a CpgObject

property :

the added CpgProperty

user_data :

user data set when the signal handler was connected.

The "property-changed" signal

void                user_function                      (CpgObject   *object,
                                                        CpgProperty *property,
                                                        gpointer     user_data)      : Run Last

Emitted when the expression of a property of the object has changed

object :

a CpgObject

property :

the changed CpgProperty

user_data :

user data set when the signal handler was connected.

The "property-removed" signal

void                user_function                      (CpgObject   *object,
                                                        CpgProperty *property,
                                                        gpointer     user_data)      : Run Last

Emitted when a property is removed from the object

object :

a CpgObject

property :

the removed CpgProperty

user_data :

user data set when the signal handler was connected.

The "resetted" signal

void                user_function                      (CpgObject *object,
                                                        gpointer   user_data)      : Run Last

Emitted when the object is resetted

object :

a CpgObject

user_data :

user data set when the signal handler was connected.

The "tainted" signal

void                user_function                      (CpgObject *object,
                                                        gpointer   user_data)      : Run Last

Emitted when the object is tainted

object :

a CpgObject

user_data :

user data set when the signal handler was connected.

The "template-applied" signal

void                user_function                      (CpgObject *object,
                                                        CpgObject *templ,
                                                        gpointer   user_data)      : Run Last

Emitted when a template is applied to the object

object :

a CpgObject

templ :

the applied CpgObject

user_data :

user data set when the signal handler was connected.

The "template-unapplied" signal

void                user_function                      (CpgObject *object,
                                                        CpgObject *templ,
                                                        gpointer   user_data)      : Run Last

Emitted when a template is unapplied from the object

object :

a CpgObject

templ :

the unapplied CpgObject

user_data :

user data set when the signal handler was connected.

The "verify-remove-property" signal

gboolean            user_function                      (CpgObject *object,
                                                        gchar     *name,
                                                        gpointer   error,
                                                        gpointer   user_data)      : Run Last

Emitted when a property is added to the object

object :

a CpgObject

name :

the property name

error :

the error

user_data :

user data set when the signal handler was connected.

Returns :

TRUE if the property can be removed, FALSE otherwise