Add e_source_registry_check_enabled().

Checks the enabled state of a given #ESource and of its ancestors to
determine if the #ESource should be displayed or acted on.

This is somewhat similar to widget sensitivity in GTK+.
cf. gtk_widget_get_sensitive() versus gtk_widget_is_sensitive()

diff --git a/docs/reference/libedataserver/libedataserver-sections.txt b/docs/reference/libedataserver/libedataserver-sections.txt
index 52b9b57..fd2df4c 100644 (file)
--- a/docs/reference/libedataserver/libedataserver-sections.txt
+++ b/docs/reference/libedataserver/libedataserver-sections.txt
@@ -823,6 +823,7 @@ e_source_registry_create_sources_finish
 e_source_registry_ref_source
 e_source_registry_list_sources
 e_source_registry_find_extension
+e_source_registry_check_enabled
 e_source_registry_build_display_tree
 e_source_registry_free_display_tree
 e_source_registry_debug_dump

diff --git a/libedataserver/e-source-registry.c b/libedataserver/e-source-registry.c
index 3933712..d37a84f 100644 (file)
--- a/libedataserver/e-source-registry.c
+++ b/libedataserver/e-source-registry.c
@@ -2236,6 +2236,58 @@ e_source_registry_list_sources (ESourceRegistry *registry,
 }
 
 /**
+ * e_source_registry_check_enabled:
+ * @registry: an #ESourceRegistry
+ * @source: an #ESource
+ *
+ * Determines whether @source is "effectively" enabled by examining its
+ * own #ESource:enabled property as well as those of its ancestors in the
+ * #ESource hierarchy.  If all examined #ESource:enabled properties are
+ * %TRUE, then the function returns %TRUE.  If any are %FALSE, then the
+ * function returns %FALSE.
+ *
+ * Use this function instead of e_source_get_enabled() to determine
+ * things like whether to display an #ESource in a user interface or
+ * whether to act on the data set described by the #ESource.
+ *
+ * Returns: whether @source is "effectively" enabled
+ *
+ * Since: 3.8
+ **/
+gboolean
+e_source_registry_check_enabled (ESourceRegistry *registry,
+                                 ESource *source)
+{
+       gboolean enabled;
+       gchar *parent_uid;
+
+       g_return_val_if_fail (E_IS_SOURCE_REGISTRY (registry), FALSE);
+       g_return_val_if_fail (E_IS_SOURCE (source), FALSE);
+
+       enabled = e_source_get_enabled (source);
+       parent_uid = e_source_dup_parent (source);
+
+       while (enabled && parent_uid != NULL) {
+               ESource *parent;
+
+               parent = e_source_registry_ref_source (registry, parent_uid);
+
+               g_free (parent_uid);
+               parent_uid = NULL;
+
+               if (parent != NULL) {
+                       enabled = e_source_get_enabled (parent);
+                       parent_uid = e_source_dup_parent (parent);
+                       g_object_unref (parent);
+               }
+       }
+
+       g_free (parent_uid);
+
+       return enabled;
+}
+
+/**
  * e_source_registry_find_extension:
  * @registry: an #ESourceRegistry
  * @source: an #ESource

diff --git a/libedataserver/e-source-registry.h b/libedataserver/e-source-registry.h
index 8ee290f..5a2a6fe 100644 (file)
--- a/libedataserver/e-source-registry.h
+++ b/libedataserver/e-source-registry.h
@@ -143,6 +143,8 @@ ESource *   e_source_registry_find_extension
                                                (ESourceRegistry *registry,
                                                 ESource *source,
                                                 const gchar *extension_name);
+gboolean       e_source_registry_check_enabled (ESourceRegistry *registry,
+                                                ESource *source);
 GNode *                e_source_registry_build_display_tree
                                                (ESourceRegistry *registry,
                                                 const gchar *extension_name);

diff --git a/libedataserver/e-source.c b/libedataserver/e-source.c
index 29318cd..1c27c18 100644 (file)
--- a/libedataserver/e-source.c
+++ b/libedataserver/e-source.c
@@ -1879,6 +1879,14 @@ e_source_set_parent (ESource *source,
  * even if it does not provide a way to change the setting through its
  * user interface.  Disabled data sources should generally be hidden.
  *
+ * <note><para>
+ *   This function does not take into account @source's ancestors in the
+ *   #ESource hierarchy, each of which have their own enabled state.  If
+ *   any of @source's ancestors are disabled, then @source itself should
+ *   be treated as disabled.  Use e_source_registry_check_enabled() to
+ *   easily check for this.
+ * </para></note>
+ *
  * Returns: whether @source is enabled
  *
  * Since: 3.6