IpatchItemCopyLinkFunc ()

IpatchItem *        (*IpatchItemCopyLinkFunc)           (IpatchItem *item,
                                                         IpatchItem *link,
                                                         gpointer user_data);

A callback function called during item copy/duplicate operations for any item link reference which needs to be resolved. An example usage is for deep duplicating an object (all references can also be duplicated). Item copy methods should call this for any linked item references which are not part of the new object.

IpatchItem

typedef struct _IpatchItem IpatchItem;

enum IpatchItemFlags

typedef enum
{
  IPATCH_ITEM_HOOKS_ACTIVE = 1 << 0,  /* hook callbacks active? */
  IPATCH_ITEM_FREE_MUTEX   = 1 << 1   /* TRUE if item should free its mutex */
} IpatchItemFlags;

IPATCH_ITEM_UNUSED_FLAG_SHIFT

#define IPATCH_ITEM_UNUSED_FLAG_SHIFT 4

IPATCH_ITEM_WLOCK()

#define             IPATCH_ITEM_WLOCK(item)

IPATCH_ITEM_WUNLOCK()

#define             IPATCH_ITEM_WUNLOCK(item)

IPATCH_ITEM_RLOCK()

#define IPATCH_ITEM_RLOCK(item)		IPATCH_ITEM_WLOCK(item)

IPATCH_ITEM_RUNLOCK()

#define IPATCH_ITEM_RUNLOCK(item) IPATCH_ITEM_WUNLOCK(item)

IPATCH_ITEM_PROP_NOTIFY_SET_EVENT()

#define             IPATCH_ITEM_PROP_NOTIFY_SET_EVENT(info, index, data, destroy)

A macro for assigning per event pointers to IpatchItemPropNotify.

IpatchItemPropCallback ()

void                (*IpatchItemPropCallback)           (IpatchItemPropNotify *notify);

IpatchItem property change callback function prototype.

IpatchItemPropDisconnect ()

void                (*IpatchItemPropDisconnect)         (IpatchItem *item,
                                                         GParamSpec *pspec,
                                                         gpointer user_data);

Function prototype which gets called when a property notify callback gets disconnected.

IPATCH_ITEM_COPY_LINK_FUNC()

#define             IPATCH_ITEM_COPY_LINK_FUNC(item, link, func, userdata)

ipatch_item_pspec_title

extern GParamSpec *ipatch_item_pspec_title;

ipatch_item_set_parent ()

void                ipatch_item_set_parent              (IpatchItem *item,
                                                         IpatchItem *parent);

Usually only used by IpatchItem type implementations. Sets the parent of a patch item. Also recursively sets base parent and IPATCH_ITEM_HOOKS_ACTIVE flag if set in parent. Also assigns the item's thread mutex to that of the parent if its class has mutex_slave set. The parent container is responsible for adding a reference to item - this function does not do so.

NOTE: If the item has mutex_slave set in its class then the item will use parent object's mutex. During the call to this function item should not be accessed by any other threads, otherwise problems may occur when the mutex is changed. Normally this shouldn't be much of an issue, since new item's are often only accessed by 1 thread until being parented.

ipatch_item_unparent ()

void                ipatch_item_unparent                (IpatchItem *item);

Usually only used by IpatchItem type implementations. Unparent an item. Also recursively unsets base parent and IPATCH_ITEM_HOOKS_ACTIVE flag. Parent container object is responsible for removing reference of item - this function does not do so.

ipatch_item_get_parent ()

IpatchItem *        ipatch_item_get_parent              (IpatchItem *item);

