src/core/na-pivot.h

   1 /*
   2  * Nautilus-Actions
   3  * A Nautilus extension which offers configurable context menu pivots.
   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 __CORE_NA_PIVOT_H__
  32 #define __CORE_NA_PIVOT_H__
  33
  34 /* @title: NAPivot
  35  * @short_description: The #NAPivot Class Definition
  36  * @include: core/na-pivot.h
  37  *
  38  * A consuming program should allocate one new NAPivot object in its
  39  * startup phase. The class takes care of declaring the I/O interfaces,
  40  * while registering the known providers.
  41  *              NAPivot *pivot = na_pivot_new();
  42  *
  43  * With this newly allocated #NAPivot object, the consuming program
  44  * is then able to ask for loading the items.
  45  *              na_pivot_set_loadable( pivot, PIVOT_LOADABLE_SET );
  46  *              na_pivot_load_items( pivot );
  47  *
  48  * Notification system.
  49  *
  50  * The NAPivot object acts as a sort of "summarizing relay" for notification
  51  * messages sent by I/O storage providers:
  52  *
  53  * - When an I/O storage subsystem detects a change on an item it manages,
  54  *   action or menu, it is first supposed to do its best effort in order
  55  *   to summarize its notifications messages;
  56  *
  57  * - At the end of this first stage of summarization, the I/O provider
  58  *   should call the na_iio_provider_item_changed() function, which
  59  *   itself will emit the "io-provider-item-changed" signal.
  60  *   This is done so that an external I/O provider does not have to know
  61  *   anything with the signal name, but has only to take care of calling
  62  *   a function of the NAIIOProvider API.
  63  *
  64  * - The emitted signal is catched by na_pivot_on_item_changed_handler(),
  65  *   which was connected when the I/O provider plugin was associated with
  66  *   the NAIOProvider object.
  67  *
  68  * - The NAPivot object receives these notifications originating from all
  69  *   loaded I/O providers, itself summarizes them, and only then notify its
  70  *   consumers with only one message for a whole set of modifications.
  71  *
  72  * It is eventually up to the consumer to connect to this signal, and
  73  * choose itself whether to reload items or not.
  74  */
  75
  76 #include <api/na-iio-provider.h>
  77 #include <api/na-object-api.h>
  78
  79 #include "na-settings.h"
  80
  81 G_BEGIN_DECLS
  82
  83 #define NA_PIVOT_TYPE                ( na_pivot_get_type())
  84 #define NA_PIVOT( object )           ( G_TYPE_CHECK_INSTANCE_CAST( object, NA_PIVOT_TYPE, NAPivot ))
  85 #define NA_PIVOT_CLASS( klass )      ( G_TYPE_CHECK_CLASS_CAST( klass, NA_PIVOT_TYPE, NAPivotClass ))
  86 #define NA_IS_PIVOT( object )        ( G_TYPE_CHECK_INSTANCE_TYPE( object, NA_PIVOT_TYPE ))
  87 #define NA_IS_PIVOT_CLASS( klass )   ( G_TYPE_CHECK_CLASS_TYPE(( klass ), NA_PIVOT_TYPE ))
  88 #define NA_PIVOT_GET_CLASS( object ) ( G_TYPE_INSTANCE_GET_CLASS(( object ), NA_PIVOT_TYPE, NAPivotClass ))
  89
  90 typedef struct _NAPivotPrivate       NAPivotPrivate;
  91
  92 typedef struct {
  93         /*< private >*/
  94         GObject         parent;
  95         NAPivotPrivate *private;
  96 }
  97         NAPivot;
  98
  99 typedef struct _NAPivotClassPrivate  NAPivotClassPrivate;
 100
 101 typedef struct {
 102         /*< private >*/
 103         GObjectClass         parent;
 104         NAPivotClassPrivate *private;
 105 }
 106         NAPivotClass;
 107
 108 GType    na_pivot_get_type( void );
 109
 110 /* properties
 111  */
 112 #define PIVOT_PROP_LOADABLE                                             "pivot-prop-loadable"
 113 #define PIVOT_PROP_TREE                                                 "pivot-prop-tree"
 114
 115 /* signals
 116  *
 117  * NAPivot acts as a 'summarizing' proxy for signals emitted by the
 118  * NAIIOProvider providers when they detect a modification in their
 119  * underlying items storage subsystems.
 120  *
 121  * As several to many signals may be emitted when such a modification occurs,
 122  * NAPivot summarizes all these signals in an only one 'items-changed' event.
 123  */
 124 #define PIVOT_SIGNAL_ITEMS_CHANGED                              "pivot-items-changed"
 125
 126 /* Loadable population
 127  * NACT management user interface defaults to PIVOT_LOAD_ALL
 128  * N-A plugin set the loadable population to !PIVOT_LOAD_DISABLED & !PIVOT_LOAD_INVALID
 129  */
 130 typedef enum {
 131         PIVOT_LOAD_NONE     = 0,
 132         PIVOT_LOAD_DISABLED = 1 << 0,
 133         PIVOT_LOAD_INVALID  = 1 << 1,
 134         PIVOT_LOAD_ALL      = 0xff
 135 }
 136         NAPivotLoadableSet;
 137
 138 NAPivot      *na_pivot_new ( void );
 139 void          na_pivot_dump( const NAPivot *pivot );
 140
 141 /* Management of the plugins which claim to implement a Nautilus-Actions interface.
 142  * As of 2.30, these may be NAIIOProvider, NAIImporter or NAIExporter
 143  */
 144 GList        *na_pivot_get_providers ( const NAPivot *pivot, GType type );
 145 void          na_pivot_free_providers( GList *providers );
 146
 147 /* Items, menus and actions, management
 148  */
 149 NAObjectItem *na_pivot_get_item     ( const NAPivot *pivot, const gchar *id );
 150 GList        *na_pivot_get_items    ( const NAPivot *pivot );
 151 void          na_pivot_load_items   ( NAPivot *pivot );
 152 void          na_pivot_set_new_items( NAPivot *pivot, GList *tree );
 153
 154 void          na_pivot_on_item_changed_handler( NAIIOProvider *provider, NAPivot *pivot  );
 155
 156 /* NAPivot properties and configuration
 157  */
 158 void          na_pivot_set_loadable     ( NAPivot *pivot, guint loadable );
 159
 160 G_END_DECLS
 161
 162 #endif /* __CORE_NA_PIVOT_H__ */