OscatsAdministrand

OscatsAdministrand — Administrand Container Class

Synopsis

struct              OscatsAdministrand;
struct              OscatsAdministrandClass;
void                oscats_administrand_freeze          (OscatsAdministrand *item);
void                oscats_administrand_unfreeze        (OscatsAdministrand *item);
void                oscats_administrand_reset_characteristics
                                                        ();
void                oscats_administrand_register_characteristic
                                                        (GQuark characteristic);
GQuark              oscats_administrand_characteristic_from_string
                                                        (const gchar *name);
const gchar *       oscats_administrand_characteristic_as_string
                                                        (GQuark characteristic);
void                oscats_administrand_set_characteristic
                                                        (OscatsAdministrand *administrand,
                                                         GQuark characteristic);
void                oscats_administrand_clear_characteristic
                                                        (OscatsAdministrand *administrand,
                                                         GQuark characteristic);
void                oscats_administrand_clear_characteristics
                                                        (OscatsAdministrand *administrand);
gboolean            oscats_administrand_has_characteristic
                                                        (OscatsAdministrand *administrand,
                                                         GQuark characteristic);
void                oscats_administrand_characteristics_iter_reset
                                                        (OscatsAdministrand *administrand);
GQuark              oscats_administrand_characteristics_iter_next
                                                        (OscatsAdministrand *administrand);
gboolean            oscats_administrand_check_type      (const OscatsAdministrand *item,
                                                         GType type);
gboolean            oscats_administrand_check_model     (const OscatsAdministrand *item,
                                                         GQuark model,
                                                         GType type);
gboolean            oscats_administrand_check_dim_type  (const OscatsAdministrand *item,
                                                         GQuark model,
                                                         OscatsDim type);
gboolean            oscats_administrand_check_space     (const OscatsAdministrand *item,
                                                         GQuark model,
                                                         const OscatsSpace *space);
void                oscats_administrand_set_default_model
                                                        (OscatsAdministrand *item,
                                                         GQuark name);
GQuark              oscats_administrand_get_default_model
                                                        (const OscatsAdministrand *item);
void                oscats_administrand_set_model       (OscatsAdministrand *item,
                                                         GQuark name,
                                                         OscatsModel *model);
void                oscats_administrand_set_model_by_name
                                                        (OscatsAdministrand *item,
                                                         const gchar *name,
                                                         OscatsModel *model);
OscatsModel *       oscats_administrand_get_model       (const OscatsAdministrand *item,
                                                         GQuark name);
OscatsModel *       oscats_administrand_get_model_by_name
                                                        (const OscatsAdministrand *item,
                                                         const gchar *name);

Object Hierarchy

  GObject
   +----OscatsAdministrand
         +----OscatsItemBank
         +----OscatsItem

Properties

  "frozen"                   gboolean              : Read
  "id"                       gchar*                : Read / Write / Construct Only

Description

Details

struct OscatsAdministrand

struct OscatsAdministrand;


struct OscatsAdministrandClass

struct OscatsAdministrandClass {
  void (*freeze) (OscatsAdministrand *item);
  void (*unfreeze) (OscatsAdministrand *item);
  gboolean (*check_type) (const OscatsAdministrand *item, GType type);
  gboolean (*check_model) (const OscatsAdministrand *item, GQuark model, GType type);
  gboolean (*check_dim_type) (const OscatsAdministrand *item, GQuark model, OscatsDim type);
  gboolean (*check_space) (const OscatsAdministrand *item, GQuark model, const OscatsSpace *space);
  void (*set_default_model) (OscatsAdministrand *item, GQuark name);
  GQuark (*get_default_model) (const OscatsAdministrand *item);
  void (*set_model) (OscatsAdministrand *item, GQuark name, OscatsModel *model);
  OscatsModel * (*get_model) (const OscatsAdministrand *item, GQuark name);
};

Note: Implementations of OscatsAdministrand may not provide all functions. Refer to implementation documentation for details. If a function is not provided, the default fails silently (returning FALSE or NULL).

The accessor functions will check type conformity of arguments, so implementation functions need not do so.

freeze ()

Mark all sub-administrands as frozen

unfreeze ()

Unmark all sub-administrands as frozen

check_type ()

Check that all of the administrand's sub-administrands conform to type

check_model ()

Check that administrand has a model named name of sub-classed from type model

check_dim_type ()

Check that administrand's sub-space is of type

