Commit d1ae2196 authored by Pierre Wieser's avatar Pierre Wieser

Global review of the notification systems

+ NAPivot always acts as a summarizing relay for items changes from i/o providers
+ NASettings always enables a pre-key callback preregistration system
+ NASettings now also have its own signal notification system, only distinguishing between
  runtime and user preferences.
parent 2d361969
2011-01-24 Pierre Wieser <pwieser@trychlos.org>
* src/core/na-pivot.c:
* src/core/na-pivot.h: Review the notification system.
* src/core/na-settings.c:
* src/core/na-settings.h:
Add a signal notification to the existing callback pregistration system.
* data/gconf-schemas/nautilus-actions-prefs.schemas.in:
* docs/des-ema/des-ema-0.15:
* docs/nact/C/nact-conditions.xml:
......
......@@ -117,7 +117,7 @@ static NAObjectItem *get_item_from_tree( const NAPivot *pivot, GList *tree, cons
static void free_consumers( GList *list );
/* NAIIOProvider management */
static void on_item_changed_timeout( NAPivot *pivot );
static void on_items_changed_timeout( NAPivot *pivot );
GType
na_pivot_get_type( void )
......@@ -186,7 +186,7 @@ class_init( NAPivotClass *klass )
/*
* NAPivot::pivot-items-changed:
*
* This signal is sent by NAPivot ath the end of a burst of modifications
* This signal is sent by NAPivot at the end of a burst of modifications
* as signaled by i/o providers.
*
* The signal is registered without any default handler.
......@@ -228,7 +228,7 @@ instance_init( GTypeInstance *instance, gpointer klass )
/* initialize timeout parameters for 'item-changed' handler
*/
self->private->change_timeout.timeout = st_burst_timeout;
self->private->change_timeout.handler = ( NATimeoutFunc ) on_item_changed_timeout;
self->private->change_timeout.handler = ( NATimeoutFunc ) on_items_changed_timeout;
self->private->change_timeout.user_data = self;
self->private->change_timeout.source_id = 0;
}
......@@ -619,9 +619,13 @@ na_pivot_set_new_items( NAPivot *pivot, GList *items )
*
* This handler is trigerred by #NAIIOProvider providers when an action
* is changed in their underlying storage subsystems.
*
* The NAIIOProvider is supposed to have itself already summarized
* a minima its own burst of notifications.
*
* We don't care of updating our internal list with each and every
* atomic modification; instead we wait for the end of notifications
* serie, and then reload the whole list of actions
* serie, and then signal our consumers.
*/
void
na_pivot_on_item_changed_handler( NAIIOProvider *provider, NAPivot *pivot )
......@@ -645,16 +649,18 @@ na_pivot_on_item_changed_handler( NAIIOProvider *provider, NAPivot *pivot )
* this is up to NAPivot to send now its summarized signal
*/
static void
on_item_changed_timeout( NAPivot *pivot )
on_items_changed_timeout( NAPivot *pivot )
{
static const gchar *thisfn = "na_pivot_on_item_changed_timeout";
GList *ic;
static const gchar *thisfn = "na_pivot_on_items_changed_timeout";
g_return_if_fail( NA_IS_PIVOT( pivot ));
g_debug( "%s: emitting %s signal", thisfn, PIVOT_SIGNAL_ITEMS_CHANGED );
g_signal_emit_by_name(( gpointer ) pivot, PIVOT_SIGNAL_ITEMS_CHANGED );
#if 0
GList *ic;
/* this has to be deprecated.. or not ?? */
g_debug( "%s: triggering NAIPivotConsumer interfaces", thisfn );
if( pivot->private->automatic_reload ){
......@@ -663,6 +669,7 @@ on_item_changed_timeout( NAPivot *pivot )
for( ic = pivot->private->consumers ; ic ; ic = ic->next ){
na_ipivot_consumer_notify_of_items_changed( NA_IPIVOT_CONSUMER( ic->data ));
}
#endif
}
/*
......@@ -727,13 +734,13 @@ na_pivot_get_settings( const NAPivot *pivot )
* na_pivot_set_automatic_reload:
* @pivot: this #NAPivot instance.
* @reload: whether this #NAPivot instance should automatically reload
* its list of actions when I/O providers advertize it of a
* its list of actions when I/O providers advertise it of a
* modification.
*
* Sets the automatic reload flag.
*
* Note that even if the #NAPivot instance is not authorized to
* automatically reload its list of actions when it is advertized of
* automatically reload its list of actions when it is advertised of
* a modification by one of the I/O providers, it always sends an
* ad-hoc notification to its consumers.
*/
......
......@@ -42,41 +42,35 @@
*
* With this newly allocated #NAPivot object, the consuming program
* is then able to ask for loading the items.
* na_pivot_load_items( pivot, PIVOT_LOADABLE_SET );
* na_pivot_set_loadable( pivot, PIVOT_LOADABLE_SET );
* na_pivot_load_items( pivot );
*
* Notification system.
*
* Each I/O storage provider should monitor modifications/deletions of
* actions, and advertize this #NAPivot, which itself will then
* advertise any registered consumers.
* The NAPivot object acts as a sort of "summarizing relay" for notification
* messages sent by I/O storage providers:
*
* This notification system is so a double-stage one :
* - When an I/O storage subsystem detects a change on an item it manages,
* action or menu, it is first supposed to do its best effort in order
* to summarize its notifications messages;
*
* 1. When an I/O storage subsystem detects a change on an action, it
* should call the na_iio_provider_item_changed() function, which
* itself will emit the "io-provider-item-changed" signal.
* - At the end of this first stage of summarization, the I/O provider
* should call the na_iio_provider_item_changed() function, which
* itself will emit the "io-provider-item-changed" signal.
* This is done so that an external I/O provider does not have to know
* anything with the signal name, but has only to take care of calling
* a function of the NAIIOProvider API.
*
* All these signals are catched by na_pivot_on_item_changed_handler()
* - The emitted signal is catched by na_pivot_on_item_changed_handler(),
* which was connected when the I/O provider plugin was associated with
* the NAIOProvider object.
*
* notify #NAPivot of this change. The user data associated with the
* message is the internal id of the #NAObjectItem-derived modified
* object.
* - The NAPivot object receives these notifications originating from all
* loaded I/O providers, itself summarizes them, and only then notify its
* consumers with only one message for a whole set of modifications.
*
* When this signal is received, #NAPivot updates accordingly the
* list of actions it maintains.
*
* It is up to the I/O storage provider to decide if it sends a
* message for each and every one detected modification, or if it
* sends only one message for a whole, maybe coherent, set of
* updates.
*
* 2. When #NAPivot has successfully updated its list of actions, it
* notifies its consumers so they update themselves.
*
* Note that #NAPivot tries to factorize notification messages, and
* to notify its consumers only once even if it has itself received
* many elementary notifications from the underlying I/O storage
* subsystems.
* It is eventually up to the consumer to connect to this signal, and
* choose itself whether to reload items or not.
*/
#include <api/na-iio-provider.h>
......@@ -120,9 +114,10 @@ GType na_pivot_get_type( void );
/* signals
*
* NAPivot acts as a 'summarizing' proxy for signals emitted by the NAIIOProvider
* providers when they detect a modification of their underlying items storage
* subsystems.
* NAPivot acts as a 'summarizing' proxy for signals emitted by the
* NAIIOProvider providers when they detect a modification in their
* underlying items storage subsystems.
*
* As several to many signals may be emitted when such a modification occurs,
* NAPivot summarizes all these signals in an only one 'items-changed' event.
*/
......
This diff is collapsed.
......@@ -43,12 +43,23 @@
* - a per-user configuration.
*
* The configuration is implemented as keyed files:
* - global configuration is sysconfdir/nautilus-actions.conf
* - global configuration is sysconfdir/xdg/nautilus-actions.conf
* - per-user configuration is HOME/.config/nautilus-actions.conf
*
* Each setting has so its own read-only attribute, whether it
* Each setting may so have its own read-only attribute, whether it
* has been read from the global configuration or from the
* per-user one.
*
* NASettings class implements two notification systems:
*
* a) a per-key system, which relies on a callback pre-registration;
* see na_settings_register_key_callback() function;
* b) a per-usage system, which relies on the usage of the changed
* key; see signal descriptions.
*
* The consumer of change notifications will choose the most accurate
* system for its needs, e.g. whether it requires to have an exact list
* of modified keys, or not.
*/
#include <glib-object.h>
......@@ -149,6 +160,20 @@ GType na_settings_get_type( void );
#define NA_IPREFS_DEFAULT_IMPORT_MODE "NoImport"
#define NA_IPREFS_DEFAULT_LIST_ORDER_MODE "AscendingOrder"
/* signals
*
* NASettings monitors, and so is able to send messages about, two sort
* of changes:
* - runtime preferences change, which group all changes which may have
* an effect on the display in file manager context menus;
* - user interface preferences change, which have only an effect on the
* NACT configuration tool
*
* These two signals are a summarization of individual changes.
*/
#define SETTINGS_SIGNAL_RUNTIME_CHANGE "settings-runtime-change"
#define SETTINGS_SIGNAL_UI_CHANGE "settings-ui-change"
typedef void ( *NASettingsKeyCallback )( const gchar *group, const gchar *key, gconstpointer new_value, gboolean mandatory, void *user_data );
NASettings *na_settings_new ( void );
......
Markdown is supported
0% or
You are about to add 0 people to the discussion. Proceed with caution.
Finish editing this message first!
Please register or to comment