ModelDictionary

ModelDictionary — an immutable mapping from string to ModelReference

Description

ModelDictionary is a lookup table of strings, mapping to ModelReference instances. It is immutable in the sense that keys may not be be added or removed and that the ModelReference pointed to by each key remains the same. The ModelReference itself is of course mutable.

Details

ModelDictionary

typedef struct {
  ModelObject parent_instance;
} ModelDictionary;

This is an opaque structure; it may not be accessed directly.


ModelDictionaryClass

typedef struct {
  ModelObjectClass parent_class;

  ModelReference * (*get_reference) (ModelDictionary *dictionary,
                                     const gchar     *key);
  ModelObject *    (*get_value)     (ModelDictionary *dictionary,
                                     const gchar     *key);
  gchar **         (*list_keys)     (ModelDictionary *dictionary,
                                     gint            *length);
} ModelDictionaryClass;

The class structure for ModelDictionary. All virtual functions must be implemented by each subclass.

ModelObjectClass parent_class;

get_reference ()

virtual function pointer for model_dictionary_get_reference()

get_value ()

virtual function pointer for model_dictionary_get_value()

list_keys ()

virtual function pointer for model_dictionary_list_keys()

model_dictionary_get_reference ()

ModelReference *    model_dictionary_get_reference      (ModelDictionary *dictionary,
                                                         const gchar *key);

Gets a ModelReference object corresponding to key on dictionary. key must be a valid key on the dictionary.

Using this function (instead of model_dictionary_get_value()) allows you to watch for changes in the value of the key. Any changes to the value of a key will be result in the "changed" signal being emitted on the reference object returned by this function.

It is appropriate for the caller to call g_object_unref() on the return value.

dictionary :

a ModelDictionary

key :

the key to fetch the reference for

returns :

a ModelReference for the key, owned by the caller

model_dictionary_get_value ()

ModelObject *       model_dictionary_get_value          (ModelDictionary *dictionary,
                                                         const gchar *key);

Gets a ModelObject corresponding to the current value of key on dictionary. key must be a valid key on the dictionary.

This function is equivalent to calling model_dictionary_get_reference() and model_reference_get_value() but is often substantially more efficient (since the model implementation need not setup watches for change notification).

It is appropriate for the caller to call g_object_unref() on the return value.

dictionary :

a ModelDictionary

key :

the key to fetch the reference for

returns :

a ModelObject for the key, owned by the caller

model_dictionary_list_keys ()

gchar **            model_dictionary_list_keys          (ModelDictionary *dictionary,
                                                         gint *length);

Gets a list of the keys on dictionary.

If length is non-NULL then it will be set to the number of items in the array that is returned. It is appropriate for the caller to call g_strfreev() on the return value.

This function allows dictionaries to be introspected for purposes of debugging and testing, but if your model is well-constructed then you should know which keys are on your dictionary objects.

dictionary :

a ModelDictionary

length :

a pointer to the number of keys returned, or NULL

returns :

a list of the keys on the dictionary, owned by the caller