check_space ()

Check that the space in which administrand's model is compatible with space

set_default_model ()

Set the default model name for administrand

get_default_model ()

Get the current default model name for administrand

set_model ()

Set a model for the administrand

get_model ()

Fetch the named model from administrand

oscats_administrand_freeze ()

void                oscats_administrand_freeze          (OscatsAdministrand *item);

When an administrand is added to a test (directly or indirectly), changes to its list of models (including which model is set as the default) are no longer permitted. When an OscatsItemBank is added to an OscatsTest, the test calls oscats_administrand_freeze(), and all implementations of OscatsAdministrand must provide OscatsAdministrandClass.freeze to call oscats_administrand_freeze() on all sub-administrands.

item :

an OscatsAdministrand

oscats_administrand_unfreeze ()

void                oscats_administrand_unfreeze        (OscatsAdministrand *item);

When an OscatsTest is disposed, it calls oscats_administrand_unfreeze() to indicate that its administrands are no longer required not to allow changes to their models. If an administrand is added to multiple tests, all of the tests must be disposed before changes are again permitted. Implementations of OscatsAdministrand with sub-administrands should provide OscatsAdministrandClass.unfreeze to call oscats_administrand_unfreeze() on all sub-administrands.

item :

an OscatsAdministrand

oscats_administrand_reset_characteristics ()

void                oscats_administrand_reset_characteristics
                                                        ();

Removes all characteristics from the internal characteristics table. (Useful for more compact memory management if you shift from one large set of characteristics to another in the same program.)


oscats_administrand_register_characteristic ()

void                oscats_administrand_register_characteristic
                                                        (GQuark characteristic);

Adds characteristic to the internal characteristics table. It is more efficient to register all characteristics before creating administrands than to add new characteristics after administrands already exist.

characteristic :

the GQuark characteristic to register

oscats_administrand_characteristic_from_string ()

GQuark              oscats_administrand_characteristic_from_string
                                                        (const gchar *name);

A wrapper of g_quark_from_string() for language bindings.

name :

the string name of the characteristic

Returns :

the characteristic as a GQuark

oscats_administrand_characteristic_as_string ()

const gchar *       oscats_administrand_characteristic_as_string
                                                        (GQuark characteristic);

A wrapper of g_quark_to_string() for language bindings.

characteristic :

a GQuark characteristic

Returns :

the string form of characteristic

oscats_administrand_set_characteristic ()

void                oscats_administrand_set_characteristic
                                                        (OscatsAdministrand *administrand,
                                                         GQuark characteristic);

Indicate that administrand has characteristic. (This will register the characteristic if it has not been already.)

administrand :

an OscatsAdministrand

characteristic :

a GQuark characteristic

oscats_administrand_clear_characteristic ()

void                oscats_administrand_clear_characteristic
                                                        (OscatsAdministrand *administrand,
                                                         GQuark characteristic);

Indicate that administrand does not have characteristic.

administrand :

an OscatsAdministrand

characteristic :

a GQuark characteristic

oscats_administrand_clear_characteristics ()

void                oscats_administrand_clear_characteristics
                                                        (OscatsAdministrand *administrand);

Clear all characteristics for administrand.

administrand :

an OscatsAdministrand

oscats_administrand_has_characteristic ()

gboolean            oscats_administrand_has_characteristic
                                                        (OscatsAdministrand *administrand,
                                                         GQuark characteristic);

administrand :

an OscatsAdministrand

characteristic :

a GQuark characteristic

Returns :

TRUE if administrand has characteristic

oscats_administrand_characteristics_iter_reset ()

void                oscats_administrand_characteristics_iter_reset
                                                        (OscatsAdministrand *administrand);

Reset the characteristics iterator for administrand.

administrand :

an OscatsAdministrand

oscats_administrand_characteristics_iter_next ()

GQuark              oscats_administrand_characteristics_iter_next
                                                        (OscatsAdministrand *administrand);

administrand :

an OscatsAdministrand

Returns :

the next GQuark characteristic that administrand has, or 0 if administrand has no more characteristics

oscats_administrand_check_type ()

gboolean            oscats_administrand_check_type      (const OscatsAdministrand *item,
                                                         GType type);

item :

an OscatsAdministrand

type :

a sub-class of OscatsAdministrand

Returns :

TRUE if all sub-administrands in item are inherited from type

oscats_administrand_check_model ()

