src/api/na-iduplicable.h

   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, 2007, 2008 Frederic Ruaudel and others (see AUTHORS)
   7  * Copyright (C) 2009, 2010, 2011 Pierre Wieser and others (see AUTHORS)
   8  *
   9  * This Program 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  * This Program 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
  17  * GNU General Public License for more details.
  18  *
  19  * You should have received a copy of the GNU General Public
  20  * License along with this Library; see the file COPYING.  If not,
  21  * write to the Free Software Foundation, Inc., 59 Temple Place,
  22  * Suite 330, Boston, MA 02111-1307, USA.
  23  *
  24  * Authors:
  25  *   Frederic Ruaudel <grumz@grumz.net>
  26  *   Rodrigo Moya <rodrigo@gnome-db.org>
  27  *   Pierre Wieser <pwieser@trychlos.org>
  28  *   ... and many others (see AUTHORS)
  29  */
  30
  31 #ifndef __NAUTILUS_ACTIONS_API_NA_IDUPLICABLE_H__
  32 #define __NAUTILUS_ACTIONS_API_NA_IDUPLICABLE_H__
  33
  34 /**
  35  * SECTION: iduplicable
  36  * @title: NAIDuplicable
  37  * @short_description: The Duplication Interface
  38  * @include: nautilus-actions/private/na-iduplicable.h
  39  *
  40  * This interface is implemented by #NAObject in order to let
  41  * #NAObject -derived instance duplication be easily tracked. This works
  42  * by keeping a pointer on the original object at duplication time, and
  43  * then only checking edition status when explicitely required.
  44  *
  45  * As the reference count of the original object is not incremented
  46  * here, the caller has to garantee itself that the original object
  47  * will stay in life at least as long as the duplicated one.
  48  *
  49  * <refsect2>
  50  *  <title>
  51  *   Modification status in Nautilus-Actions configuration tool
  52  *  </title>
  53  *  <itemizedlist>
  54  *   <listitem>
  55  *    <para>
  56  *     Objects whose origin is NULL are considered as modified ; this is
  57  *     in particular the case of new, pasted, imported and dropped
  58  *     objects.
  59  *    </para>
  60  *   </listitem>
  61  *   <listitem>
  62  *    <para>
  63  *     when a new object, whether is is really new or it has been pasted,
  64  *     imported or dropped, is inserted somewhere in the tree, its
  65  *     immediate parent is also marked as modified.
  66  *    </para>
  67  *   </listitem>
  68  *   <listitem>
  69  *    <para>
  70  *     Check for edition status, which positions modification and validity
  71  *     status, is not recursive ; it is the responsability of the
  72  *     implementation to check for edition status of children of object..
  73  *    </para>
  74  *   </listitem>
  75  *  </itemizedlist>
  76  * </refsect2>
  77  *
  78  * <refsect2>
  79  *  <title>Versions historic</title>
  80  *  <table>
  81  *    <title>Historic of the versions of the #NAIDuplicable interface</title>
  82  *    <tgroup rowsep="1" colsep="1" align="center" cols="3">
  83  *      <colspec colname="na-version" />
  84  *      <colspec colname="api-version" />
  85  *      <colspec colname="current" />
  86  *      <thead>
  87  *        <row>
  88  *          <entry>&prodname; version</entry>
  89  *          <entry>#NAIDuplicable interface version</entry>
  90  *          <entry></entry>
  91  *        </row>
  92  *      </thead>
  93  *      <tbody>
  94  *        <row>
  95  *          <entry>since 2.30</entry>
  96  *          <entry>1</entry>
  97  *          <entry>current version</entry>
  98  *        </row>
  99  *      </tbody>
 100  *    </tgroup>
 101  *  </table>
 102  * </refsect2>
 103  */
 104
 105 #include <glib-object.h>
 106
 107 G_BEGIN_DECLS
 108
 109 #define NA_IDUPLICABLE_TYPE                      ( na_iduplicable_get_type())
 110 #define NA_IDUPLICABLE( instance )               ( G_TYPE_CHECK_INSTANCE_CAST( instance, NA_IDUPLICABLE_TYPE, NAIDuplicable ))
 111 #define NA_IS_IDUPLICABLE( instance )            ( G_TYPE_CHECK_INSTANCE_TYPE( instance, NA_IDUPLICABLE_TYPE ))
 112 #define NA_IDUPLICABLE_GET_INTERFACE( instance ) ( G_TYPE_INSTANCE_GET_INTERFACE(( instance ), NA_IDUPLICABLE_TYPE, NAIDuplicableInterface ))
 113
 114 typedef struct _NAIDuplicable                    NAIDuplicable;
 115 typedef struct _NAIDuplicableInterfacePrivate    NAIDuplicableInterfacePrivate;
 116
 117 /**
 118  * NAIDuplicableInterface:
 119  * @copy:      copies one object to another.
 120  * @are_equal: tests if two objects are equals.
 121  * @is_valid:  tests if one object is valid.
 122  *
 123  * This interface is implemented by #NAObject objects, in order to be able
 124  * to keep the trace of all duplicated objects.
 125  */
 126 typedef struct {
 127         /*< private >*/
 128         GTypeInterface                 parent;
 129         NAIDuplicableInterfacePrivate *private;
 130
 131         /*< public >*/
 132         /**
 133          * copy:
 134          * @target: the #NAIDuplicable target of the copy.
 135          * @source: the #NAIDuplicable source of the copy
 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 );
 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 GType          na_iduplicable_get_type( void );
 194
 195 void           na_iduplicable_dispose     ( const NAIDuplicable *object );
 196 void           na_iduplicable_dump        ( const NAIDuplicable *object );
 197 NAIDuplicable *na_iduplicable_duplicate   ( const NAIDuplicable *object );
 198 void           na_iduplicable_check_status( const NAIDuplicable *object );
 199
 200 NAIDuplicable *na_iduplicable_get_origin  ( const NAIDuplicable *object );
 201 gboolean       na_iduplicable_is_valid    ( const NAIDuplicable *object );
 202 gboolean       na_iduplicable_is_modified ( const NAIDuplicable *object );
 203
 204 void           na_iduplicable_set_origin  ( NAIDuplicable *object, const NAIDuplicable *origin );
 205
 206 void           na_iduplicable_register_consumer( GObject *consumer );
 207
 208 #ifndef NA_DISABLE_DEPRECATED
 209 void           na_iduplicable_set_modified( NAIDuplicable *object, gboolean modified );
 210 #endif
 211
 212 G_END_DECLS
 213
 214 #endif /* __NAUTILUS_ACTIONS_API_NA_IDUPLICABLE_H__ */