1 /* 2 * Nautilus-Actions 3 * A Nautilus extension which offers configurable context menu actions. 4 * 5 * Copyright (C) 2005 The GNOME Foundation 6 * Copyright (C) 2006-2008 Frederic Ruaudel and others (see AUTHORS) 7 * Copyright (C) 2009-2014 Pierre Wieser and others (see AUTHORS) 8 * 9 * Nautilus-Actions is free software; you can redistribute it and/or 10 * modify it under the terms of the GNU General Public License as 11 * published by the Free Software Foundation; either version 2 of 12 * the License, or (at your option) any later version. 13 * 14 * Nautilus-Actions is distributed in the hope that it will be useful, 15 * but WITHOUT ANY WARRANTY; without even the implied warranty of 16 * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE. See the GNU 17 * General Public License for more details. 18 * 19 * You should have received a copy of the GNU General Public License 20 * along with Nautilus-Actions; see the file COPYING. If not, see 21 * <http://www.gnu.org/licenses/>. 22 * 23 * Authors: 24 * Frederic Ruaudel <grumz@grumz.net> 25 * Rodrigo Moya <rodrigo@gnome-db.org> 26 * Pierre Wieser <pwieser@trychlos.org> 27 * ... and many others (see AUTHORS) 28 */ 29 30 #ifndef __NAUTILUS_ACTIONS_API_NA_IDUPLICABLE_H__ 31 #define __NAUTILUS_ACTIONS_API_NA_IDUPLICABLE_H__ 32 33 /** 34 * SECTION: iduplicable 35 * @title: NAIDuplicable 36 * @short_description: The Duplication Interface 37 * @include: nautilus-actions/private/na-iduplicable.h 38 * 39 * This interface is implemented by #NAObject in order to let 40 * #NAObject -derived instance duplication be easily tracked. This works 41 * by keeping a pointer on the original object at duplication time, and 42 * then only checking edition status when explicitely required. 43 * 44 * As the reference count of the original object is not incremented 45 * here, the caller has to garantee itself that the original object 46 * will stay in life at least as long as the duplicated one. 47 * 48 * <refsect2> 49 * <title> 50 * Modification status in Nautilus-Actions configuration tool 51 * </title> 52 * <itemizedlist> 53 * <listitem> 54 * <para> 55 * Objects whose origin is NULL are considered as modified ; this is 56 * in particular the case of new, pasted, imported and dropped 57 * objects. 58 * </para> 59 * </listitem> 60 * <listitem> 61 * <para> 62 * when a new object, whether is is really new or it has been pasted, 63 * imported or dropped, is inserted somewhere in the tree, its 64 * immediate parent is also marked as modified. 65 * </para> 66 * </listitem> 67 * <listitem> 68 * <para> 69 * Check for edition status, which positions modification and validity 70 * status, is not recursive ; it is the responsability of the 71 * implementation to check for edition status of children of object.. 72 * </para> 73 * </listitem> 74 * </itemizedlist> 75 * </refsect2> 76 * 77 * <refsect2> 78 * <title>Versions historic</title> 79 * <table> 80 * <title>Historic of the versions of the #NAIDuplicable interface</title> 81 * <tgroup rowsep="1" colsep="1" align="center" cols="3"> 82 * <colspec colname="na-version" /> 83 * <colspec colname="api-version" /> 84 * <colspec colname="current" /> 85 * <thead> 86 * <row> 87 * <entry>&prodname; version</entry> 88 * <entry>#NAIDuplicable interface version</entry> 89 * <entry></entry> 90 * </row> 91 * </thead> 92 * <tbody> 93 * <row> 94 * <entry>since 2.30</entry> 95 * <entry>1</entry> 96 * <entry>current version</entry> 97 * </row> 98 * </tbody> 99 * </tgroup> 100 * </table> 101 * </refsect2> 102 */ 103 104 #include <glib-object.h> 105 106 G_BEGIN_DECLS 107 108 #define NA_TYPE_IDUPLICABLE ( na_iduplicable_get_type()) 109 #define NA_IDUPLICABLE( instance ) ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_TYPE_IDUPLICABLE, NAIDuplicable )) 110 #define NA_IS_IDUPLICABLE( instance ) ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_TYPE_IDUPLICABLE )) 111 #define NA_IDUPLICABLE_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_TYPE_IDUPLICABLE, NAIDuplicableInterface )) 112 113 typedef struct _NAIDuplicable NAIDuplicable; 114 typedef struct _NAIDuplicableInterfacePrivate NAIDuplicableInterfacePrivate; 115 116 /** 117 * NAIDuplicableInterface: 118 * @copy: copies one object to another. 119 * @are_equal: tests if two objects are equals. 120 * @is_valid: tests if one object is valid. 121 * 122 * This interface is implemented by #NAObject objects, in order to be able 123 * to keep the trace of all duplicated objects. 124 */ 125 typedef struct { 126 /*< private >*/ 127 GTypeInterface parent; 128 NAIDuplicableInterfacePrivate *private; 129 130 /*< public >*/ 131 /** 132 * copy: 133 * @target: the #NAIDuplicable target of the copy. 134 * @source: the #NAIDuplicable source of the copy. 135 * @mode: the duplication mode. 136 * 137 * Copies data from @source to @ŧarget, so that @target becomes an 138 * exact copy of @source. 139 * 140 * Each derived class of the implementation should define this 141 * function to copy its own data. The implementation should take 142 * care itself of calling each function in the class hierarchy, 143 * from topmost base class to most-derived one. 144 * 145 * Since: 2.30 146 */ 147 void ( *copy ) ( NAIDuplicable *target, const NAIDuplicable *source, guint mode ); 148 149 /** 150 * are_equal: 151 * @a: a first #NAIDuplicable object. 152 * @b: a second #NAIDuplicable object to be compared to the first 153 * one. 154 * 155 * Compares the two objects. 156 * 157 * Each derived class of the implementation should define this 158 * function to compare its own data. The implementation should take 159 * care itself of calling each function in the class hierarchy, 160 * from topmost base class to most-derived one. 161 * 162 * When testing for the modification status of an object, @a stands for 163 * the original object, while @b stands for the duplicated one. 164 * 165 * Returns: TRUE if @a and @b are identical, FALSE else. 166 * 167 * Since: 2.30 168 */ 169 gboolean ( *are_equal ) ( const NAIDuplicable *a, const NAIDuplicable *b ); 170 171 /** 172 * is_valid: 173 * @object: the NAIDuplicable object to be checked. 174 * 175 * Checks @object for validity. 176 * 177 * Each derived class of the implementation should define this 178 * function to compare its own data. The implementation should take 179 * care itself of calling each function in the class hierarchy, 180 * from topmost base class to most-derived one. 181 * 182 * Returns: TRUE if @object is valid, FALSE else. 183 * 184 * Since: 2.30 185 */ 186 gboolean ( *is_valid ) ( const NAIDuplicable *object ); 187 } 188 NAIDuplicableInterface; 189 190 #define IDUPLICABLE_SIGNAL_MODIFIED_CHANGED "iduplicable-modified-changed" 191 #define IDUPLICABLE_SIGNAL_VALID_CHANGED "iduplicable-valid-changed" 192 193 /** 194 * DuplicateMode: 195 * @DUPLICATE_ONLY: only duplicates the provided object. 196 * @DUPLICATE_OBJECT: only duplicate a menu 197 * (a menu with some subitems is duplicated to an empty menu) 198 * @DUPLICATE_REC: recursively duplicates all the provided hierarchy. 199 */ 200 typedef enum { 201 DUPLICATE_ONLY = 1, 202 DUPLICATE_OBJECT, 203 DUPLICATE_REC 204 } 205 DuplicableMode; 206 207 GType na_iduplicable_get_type ( void ); 208 209 void na_iduplicable_dispose ( const NAIDuplicable *object ); 210 void na_iduplicable_dump ( const NAIDuplicable *object ); 211 NAIDuplicable *na_iduplicable_duplicate ( const NAIDuplicable *object, guint mode ); 212 void na_iduplicable_check_status ( const NAIDuplicable *object ); 213 214 NAIDuplicable *na_iduplicable_get_origin ( const NAIDuplicable *object ); 215 gboolean na_iduplicable_is_valid ( const NAIDuplicable *object ); 216 gboolean na_iduplicable_is_modified ( const NAIDuplicable *object ); 217 218 void na_iduplicable_set_origin ( NAIDuplicable *object, const NAIDuplicable *origin ); 219 220 void na_iduplicable_register_consumer( GObject *consumer ); 221 222 #ifdef NA_ENABLE_DEPRECATED 223 void na_iduplicable_set_modified( NAIDuplicable *object, gboolean modified ); 224 #endif 225 226 G_END_DECLS 227 228 #endif /* __NAUTILUS_ACTIONS_API_NA_IDUPLICABLE_H__ */ 229