gboolean            oscats_administrand_check_model     (const OscatsAdministrand *item,
                                                         GQuark model,
                                                         GType type);

Checks whether the administrand (or all sub-administrands) have a model model and if model inherits from type. Use model = 0 to check the default model.

item :

an OscatsAdministrand

model :

a GQuark identifier for a model name

type :

a sub-class of OscatsModel

Returns :

TRUE if item has model and model inherits from type

oscats_administrand_check_dim_type ()

gboolean            oscats_administrand_check_dim_type  (const OscatsAdministrand *item,
                                                         GQuark model,
                                                         OscatsDim type);

Checks whether the administrand (or all sub-administrands) have a model model and if the subspace for model is of type. Use model = 0 to check the default model.

item :

an OscatsAdministrand

model :

a GQuark identifier for a model name

type :

a dimension type (see OscatsSpace)

Returns :

TRUE if item has model and the subspace of model is type

oscats_administrand_check_space ()

gboolean            oscats_administrand_check_space     (const OscatsAdministrand *item,
                                                         GQuark model,
                                                         const OscatsSpace *space);

Checks whether the administrand (or all sub-administrands) have a model model and if the space for model is compatible with space. Use model = 0 to check the default model.

item :

an OscatsAdministrand

model :

a GQuark identifier for a model name

space :

an OscatsSpace

Returns :

TRUE if item has model and the space of model is compatible with space

oscats_administrand_set_default_model ()

void                oscats_administrand_set_default_model
                                                        (OscatsAdministrand *item,
                                                         GQuark name);

Set the model name as the default for item. Note, an administrand's models may not be changed if it is frozen. See "frozen" and oscats_administrand_freeze().

item :

an OscatsAdministrand

name :

the name of a model (as a GQuark)

oscats_administrand_get_default_model ()

GQuark              oscats_administrand_get_default_model
                                                        (const OscatsAdministrand *item);

Get which model name is set as the default for this administrand. Generally, an administrand's default model will be "default" by default, but this may be implementation-specific.

This function returns the key for the default model. To actually retrieve the OscatsModel itself, use oscats_administrand_get_model().

item :

an OscatsAdministrand

Returns :

the model name for the default model (as a GQuark)

oscats_administrand_set_model ()

void                oscats_administrand_set_model       (OscatsAdministrand *item,
                                                         GQuark name,
                                                         OscatsModel *model);

Set the model model as name for item. If item already has a model name, it is replaced with model. Note, item takes ownership of model.

The name may be 0 to indicate the default model.

Note, an administrand's models may not be changed if it is frozen. See "frozen" and oscats_administrand_freeze().

Generally, model access is fastest for the first models added, so models should be set in order of decreasing expected access frequency. Accessing the default model (by supplying the GQuark 0) is fastest, though.

item :

an OscatsAdministrand

name :

the name of the model (as a GQuark)

model :

the OscatsModel to set. [transfer full]

oscats_administrand_set_model_by_name ()

void                oscats_administrand_set_model_by_name
                                                        (OscatsAdministrand *item,
                                                         const gchar *name,
                                                         OscatsModel *model);

Convenience wrapper for oscats_administrand_set_model().

item :

an OscatsAdministrand

name :

the name of the model

model :

the OscatsModel to set. [transfer full]

oscats_administrand_get_model ()

OscatsModel *       oscats_administrand_get_model       (const OscatsAdministrand *item,
                                                         GQuark name);

Get the model model as name for item. The name may be 0 to indicate the default model.

item :

an OscatsAdministrand

name :

the name of the model (as a GQuark)

Returns :

the model name for item, or NULL if item does not have a model name. [transfer none]

oscats_administrand_get_model_by_name ()

OscatsModel *       oscats_administrand_get_model_by_name
                                                        (const OscatsAdministrand *item,
                                                         const gchar *name);

Convenience wrapper for oscats_administrand_get_model().

item :

an OscatsAdministrand

name :

the name of the model

Returns :

the model name for item, or NULL if item does not have a model name. [transfer none]

Property Details

The "frozen" property

  "frozen"                   gboolean              : Read

Indicates whether changes to the administrand's models are permitted. Once an administrand is added (directly or indirectly) to a test, changes to its list of models are no longer permitted.

Default value: FALSE


The "id" property

  "id"                       gchar*                : Read / Write / Construct Only

A string identifier for the administrand.

Default value: NULL