## IpatchPaste IpatchPaste — Object paste instance |

## Stability Level

Stable, unless otherwise indicated

## Synopsis

                        IpatchPaste;
    enum                IpatchPasteChoice;
    gboolean            (*IpatchPasteTestFunc)              (IpatchItem *dest,
                                                             IpatchItem *src);
    gboolean            (*IpatchPasteExecFunc)              (IpatchPaste *paste,
                                                             IpatchItem *dest,
                                                             IpatchItem *src,
                                                             GError **err);
    enum                IpatchPastePriority;
    #define             IPATCH_PASTE_FLAGS_PRIORITY_MASK
    void                ipatch_register_paste_handler       (IpatchPasteTestFunc test_func,
                                                             IpatchPasteExecFunc exec_func,
                                                             int flags);
    gboolean            ipatch_is_paste_possible            (IpatchItem *dest,
                                                             IpatchItem *src);
    gboolean            ipatch_simple_paste                 (IpatchItem *dest,
                                                             IpatchItem *src,
                                                             GError **err);
    IpatchPaste *       ipatch_paste_new                    (void);
    gboolean            ipatch_paste_objects                (IpatchPaste *paste,
                                                             IpatchItem *dest,
                                                             IpatchItem *src,
                                                             GError **err);
    gboolean            ipatch_paste_resolve                (IpatchPaste *paste,
                                                             IpatchPasteResolveFunc resolve_func,
                                                             gpointer user_data);
    gboolean            ipatch_paste_finish                 (IpatchPaste *paste,
                                                             GError **err);
    IpatchList *        ipatch_paste_get_add_list           (IpatchPaste *paste);
    void                ipatch_paste_object_add             (IpatchPaste *paste,
                                                             IpatchItem *additem,
                                                             IpatchContainer *parent,
                                                             IpatchItem *orig);
    IpatchItem *        ipatch_paste_object_add_duplicate   (IpatchPaste *paste,
                                                             IpatchItem *item,
                                                             IpatchContainer *parent);
    IpatchItem *        ipatch_paste_object_add_duplicate_deep
                                                            (IpatchPaste *paste,
                                                             IpatchItem *item,
                                                             IpatchContainer *parent);
    gboolean            ipatch_paste_object_add_convert     (IpatchPaste *paste,
                                                             GType conv_type,
                                                             IpatchItem *item,
                                                             IpatchContainer *parent,
                                                             IpatchList **item_list,
                                                             GError **err);
    void                ipatch_paste_object_link            (IpatchPaste *paste,
                                                             IpatchItem *from,
                                                             IpatchItem *to);
    gboolean            ipatch_paste_default_test_func      (IpatchItem *dest,
                                                             IpatchItem *src);
    gboolean            ipatch_paste_default_exec_func      (IpatchPaste *paste,
                                                             IpatchItem *dest,
                                                             IpatchItem *src,
                                                             GError **err);

## Object Hierarchy

      GObject
       +----IpatchPaste

## Description

This object provides a system and instance for doing cut/paste operations on instrument items.

## Details

### IpatchPaste

    typedef struct _IpatchPaste IpatchPaste;

### enum IpatchPasteChoice

    typedef enum
    {
      IPATCH_PASTE_CHOICE_IGNORE,	/* item will be pasted (conflict remains) */
      IPATCH_PASTE_CHOICE_REPLACE,	/* replace item */
      IPATCH_PASTE_CHOICE_KEEP,	/* keep existing item (reverse replace) */
      IPATCH_PASTE_CHOICE_CANCEL	/* cancel the current operation */
    } IpatchPasteChoice;

### IpatchPasteTestFunc ()

    gboolean            (*IpatchPasteTestFunc)              (IpatchItem *dest,
                                                             IpatchItem *src);

Test if a paste handler can handle the paste operation.

`dest` : | Destination item of paste operation
`src` : | Source item of paste operation
Returns : | `TRUE` if paste supported by this handler, `FALSE` otherwise

### IpatchPasteExecFunc ()

    gboolean            (*IpatchPasteExecFunc)              (IpatchPaste *paste,
                                                             IpatchItem *dest,
                                                             IpatchItem *src,
                                                             GError **err);

Perform the construction phase of the paste operation. This includes every action up to the point of actually adding/linking objects. All object addition and linking operations are stored in `paste` instance to be executed after resolving conflicts, etc.

