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