src/core/fma-pivot.h

   1 /*
   2  * FileManager-Actions
   3  * A file-manager extension which offers configurable context menu pivots.
   4  *
   5  * Copyright (C) 2005 The GNOME Foundation
   6  * Copyright (C) 2006-2008 Frederic Ruaudel and others (see AUTHORS)
   7  * Copyright (C) 2009-2015 Pierre Wieser and others (see AUTHORS)
   8  *
   9  * FileManager-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  * FileManager-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 FileManager-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 __CORE_FMA_PIVOT_H__
  31 #define __CORE_FMA_PIVOT_H__
  32
  33 /* @title: FMAPivot
  34  * @short_description: The #FMAPivot Class Definition
  35  * @include: core/fma-pivot.h
  36  *
  37  * A consuming program should allocate one new FMAPivot object in its
  38  * startup phase. The class takes care of declaring the I/O interfaces,
  39  * while registering the known providers.
  40  *              FMAPivot *pivot = fma_pivot_new();
  41  *
  42  * With this newly allocated #FMAPivot object, the consuming program
  43  * is then able to ask for loading the items.
  44  *              fma_pivot_set_loadable( pivot, PIVOT_LOADABLE_SET );
  45  *              fma_pivot_load_items( pivot );
  46  *
  47  * Notification system.
  48  *
  49  * The FMAPivot object acts as a sort of "summarizing relay" for notification
  50  * messages sent by I/O storage providers:
  51  *
  52  * - When an I/O storage subsystem detects a change on an item it manages,
  53  *   action or menu, it is first supposed to do its best effort in order
  54  *   to summarize its notifications messages;
  55  *
  56  * - At the end of this first stage of summarization, the I/O provider
  57  *   should call the fma_iio_provider_item_changed() function, which
  58  *   itself will emit the "io-provider-item-changed" signal.
  59  *   This is done so that an external I/O provider does not have to know
  60  *   anything with the signal name, but has only to take care of calling
  61  *   a function of the FMAIIOProvider API.
  62  *
  63  * - The emitted signal is catched by fma_pivot_on_item_changed_handler(),
  64  *   which was connected when the I/O provider plugin was associated with
  65  *   the FMAIOProvider object.
  66  *
  67  * - The FMAPivot object receives these notifications originating from all
  68  *   loaded I/O providers, itself summarizes them, and only then notify its
  69  *   consumers with only one message for a whole set of modifications.
  70  *
  71  * It is eventually up to the consumer to connect to this signal, and
  72  * choose itself whether to reload items or not.
  73  */
  74
  75 #include <api/fma-iio-provider.h>
  76 #include <api/fma-object-api.h>
  77
  78 #include "fma-settings.h"
  79
  80 G_BEGIN_DECLS
  81
  82 #define FMA_TYPE_PIVOT                ( fma_pivot_get_type())
  83 #define FMA_PIVOT( object )           ( G_TYPE_CHECK_INSTANCE_CAST( object, FMA_TYPE_PIVOT, FMAPivot ))
  84 #define FMA_PIVOT_CLASS( klass )      ( G_TYPE_CHECK_CLASS_CAST( klass, FMA_TYPE_PIVOT, FMAPivotClass ))
  85 #define FMA_IS_PIVOT( object )        ( G_TYPE_CHECK_INSTANCE_TYPE( object, FMA_TYPE_PIVOT ))
  86 #define FMA_IS_PIVOT_CLASS( klass )   ( G_TYPE_CHECK_CLASS_TYPE(( klass ), FMA_TYPE_PIVOT ))
  87 #define FMA_PIVOT_GET_CLASS( object ) ( G_TYPE_INSTANCE_GET_CLASS(( object ), FMA_TYPE_PIVOT, FMAPivotClass ))
  88
  89 typedef struct _FMAPivotPrivate       FMAPivotPrivate;
  90
  91 typedef struct {
  92         /*< private >*/
  93         GObject          parent;
  94         FMAPivotPrivate *private;
  95 }
  96         FMAPivot;
  97
  98 typedef struct _FMAPivotClassPrivate  FMAPivotClassPrivate;
  99
 100 typedef struct {
 101         /*< private >*/
 102         GObjectClass          parent;
 103         FMAPivotClassPrivate *private;
 104 }
 105         FMAPivotClass;
 106
 107 GType    fma_pivot_get_type( void );
 108
 109 /* properties
 110  */
 111 #define PIVOT_PROP_LOADABLE                                             "pivot-prop-loadable"
 112 #define PIVOT_PROP_TREE                                                 "pivot-prop-tree"
 113
 114 /* signals
 115  *
 116  * FMAPivot acts as a 'summarizing' proxy for signals emitted by the
 117  * FMAIIOProvider providers when they detect a modification in their
 118  * underlying items storage subsystems.
 119  *
 120  * As several to many signals may be emitted when such a modification occurs,
 121  * FMAPivot summarizes all these signals in an only one 'items-changed' event.
 122  */
 123 #define PIVOT_SIGNAL_ITEMS_CHANGED                              "pivot-items-changed"
 124
 125 /* Loadable population
 126  * fma-config-tool user interface defaults to PIVOT_LOAD_ALL
 127  * FMA plugin set the loadable population to !PIVOT_LOAD_DISABLED & !PIVOT_LOAD_INVALID
 128  */
 129 typedef enum {
 130         PIVOT_LOAD_NONE     = 0,
 131         PIVOT_LOAD_DISABLED = 1 << 0,
 132         PIVOT_LOAD_INVALID  = 1 << 1,
 133         PIVOT_LOAD_ALL      = 0xff
 134 }
 135         FMAPivotLoadableSet;
 136
 137 FMAPivot      *fma_pivot_new                    ( void );
 138 void           fma_pivot_dump                   ( const FMAPivot *pivot );
 139
 140 /* Management of the plugins which claim to implement a FileManager-Actions interface.
 141  * As of 2.30, these may be FMAIIOProvider, FMAIImporter or FMAIExporter
 142  */
 143 GList         *fma_pivot_get_providers          ( const FMAPivot *pivot, GType type );
 144 void           fma_pivot_free_providers         ( GList *providers );
 145
 146 /* Items, menus and actions, management
 147  */
 148 FMAObjectItem *fma_pivot_get_item               ( const FMAPivot *pivot, const gchar *id );
 149 GList         *fma_pivot_get_items              ( const FMAPivot *pivot );
 150 void           fma_pivot_load_items             ( FMAPivot *pivot );
 151 void           fma_pivot_set_new_items          ( FMAPivot *pivot, GList *tree );
 152
 153 void           fma_pivot_on_item_changed_handler( FMAIIOProvider *provider, FMAPivot *pivot  );
 154
 155 /* FMAPivot properties and configuration
 156  */
 157 void           fma_pivot_set_loadable           ( FMAPivot *pivot, guint loadable );
 158
 159 G_END_DECLS
 160
 161 #endif /* __CORE_FMA_PIVOT_H__ */