Gets the parent of item after incrementing its reference count. The caller is responsible for decrementing the reference count with g_object_unref when finished with it. This function is useful because all code paths must contain references to the items that they are working with in a multi-thread environment (there is no guarantee an item won't be destroyed unless a refcount is held).

ipatch_item_peek_parent ()

IpatchItem *        ipatch_item_peek_parent             (IpatchItem *item);

This function is the same as ipatch_item_get_parent() (gets an item's parent) but does not increment the parent's ref count. Therefore this function should only be used when the caller already holds a reference or when only the value of the pointer will be used (not the contents), to avoid multi-thread problems.

ipatch_item_get_base ()

IpatchItem *        ipatch_item_get_base                (IpatchItem *item);

Gets the base parent of item (toplevel patch file object) after incrementing its reference count. The caller is responsible for decrementing the reference count with g_object_unref when finished with it. If item is itself a IpatchBase object then it is returned.

ipatch_item_peek_base ()

IpatchItem *        ipatch_item_peek_base               (IpatchItem *item);

This function is the same as ipatch_item_get_base() (gets an item's toplevel base parent) but does not increment the parent's ref count. Therefore this function should only be used when the caller already holds a reference or when only the value of the pointer will be used (not the contents), to avoid multi-thread problems.

ipatch_item_get_ancestor_by_type ()

IpatchItem *        ipatch_item_get_ancestor_by_type    (IpatchItem *item,
                                                         GType ancestor_type);

Searches for the first parent item that is derived from ancestor_type in the item object's ancestry. ancestor_type must be an IpatchItem derived type (as well as the ancestry of item). Of note is that item can also match. The returned item's reference count has been incremented and it is the responsiblity of the caller to remove it with g_object_unref() when finished with it.

ipatch_item_peek_ancestor_by_type ()

IpatchItem *        ipatch_item_peek_ancestor_by_type   (IpatchItem *item,
                                                         GType ancestor_type);

Just like ipatch_item_get_ancestor_by_type() but doesn't ref returned item. This should only be used when caller already owns a reference or only the pointer value is of importance, since otherwise there is a potential multi-thread race condition.

ipatch_item_remove ()

void                ipatch_item_remove                  (IpatchItem *item);

This function removes an item from its parent container and removes other references from within the same patch (e.g., a IpatchSF2Sample will be removed from its parent IpatchSF2 and all IpatchSF2IZone objects referencing the sample will also be removed).

ipatch_item_changed ()

void                ipatch_item_changed                 (IpatchItem *item);

This function should be called when an item's saveable state (what ends up in a patch file) has changed. Causes the item object's base parent to have its changed flag set, indicating that the file has changes that have not been saved. Note that this function is automatically called when an ipatch_item_prop_notify() occurs for a property without the IPATCH_PARAM_NO_SAVE_CHANGE flag in its GParamSpec and therefore this function should not be called additionally.

ipatch_item_get_property_fast ()

void                ipatch_item_get_property_fast       (IpatchItem *item,
                                                         GParamSpec *pspec,
                                                         GValue *value);

Usually only used by IpatchItem implementations. A faster way to retrieve an object property. Often used for fetching current value for property notifies. Notice that this function currently doesn't work with interface or class overridden properties.

ipatch_item_copy ()

void                ipatch_item_copy                    (IpatchItem *dest,
                                                         IpatchItem *src);

Copy an item using the item class' "copy" method. Object links are copied as is, meaning the resulting object is a local object to the same IpatchBase.

ipatch_item_copy_link_func ()

void                ipatch_item_copy_link_func          (IpatchItem *dest,
                                                         IpatchItem *src,
                                                         IpatchItemCopyLinkFunc link_func,
                                                         gpointer user_data);

Copy an item using the item class' "copy" method. Like ipatch_item_copy() but takes a link_func which can be used for handling replication of externally linked objects (recursively deep duplicate for example, although there is ipatch_item_duplicate_deep() specifically for that).

ipatch_item_copy_replace ()

void                ipatch_item_copy_replace            (IpatchItem *dest,
                                                         IpatchItem *src,
                                                         GHashTable *repl_hash);

Like ipatch_item_copy() but takes a link replacement hash, which can be used for substituting different objects for object links. See ipatch_item_copy_link_func() if even more flexibility is desired.

ipatch_item_duplicate ()

IpatchItem *        ipatch_item_duplicate               (IpatchItem *item);

A convenience function to duplicate an item. Like ipatch_item_copy() but creates a new duplicate item, rather than using an existing item. Note that externally linked objects are not duplicated for non IpatchBase derived types, making the item local to the same IpatchBase object.

ipatch_item_duplicate_link_func ()

IpatchItem *        ipatch_item_duplicate_link_func     (IpatchItem *item,
                                                         IpatchItemCopyLinkFunc link_func,
                                                         gpointer user_data);

Like ipatch_item_copy_link_func() but duplicates the item instead of copying to an existing item.

ipatch_item_duplicate_replace ()

IpatchItem *        ipatch_item_duplicate_replace       (IpatchItem *item,
                                                         GHashTable *repl_hash);

Like ipatch_item_copy_replace() but duplicates the item instead of copying it to an already created item.

ipatch_item_duplicate_deep ()

IpatchList *        ipatch_item_duplicate_deep          (IpatchItem *item);

Recursively duplicate an item (i.e., its dependencies also).

ipatch_item_copy_link_func_deep ()

IpatchItem *        ipatch_item_copy_link_func_deep     (IpatchItem *item,
                                                         IpatchItem *link,
                                                         gpointer user_data);

ipatch_item_copy_link_func_hash ()

IpatchItem *        ipatch_item_copy_link_func_hash     (IpatchItem *item,
                                                         IpatchItem *link,
                                                         gpointer user_data);

A predefined IpatchItemCopyLinkFunc which takes a hash for the user_data component, which is used for replacing link pointers. link is used as the hash key, the hash value is used in its place if present otherwise link is used unchanged.

ipatch_item_type_can_conflict ()

gboolean            ipatch_item_type_can_conflict       (GType item_type);

Test if a given IpatchItem derived type can conflict with another item (only applies to items of the same type in the same IpatchBase object).

ipatch_item_type_get_unique_specs ()

GParamSpec **       ipatch_item_type_get_unique_specs   (GType item_type,
                                                         guint32 *groups);

Get the list of unique parameter specs which can conflict for a given item type.

ipatch_item_get_unique_props ()

GValueArray *       ipatch_item_get_unique_props        (IpatchItem *item);

Get the values of the unique properties for item. This is useful when doing conflict detection processing and more flexibility is desired than with ipatch_item_test_conflict().

ipatch_item_test_conflict ()

guint               ipatch_item_test_conflict           (IpatchItem *item1,
                                                         IpatchItem *item2);

Test if two items would conflict if they were siblings (doesn't actually test if they are siblings).

ipatch_item_set_atomic ()

void                ipatch_item_set_atomic              (gpointer item,
                                                         const char *first_property_name,
                                                         ...);

Sets properties on a patch item atomically (i.e. item is multi-thread locked while all properties are set). This avoids critical parameter sync problems when multiple threads are accessing the same item. See g_object_set() for more information on setting properties.

ipatch_item_get_atomic ()

void                ipatch_item_get_atomic              (gpointer item,
                                                         const char *first_property_name,
                                                         ...);

Gets properties from a patch item atomically (i.e. item is multi-thread locked while all properties are retrieved). This avoids critical parameter sync problems when multiple threads are accessing the same item. See g_object_get() for more information on getting properties.

ipatch_item_first ()

IpatchItem *        ipatch_item_first                   (IpatchIter *iter);

Gets the first item in a patch item iterator. A convenience wrapper for ipatch_iter_first().

ipatch_item_next ()

IpatchItem *        ipatch_item_next                    (IpatchIter *iter);

Gets the next item in a patch item iterator. A convenience wrapper for ipatch_iter_next().

ipatch_item_prop_notify ()

void                ipatch_item_prop_notify             (IpatchItem *item,
                                                         GParamSpec *pspec,
                                                         const GValue *new_value,
                                                         const GValue *old_value);

Usually only used by IpatchItem object implementations, rather than explicitly called by the user. It should be called AFTER item property changes that occur outside of the IpatchItem item_set_property method.

ipatch_item_prop_notify_by_name ()

void                ipatch_item_prop_notify_by_name     (IpatchItem *item,
                                                         const char *prop_name,
                                                         const GValue *new_value,
                                                         const GValue *old_value);

Usually only used by IpatchItem object implementations, rather than explicitly called by the user. Like ipatch_item_prop_notify() except takes a property name instead of a parameter spec, for added convenience.

ipatch_item_prop_connect ()

guint               ipatch_item_prop_connect            (IpatchItem *item,
                                                         GParamSpec *pspec,
                                                         IpatchItemPropCallback callback,
                                                         IpatchItemPropDisconnect disconnect,
                                                         gpointer user_data);

Connect a callback for a specific IpatchItem and property. If a property change occurs for the given item and pspec then the callback is invoked. The parameters item and/or pspec may be NULL for wild card matching (if both are NULL then callback will be called for all IpatchItem property changes).

ipatch_item_prop_connect_by_name ()

guint               ipatch_item_prop_connect_by_name    (IpatchItem *item,
                                                         const char *prop_name,
                                                         IpatchItemPropCallback callback,
                                                         IpatchItemPropDisconnect disconnect,
                                                         gpointer user_data);

Like ipatch_item_prop_add_callback() but takes the name of a property\ instead of the parameter spec, for added convenience.

ipatch_item_prop_disconnect ()

void                ipatch_item_prop_disconnect         (guint handler_id);

Disconnects an IpatchItem property change callback handler by its ID.

ipatch_item_prop_disconnect_matched ()

void                ipatch_item_prop_disconnect_matched (IpatchItem *item,
                                                         GParamSpec *pspec,
                                                         IpatchItemPropCallback callback,
                                                         gpointer user_data);

Disconnects first IpatchItem property change callback matching all the function parameters. Note: Only the pointer values of item and pspec are used so they don't actually need to be valid anymore.

ipatch_item_prop_disconnect_by_name ()

void                ipatch_item_prop_disconnect_by_name (IpatchItem *item,
                                                         const char *prop_name,
                                                         IpatchItemPropCallback callback,
                                                         gpointer user_data);

Like ipatch_item_prop_disconnect_matched() but takes a name of the property to match instead of a parameter spec, for added convenience. Note: item must still be valid (to look up the property), contrary to ipatch_item_prop_disconnect_matched().

The "base" property

  "base"                     IpatchBase*           : Read

Base.

The "flags" property

  "flags"                    guint                 : Read / Write

Flags.

Default value: 0

The "parent" property

  "parent"                   IpatchItem*           : Read / Write

Parent.

The "title" property

  "title"                    gchar*                : Read

Title.

Default value: NULL