`paste` : | Paste object
`dest` : | Destination item of paste operation
`src` : | Source item of paste operation
`err` : | Location to store error information
Returns : | `TRUE` on success, `FALSE` on error (in which case `err` may be set).

### enum IpatchPastePriority

    typedef enum
    {
      /* 0 value is an alias for IPATCH_PASTE_PRIORITY_DEFAULT */

      IPATCH_PASTE_PRIORITY_LOWEST  = 1,
      IPATCH_PASTE_PRIORITY_LOW     = 25,
      IPATCH_PASTE_PRIORITY_DEFAULT = 50,
      IPATCH_PASTE_PRIORITY_HIGH    = 75,
      IPATCH_PASTE_PRIORITY_HIGHEST = 100
    } IpatchPastePriority;

### IPATCH_PASTE_FLAGS_PRIORITY_MASK

    #define IPATCH_PASTE_FLAGS_PRIORITY_MASK   0x7F

### ipatch_register_paste_handler ()

    void                ipatch_register_paste_handler       (IpatchPasteTestFunc test_func,
                                                             IpatchPasteExecFunc exec_func,
                                                             int flags);

Registers a handler function to paste objects for which `test_func` returns `TRUE`.

`test_func` : | Callback function to test if a paste operation is handled
`exec_func` : | Paste execution function
`flags` : | Currently just a value from IpatchPastePriority or 0 for default priority.

### ipatch_is_paste_possible ()

    gboolean            ipatch_is_paste_possible            (IpatchItem *dest,
                                                             IpatchItem *src);

Check if the given items can be pasted from `src` to `dest`.

`dest` : | Destination item
`src` : | Source item
Returns : | `TRUE` if paste is possible, `FALSE` otherwise

### ipatch_simple_paste ()

    gboolean            ipatch_simple_paste                 (IpatchItem *dest,
                                                             IpatchItem *src,
                                                             GError **err);

Simple paste of a single `src` item to `dest` item. Any conflicts are ignored which means that conflicts will remain and should be resolved.

`dest` : | Destination item to paste to
`src` : | Source item
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise in which case `err` should be set.

### ipatch_paste_new ()

    IpatchPaste *       ipatch_paste_new                    (void);

### ipatch_paste_objects ()

    gboolean            ipatch_paste_objects                (IpatchPaste *paste,
                                                             IpatchItem *dest,
                                                             IpatchItem *src,
                                                             GError **err);

Setup a paste operation. Multiple item pastes can occur for the same `paste` instance. Existing duplicated items are used if present (example: if multiple instruments are pasted between different IpatchBase objects and they link to the same sample, they will both use the same sample in the final paste operation).

`paste` : | Paste object
`dest` : | Destination item of paste
`src` : | Source item of paste
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set)

### ipatch_paste_resolve ()

    gboolean            ipatch_paste_resolve                (IpatchPaste *paste,
                                                             IpatchPasteResolveFunc resolve_func,
                                                             gpointer user_data);

This function is used to make choices as to how conflicts are resolved. Conflicting objects are those with identical unique property values. For each conflicting object that would result from a paste, the `resolve_func` is called allowing a choice to be made as to how it is handled. The default choice is to ignore the duplicate, resulting in conflicting objects. This function can be executed multiple times, the choices are only executed once `ipatch_paste_finish()` is called.

`paste` : | Paste object
`resolve_func` : | Resolve callback function which is invoked for each conflict.
`user_data` : | User defined data to pass to `resolve_func`.
Returns : | `TRUE` on success, `FALSE` if operation was canceled (`resolve_func` returned IPATCH_PASTE_CHOICE_CANCEL).

### ipatch_paste_finish ()

    gboolean            ipatch_paste_finish                 (IpatchPaste *paste,
                                                             GError **err);

Complete the paste operation(s) (add/link objects). Conflicts are handled for the choices made with `ipatch_paste_resolve()` (defaults to ignore which will result in conflicts).

`paste` : | Paste object
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_paste_get_add_list ()

    IpatchList *        ipatch_paste_get_add_list           (IpatchPaste *paste);

Get list of objects to add with paste operation. This can be called after `ipatch_paste_objects()` or after `ipatch_paste_finish()`. In the first case the objects have not yet been added, in the second case the paste operation has been completed. The list of objects returned are only those which are not conflicting or a choice of IPATCH_PASTE_CHOICE_IGNORE or IPATCH_PASTE_CHOICE_REPLACE was selected.

