src/api/na-object.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_OBJECT_H__
  32 #define __NAUTILUS_ACTIONS_API_NA_OBJECT_H__
  33
  34 /**
  35  * SECTION: object
  36  * @title: NAObject
  37  * @short_description: The Deepest Base Class Definition
  38  * @include: nautilus-actions/na-object.h
  39  *
  40  * This is the base class of all our data object hierarchy. #NAObject is
  41  * supposed to be used as a pure virtual base class, i.e. should only be
  42  * derived.
  43  *
  44  * All the API described here is rather private. External code should
  45  * use the API described in <na-object-api.h>.
  46  */
  47
  48 #include <glib-object.h>
  49
  50 G_BEGIN_DECLS
  51
  52 #define NA_OBJECT_TYPE                ( na_object_object_get_type())
  53 #define NA_OBJECT( object )           ( G_TYPE_CHECK_INSTANCE_CAST( object, NA_OBJECT_TYPE, NAObject ))
  54 #define NA_OBJECT_CLASS( klass )      ( G_TYPE_CHECK_CLASS_CAST( klass, NA_OBJECT_TYPE, NAObjectClass ))
  55 #define NA_IS_OBJECT( object )        ( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_OBJECT_TYPE ))
  56 #define NA_IS_OBJECT_CLASS( klass )   ( G_TYPE_CHECK_CLASS_TYPE(( klass ), NA_OBJECT_TYPE ))
  57 #define NA_OBJECT_GET_CLASS( object ) ( G_TYPE_INSTANCE_GET_CLASS(( object ), NA_OBJECT_TYPE, NAObjectClass ))
  58
  59 typedef struct _NAObjectPrivate       NAObjectPrivate;
  60
  61 typedef struct {
  62         /*< private >*/
  63         GObject          parent;
  64         NAObjectPrivate *private;
  65 }
  66         NAObject;
  67
  68 typedef struct _NAObjectClassPrivate  NAObjectClassPrivate;
  69
  70 /**
  71  * NAObjectClass:
  72  * @dump:      Dumps the #NAObject -part of the #NAObject -derived object.
  73  * @copy:      Copies a #NAObject to another.
  74  * @are_equal: Tests if two #NAObject are equal.
  75  * @is_valid:  Tests if a #NAObject is valid.
  76  *
  77  * The #NAObjectClass defines some methods available to derived classes.
  78  */
  79 typedef struct {
  80         /*< private >*/
  81         GObjectClass          parent;
  82         NAObjectClassPrivate *private;
  83
  84         /*< public >*/
  85         /**
  86          * dump:
  87          * @object: the NAObject-derived object to be dumped.
  88          *
  89          * Dumps via g_debug the content of the object.
  90          *
  91          * NAObject class takes care of calling this function for each
  92          * derived class, starting from topmost base class up to most-
  93          * derived one. Each derived class has so only to take care of
  94          * dumping its own data.
  95          *
  96          * Since: 2.30
  97          */
  98         void     ( *dump )     ( const NAObject *object );
  99
 100         /**
 101          * copy:
 102          * @target: the NAObject-derived object which will receive data.
 103          * @source: the NAObject-derived object which will provide data.
 104          * @recursive: whether children should be recursively copied.
 105          *
 106          * Copies data and properties from @source to @target.
 107          *
 108          * Each derived class should take care of implementing this function
 109          * when relevant. NAObject class will take care of calling this
 110          * function for each class of the hierarchy, starting from topmost
 111          * base class up to the most-derived one. Each class has so only to
 112          * take care of dumping its own data.
 113          *
 114          * Since: 2.30
 115          */
 116         void     ( *copy )     ( NAObject *target, const NAObject *source, gboolean recursive );
 117
 118         /**
 119          * are_equal:
 120          * @a: a first NAObject object.
 121          * @b: a second NAObject object to be compared to the first one.
 122          *
 123          * Compares the two objects.
 124          *
 125          * Each derived class should take care of implementing this function
 126          * when relevant. NAObject class will take care of calling this
 127          * function for each class of the hierarchy, starting from topmost
 128          * base class up to the most-derived one, at least while result
 129          * stays at TRUE.
 130          * As soon as a difference is detected, the calling sequence will
 131          * be stopped, and the result returned.
 132          *
 133          * Returns: TRUE if @a and @b are identical, FALSE else.
 134          *
 135          * Since: 2.30
 136          */
 137         gboolean ( *are_equal )( const NAObject *a, const NAObject *b );
 138
 139         /**
 140          * is_valid:
 141          * @object: the NAObject object to be checked.
 142          *
 143          * Checks @object for validity.
 144          *
 145          * A NAObject is valid if its internal identifier is set.
 146          *
 147          * Each derived class should take care of implementing this function
 148          * when relevant. NAObject class will take care of calling this
 149          * function for each class of the hierarchy, starting from topmost
 150          * base class up to the most-derived one, at least while result
 151          * stays at TRUE.
 152          * As soon as a difference is detected, the calling sequence will
 153          * be stopped, and the result returned.
 154          *
 155          * Returns: TRUE if @object is valid, FALSE else.
 156          *
 157          * Since: 2.30
 158          */
 159         gboolean ( *is_valid ) ( const NAObject *object );
 160 }
 161         NAObjectClass;
 162
 163 GType     na_object_object_get_type( void );
 164
 165 void      na_object_object_check_status_rec( const NAObject *object );
 166
 167 void      na_object_object_reset_origin   ( NAObject *object, const NAObject *origin );
 168
 169 NAObject *na_object_object_ref  ( NAObject *object );
 170 void      na_object_object_unref( NAObject *object );
 171
 172 void      na_object_object_copy      ( NAObject *target, const NAObject *source, gboolean recursive );
 173
 174 void      na_object_object_dump      ( const NAObject *object );
 175 void      na_object_object_dump_norec( const NAObject *object );
 176 void      na_object_object_dump_tree ( GList *tree );
 177
 178 GList    *na_object_object_get_hierarchy( const NAObject *object );
 179 void      na_object_free_hierarchy( GList *hierarchy );
 180
 181 void      na_object_object_debug_invalid( const NAObject *object, const gchar *reason );
 182
 183 G_END_DECLS
 184
 185 #endif /* __NAUTILUS_ACTIONS_API_NA_OBJECT_H__ */