IpatchPaste

IpatchPaste — Object paste instance

Stability Level

Stable, unless otherwise indicated

Functions

Types and Values

Object Hierarchy

    GObject
    ╰── IpatchPaste

Description

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

Functions

IpatchPasteTestFunc ()

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

Test if a paste handler can handle the paste operation.

Parameters

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.

Parameters

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).


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.

[skip]

Parameters

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.

[type IpatchPastePriority]

ipatch_register_paste_handler_full ()

int
ipatch_register_paste_handler_full (IpatchPasteTestFunc test_func,
                                    IpatchPasteExecFunc exec_func,
                                    GDestroyNotify notify_func,
                                    gpointer user_data,
                                    int flags);

Registers a handler function to paste objects for which test_func returns TRUE. Like ipatch_register_paste_handler() but is friendly to GObject Introspection.

[rename-to ipatch_register_paste_handler]

Parameters

test_func

Callback function to test if a paste operation is handled.

[scope notified]

exec_func

Paste execution function.

[scope notified]

notify_func

Called when paste handler is unregistered.

[nullable][scope async][closure user_data]

user_data

Data to pass to notify_func or NULL.

[nullable]

flags

Currently just a value from IpatchPastePriority or 0 for default priority.

[type IpatchPastePriority]

Returns

Handler ID, which can be used to unregister it or -1 if invalid parameters

Since: 1.1.0


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 .

Parameters

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.

Parameters

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).

Parameters

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.

Parameters

paste

Paste object

 

resolve_func

Resolve callback function which is invoked for each conflict.

[scope call][closure user_data]

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).

Parameters

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.

Parameters

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.

[transfer full]


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.

Parameters

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.

[nullable]

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.

Parameters

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).

[transfer none]


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.

Parameters

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).

[transfer none]


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.

Parameters

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.

[out][optional]

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.

Parameters

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).

Parameters

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).

Parameters

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).

Types and Values

enum IpatchPasteChoice

Members

IPATCH_PASTE_CHOICE_IGNORE

   

IPATCH_PASTE_CHOICE_REPLACE

   

IPATCH_PASTE_CHOICE_KEEP

   

IPATCH_PASTE_CHOICE_CANCEL

   

enum IpatchPastePriority

Members

IPATCH_PASTE_PRIORITY_LOWEST

   

IPATCH_PASTE_PRIORITY_LOW

   

IPATCH_PASTE_PRIORITY_DEFAULT

   

IPATCH_PASTE_PRIORITY_HIGH

   

IPATCH_PASTE_PRIORITY_HIGHEST

   

IPATCH_PASTE_FLAGS_PRIORITY_MASK

#define IPATCH_PASTE_FLAGS_PRIORITY_MASK   0x7F