`paste` : | Paste object
Returns : | List of objects being added with paste operation or `NULL` if none. Returned list has a refcount of 1 which the caller owns, unref when done.

### ipatch_paste_object_add ()

    void                ipatch_paste_object_add             (IpatchPaste *paste,
                                                             IpatchItem *additem,
                                                             IpatchContainer *parent,
                                                             IpatchItem *orig);

Used by IpatchPasteExecFunc handlers. Adds an object addition operation to a paste instance.

`paste` : | Paste object
`additem` : | New item to add.
`parent` : | Container to parent `additem` to.
`orig` : | Original item associated with `additem` (if duplicated for example). If supplied then an association between the `orig` object and the `additem` will be made, and any references to `orig` of subsequent deep duplications will use the new `additem` instead.

### ipatch_paste_object_add_duplicate ()

    IpatchItem *        ipatch_paste_object_add_duplicate   (IpatchPaste *paste,
                                                             IpatchItem *item,
                                                             IpatchContainer *parent);

Used by IpatchPasteExecFunc handlers. Duplicates an item and adds an addition operation to a paste instance. Useful for duplicating an object within the same IpatchBase parent. For this reason the duplicated item is automatically forced to be unique and no association is added for `item` to the new duplicate.

`paste` : | Paste object
`item` : | Item to duplicate and add
`parent` : | Container to parent duplicated item to.
Returns : | The new duplicate of `item` (no reference added for caller).

### ipatch_paste_object_add_duplicate_deep ()

    IpatchItem *        ipatch_paste_object_add_duplicate_deep
                                                            (IpatchPaste *paste,
                                                             IpatchItem *item,
                                                             IpatchContainer *parent);

Used by IpatchPasteExecFunc handlers. Deep duplicates `item` and registers it as an add to `parent` in the `paste` operation, also registers all new duplicated dependencies of `item`. Any existing matching duplicate items in the `paste` instance are used rather than duplicating them again.

`paste` : | Paste object
`item` : | Item to deep duplicate and add.
`parent` : | Container to parent `item` to.
Returns : | The new duplicate of `item` (no reference added for caller).

### ipatch_paste_object_add_convert ()

    gboolean            ipatch_paste_object_add_convert     (IpatchPaste *paste,
                                                             GType conv_type,
                                                             IpatchItem *item,
                                                             IpatchContainer *parent,
                                                             IpatchList **item_list,
                                                             GError **err);

Used by IpatchPasteExecFunc handlers. Converts `item` using an IpatchConverter of type `conv_type` and registers it as an add to `parent` in the `paste` operation, also registers all new dependencies of `item`. Any existing matching converted item dependencies in the `paste` instance are used rather than duplicating them again.

`paste` : | Paste object
`conv_type` : | IpatchConverter derived type to use for conversion.
`item` : | Item to convert and add.
`parent` : | Container to parent converted item to.
`item_list` : | Location to store pointer to the list of added items or `NULL` to ignore. Caller owns a reference to the list.
`err` : | Location to store error info or `NULL` to ignore.
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).

### ipatch_paste_object_link ()

    void                ipatch_paste_object_link            (IpatchPaste *paste,
                                                             IpatchItem *from,
                                                             IpatchItem *to);

Used by IpatchPasteExecFunc handlers. Registers a link operation.

`paste` : | Paste object
`from` : | Item to link from
`to` : | Item to link to

### ipatch_paste_default_test_func ()

    gboolean            ipatch_paste_default_test_func      (IpatchItem *dest,
                                                             IpatchItem *src);

Default IpatchPasteTestFunc. Useful for alternative paste implementations which would like to chain to the default function (to override only specific object types for example).

`dest` : | Destination item of paste operation
`src` : | Source item of paste operation
Returns : | `TRUE` if paste supported by this handler, `FALSE` otherwise

### ipatch_paste_default_exec_func ()

    gboolean            ipatch_paste_default_exec_func      (IpatchPaste *paste,
                                                             IpatchItem *dest,
                                                             IpatchItem *src,
                                                             GError **err);

Default IpatchPasteExecFunc. Useful for alternative paste implementations which would like to chain to the default function (to override only specific object types for example).

`paste` : | Paste object
`src` : | Source object of paste
`dest` : | Destination object of paste
`err` : | Location to store error info or `NULL`
Returns : | `TRUE` on success, `FALSE` otherwise (in which case `err` may be set).