ESourceSelector: Evolution Utilities Reference Manual

## ESourceSelector ESourceSelector |

## Functions

gboolean | (*ESourceSelectorForeachSourceChildFunc) ()
GtkWidget * | e_source_selector_new ()
ESourceRegistry * | e_source_selector_get_registry ()
const gchar * | e_source_selector_get_extension_name ()
gboolean | e_source_selector_get_show_colors ()
void | e_source_selector_set_show_colors ()
gboolean | e_source_selector_get_show_icons ()
void | e_source_selector_set_show_icons ()
gboolean | e_source_selector_get_show_toggles ()
void | e_source_selector_set_show_toggles ()
void | e_source_selector_select_source ()
void | e_source_selector_unselect_source ()
void | e_source_selector_select_exclusive ()
void | e_source_selector_select_all ()
gboolean | e_source_selector_source_is_selected ()
GList * | e_source_selector_get_selection ()
guint | e_source_selector_count_total ()
guint | e_source_selector_count_selected ()
void | e_source_selector_edit_primary_selection ()
ESource * | e_source_selector_ref_primary_selection ()
void | e_source_selector_set_primary_selection ()
gboolean | e_source_selector_get_source_iter ()
ESource * | e_source_selector_ref_source_by_iter ()
ESource * | e_source_selector_ref_source_by_path ()
void | e_source_selector_queue_write ()
void | e_source_selector_update_row ()
void | e_source_selector_update_all_rows ()
void | e_source_selector_set_source_tooltip ()
gchar * | e_source_selector_dup_source_tooltip ()
void | e_source_selector_set_source_is_busy ()
gboolean | e_source_selector_get_source_is_busy ()
void | e_source_selector_set_source_connection_status ()
guint | e_source_selector_get_source_connection_status ()
gboolean | e_source_selector_manage_groups ()
gboolean | e_source_selector_save_groups_setup ()
void | e_source_selector_load_groups_setup ()
void | e_source_selector_add_source_child ()
void | e_source_selector_remove_source_children ()
void | e_source_selector_foreach_source_child_remove ()
gchar * | e_source_selector_dup_selected_child_data ()

## Properties

char * | extension-name | Read / Write / Construct Only
ESource * | primary-selection | Read / Write
ESourceRegistry * | registry | Read / Write / Construct Only
gboolean | show-colors | Read / Write
gboolean | show-icons | Read / Write
gboolean | show-toggles | Read / Write

## Signals

gboolean | data-dropped | Run Last
gboolean | filter-source | Action
gboolean | popup-event | Run Last
void | primary-selection-changed | Run Last
void | selection-changed | Run Last
void | source-child-selected | Run Last
void | source-selected | Run Last
void | source-unselected | Run Last

## Types and Values

#define | E_SOURCE_SELECTOR_GROUPS_SETUP_NAME

## Object Hierarchy

        GObject
        ╰── GInitiallyUnowned
            ╰── GtkWidget
                ╰── GtkContainer
                    ╰── GtkTreeView
                        ╰── ESourceSelector
                            ├── EAlarmSelector
                            ├── EAutocompleteSelector
                            ├── EClientSelector
                            ├── EConflictSearchSelector
                            ╰── EProxyLinkSelector

## Description

## Functions

### ESourceSelectorForeachSourceChildFunc ()

    gboolean
    (*ESourceSelectorForeachSourceChildFunc)
                                   (ESourceSelector *selector,
                                    const gchar *display_name,
                                    const gchar *child_data,
                                    gpointer user_data);

Callback called for each source's child added by `e_source_selector_add_source_child()`. The callback is used by `e_source_selector_foreach_source_child_remove()`.

#### Parameters

selector | an ESourceSelector |
display_name | child's display name |
child_data | child's data |
user_data | callback user data |

#### Returns

`TRUE` to remove the child, or `FALSE` to keep it

Since: 3.48

### e_source_selector_new ()

    GtkWidget *
    e_source_selector_new (ESourceRegistry *registry,
                           const gchar *extension_name);

Displays a list of sources from `registry` having an extension named `extension_name` . The sources are grouped by backend or groupware account, which are described by the parent source.

#### Parameters

registry | an ESourceRegistry |
extension_name | the name of an ESource extension |

#### Returns

a new ESourceSelector

### e_source_selector_get_registry ()

    ESourceRegistry *
    e_source_selector_get_registry (ESourceSelector *selector);

Returns the ESourceRegistry that `selector` is getting sources from.

#### Parameters

selector | an ESourceSelector |

#### Returns

an ESourceRegistry

Since: 3.6

### e_source_selector_get_extension_name ()

    const gchar *
    e_source_selector_get_extension_name (ESourceSelector *selector);

Returns the extension name used to filter which sources are displayed.

#### Parameters

selector | an ESourceSelector |

#### Returns

the ESource extension name

Since: 3.6

### e_source_selector_get_show_colors ()

    gboolean
    e_source_selector_get_show_colors (ESourceSelector *selector);

Returns whether colors are shown next to data sources.

#### Parameters

selector | an ESourceSelector |

#### Returns

`TRUE` if colors are being shown

Since: 3.6

### e_source_selector_set_show_colors ()

    void
    e_source_selector_set_show_colors (ESourceSelector *selector,
                                       gboolean show_colors);

Sets whether to show colors next to data sources.

#### Parameters

selector | an ESourceSelector |
show_colors | whether to show colors |

Since: 3.6

### e_source_selector_get_show_icons ()

    gboolean
    e_source_selector_get_show_icons (ESourceSelector *selector);

Returns whether icons are shown next to data sources.

Generally the icon shown will be based on the presence of a backend-based extension, such as ESourceAddressBook or ESourceCalendar. For ESource instances with no such extension, no icon is shown.

#### Parameters

selector | an ESourceSelector |

#### Returns

`TRUE` if icons are being shown

Since: 3.12

### e_source_selector_set_show_icons ()

    void
    e_source_selector_set_show_icons (ESourceSelector *selector,
                                      gboolean show_icons);

Sets whether to show icons next to data sources.

Generally the icon shown will be based on the presence of a backend-based extension, such as ESourceAddressBook or ESourceCalendar. For ESource instances with no such extension, no icon is shown.

#### Parameters

selector | an ESourceSelector |
show_icons | whether to show icons |

Since: 3.12

### e_source_selector_get_show_toggles ()

    gboolean
    e_source_selector_get_show_toggles (ESourceSelector *selector);

Returns whether toggles are shown next to data sources.

#### Parameters

selector | an ESourceSelector |

#### Returns

`TRUE` if toggles are being shown

Since: 3.6

### e_source_selector_set_show_toggles ()

    void
    e_source_selector_set_show_toggles (ESourceSelector *selector,
                                        gboolean show_toggles);

Sets whether to show toggles next to data sources.

#### Parameters

selector | an ESourceSelector |
show_toggles | whether to show toggles |

Since: 3.6

### e_source_selector_select_source ()

    void
    e_source_selector_select_source (ESourceSelector *selector,
                                     ESource *source);

Select `source` in `selector` .

#### Parameters

selector | An ESourceSelector widget |
source | An ESource. |

### e_source_selector_unselect_source ()

    void
    e_source_selector_unselect_source (ESourceSelector *selector,
                                       ESource *source);

Unselect `source` in `selector` .

#### Parameters

selector | An ESourceSelector widget |
source | An ESource. |

### e_source_selector_select_exclusive ()

    void
    e_source_selector_select_exclusive (ESourceSelector *selector,
                                        ESource *source);

Select `source` in `selector` and unselect all others.

#### Parameters

selector | An ESourceSelector widget |
source | An ESource. |

Since: 2.30

### e_source_selector_select_all ()

    void
    e_source_selector_select_all (ESourceSelector *selector);

Selects all ESource-s in the `selector` .

#### Parameters

selector | An ESourceSelector widget |

Since: 3.20

### e_source_selector_source_is_selected ()

    gboolean
    e_source_selector_source_is_selected (ESourceSelector *selector,
                                          ESource *source);

Check whether `source` is selected in `selector` .

#### Parameters

selector | An ESourceSelector widget |
source | An ESource. |

#### Returns

`TRUE` if `source` is currently selected, `FALSE` otherwise.

### e_source_selector_get_selection ()

    GList *
    e_source_selector_get_selection (ESourceSelector *selector);

Returns a list of selected sources, i.e. those that were enabled through the corresponding checkboxes in the tree. The sources are ordered as they appear in `selector` .

The sources returned in the list are referenced for thread-safety. They must each be unreferenced with `g_object_unref()` when finished with them. Free the returned list itself with `g_list_free()`.

An easy way to free the list properly in one step is as follows:

    1
    g_list_free_full (list, g_object_unref);

#### Parameters

selector | an ESourceSelector |

#### Returns

a ordered list of selected sources

### e_source_selector_count_total ()

    guint
    e_source_selector_count_total (ESourceSelector *selector);

Counts how many ESource-s are shown in the `selector` .

#### Parameters

selector | an ESourceSelector |

#### Returns

How many ESource-s are shown in the `selector` .

Since: 3.20

### e_source_selector_count_selected ()

    guint
    e_source_selector_count_selected (ESourceSelector *selector);

Counts how many ESource-s are selected in the `selector` .

#### Parameters

selector | an ESourceSelector |

#### Returns

How many ESource-s are selected in the `selector` .

Since: 3.20

### e_source_selector_edit_primary_selection ()

    void
    e_source_selector_edit_primary_selection
                                   (ESourceSelector *selector);

Allows the user to rename the primary selected source by opening an entry box directly in `selector` .

#### Parameters

selector | An ESourceSelector widget |

Since: 2.26

### e_source_selector_ref_primary_selection ()

    ESource *
    e_source_selector_ref_primary_selection
                                   (ESourceSelector *selector);

Get the primary selected source. The primary selection is the one that is highlighted through the normal GtkTreeView selection mechanism (as opposed to the "normal" selection, which is the set of source whose checkboxes are checked).

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

#### Parameters

selector | An ESourceSelector widget |

#### Returns

The selected source.

Since: 3.6

### e_source_selector_set_primary_selection ()

    void
    e_source_selector_set_primary_selection
                                   (ESourceSelector *selector,
                                    ESource *source);

Highlights `source` in `selector` . The highlighted ESource is called the primary selection.

Do not confuse this function with `e_source_selector_select_source()`, which activates the check box next to an ESource's display name in `selector` . This function does not alter the check box.

#### Parameters

selector | an ESourceSelector widget |
source | an ESource to select |

### e_source_selector_get_source_iter ()

    gboolean
    e_source_selector_get_source_iter (ESourceSelector *selector,
                                       ESource *source,
                                       GtkTreeIter *iter,
                                       GtkTreeModel **out_model);

Gets an iterator for the `source` , optionally also the model.

#### Parameters

selector | an ESourceSelector |
source | an ESource |
iter | a GtkTreeIter to store the iterator to. | [out]
out_model | a GtkTreeModel to set to, or `NULL` when not needed. | [out][optional][transfer none]

#### Returns

whether the `source` was found

Since: 3.48

### e_source_selector_ref_source_by_iter ()

    ESource *
    e_source_selector_ref_source_by_iter (ESourceSelector *selector,
                                          GtkTreeIter *iter);

Returns the ESource object at `iter` .

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

#### Parameters

selector | an ESourceSelector |
iter | a GtkTreeIter |

#### Returns

the ESource object at `iter` , or `NULL`

Since: 3.8

### e_source_selector_ref_source_by_path ()

    ESource *
    e_source_selector_ref_source_by_path (ESourceSelector *selector,
                                          GtkTreePath *path);

Returns the ESource object at `path` , or `NULL` if `path` is invalid.

The returned ESource is referenced for thread-safety and must be unreferenced with `g_object_unref()` when finished with it.

#### Parameters

selector | an ESourceSelector |
path | a GtkTreePath |

#### Returns

the ESource object at `path` , or `NULL`

Since: 3.6

### e_source_selector_queue_write ()

    void
    e_source_selector_queue_write (ESourceSelector *selector,
                                   ESource *source);

Queues a main loop idle callback to write changes to `source` back to the D-Bus registry service.

#### Parameters

selector | an ESourceSelector |
source | an ESource with changes to be written |

Since: 3.6

### e_source_selector_update_row ()

    void
    e_source_selector_update_row (ESourceSelector *selector,
                                  ESource *source);

Updates the corresponding GtkTreeModel row for `source` .

This function is public so it can be called from subclasses like EClientSelector.

#### Parameters

selector | an ESourceSelector |
source | an ESource |

Since: 3.8

### e_source_selector_update_all_rows ()

    void
    e_source_selector_update_all_rows (ESourceSelector *selector);

Calls `e_source_selector_update_row()` for each ESource being shown by `selector` , according to the “extension_name” property.

#### Parameters

selector | an ESourceSelector |

Since: 3.10

### e_source_selector_set_source_tooltip ()

    void
    e_source_selector_set_source_tooltip (ESourceSelector *selector,
                                          ESource *source,
                                          const gchar *tooltip);

Updates tooltip for the given `source` .

#### Parameters

selector | an ESourceSelector |
source | an ESource for which to set the tooltip |

Since: 3.16

### e_source_selector_dup_source_tooltip ()

    gchar *
    e_source_selector_dup_source_tooltip (ESourceSelector *selector,
                                          ESource *source);

#### Parameters

selector | an ESourceSelector |
source | an ESource for which to read the tooltip |

#### Returns

Current tooltip for the given `source` . Free the returned string with `g_free()` when done with it.

Since: 3.16

### e_source_selector_set_source_is_busy ()

    void
    e_source_selector_set_source_is_busy (ESourceSelector *selector,
                                          ESource *source,
                                          gboolean is_busy);

Updates the is-busy flag status for the given `source` .

#### Parameters

selector | an ESourceSelector |
source | an ESource for which to set the is-busy status |

Since: 3.16

### e_source_selector_get_source_is_busy ()

    gboolean
    e_source_selector_get_source_is_busy (ESourceSelector *selector,
                                          ESource *source);

#### Parameters

selector | an ESourceSelector |
source | an ESource for which to read the is-busy status |

#### Returns

Current is-busy flag status for the given `source` .

Since: 3.16

### e_source_selector_set_source_connection_status ()

    void
    e_source_selector_set_source_connection_status
                                   (ESourceSelector *selector,
                                    ESource *source,
                                    guint value);

Sets connection status for the `source` . It's not interpreted by the `selector` , it only saves it into the model. Read it back with `e_source_selector_get_source_connection_status()`.

#### Parameters

selector | an ESourceSelector |
source | an ESource for which to set the connection status |
value | the value to set |

Since: 3.40

### e_source_selector_get_source_connection_status ()

    guint
    e_source_selector_get_source_connection_status
                                   (ESourceSelector *selector,
                                    ESource *source);

Gets connection status for the `source` . It's not interpreted by the `selector` , it only returns what had been saved into the model with `e_source_selector_set_source_connection_status()`.

#### Parameters

selector | an ESourceSelector |
source | an ESource for which to get the stored connection status |

#### Returns

Value previously stored with `e_source_selector_set_source_connection_status()`, or 0 when not set or when the `source` was not found.

Since: 3.40

### e_source_selector_manage_groups ()

    gboolean
    e_source_selector_manage_groups (ESourceSelector *selector);

Manages list of groups, like their order in the source selector, and a hidden property of the group.

#### Parameters

selector | an ESourceSelector |

#### Returns

Whether user confirmed changes in the dialog.

Since: 3.20

### e_source_selector_save_groups_setup ()

    gboolean
    e_source_selector_save_groups_setup (ESourceSelector *selector,
                                         GKeyFile *key_file);

Stores current setup of the groups in the `key_file` .

Use `e_source_selector_load_groups_setup()` to pass the settings back to the `selector` .

#### Parameters

selector | an ESourceSelector |
key_file | a GKeyFile to store the sgroups setup to |

#### Returns

Whether the saved values are different, aka whether it's required to store the changes.

Since: 3.20

### e_source_selector_load_groups_setup ()

    void
    e_source_selector_load_groups_setup (ESourceSelector *selector,
                                         GKeyFile *key_file);

Loads setup of the groups from the `key_file` .

Use `e_source_selector_save_groups_setup()` to store the settings of the `selector` .

#### Parameters

selector | an ESourceSelector |
key_file | a GKeyFile to load the groups setup from |

Since: 3.20

### e_source_selector_add_source_child ()

    void
    e_source_selector_add_source_child (ESourceSelector *selector,
                                        ESource *source,
                                        const gchar *display_name,
                                        const gchar *child_data);

Adds a child node under the `source` node, identified by `child_data` in functions `e_source_selector_remove_source_child()` and `e_source_selector_foreach_source_child()`, the same as in the signal callbacks. It's the caller's responsibility to choose a unique `child_data` .

Listen to “after-rebuild” signal to re-add the child data after the content is rebuilt.

#### Parameters

selector | an ESourceSelector |
source | a parent ESource |
display_name | user-visible text for the child |
child_data | custom child data |

Since: 3.48

### e_source_selector_remove_source_children ()

    void
    e_source_selector_remove_source_children
                                   (ESourceSelector *selector,
                                    ESource *source);

Removes all children of the `source` , previously added by `e_source_selector_add_source_child()`. It does not remove real ESource references.

#### Parameters

selector | an ESourceSelector |
source | an ESource |

Since: 3.48

### e_source_selector_foreach_source_child_remove ()

    void
    e_source_selector_foreach_source_child_remove
                                   (ESourceSelector *selector,
                                    ESource *source,
                                    ESourceSelectorForeachSourceChildFunc func,
                                    gpointer user_data);

Traverses all `source` children previously added by `e_source_selector_add_source_child()` and removes those, for which the `func` returns `TRUE`.

#### Parameters

selector | an ESourceSelector |
source | a parent ESource |
func | function to call for each child. | [scope call]
user_data | user data passed to the `func` |

Since: 3.48

### e_source_selector_dup_selected_child_data ()

    gchar *
    e_source_selector_dup_selected_child_data
                                   (ESourceSelector *selector);

Returns child data for the selected source child, as set by `e_source_selector_add_source_child()`.

Free the returned string with `g_free()`, when no longer needed.

#### Parameters

selector | an ESourceSelector |

#### Returns

source child data of the selected node, or `NULL`, when none set.

[transfer full][nullable]

Since: 3.48

## Types and Values

### E_SOURCE_SELECTOR_GROUPS_SETUP_NAME

    #define E_SOURCE_SELECTOR_GROUPS_SETUP_NAME "SourceSelector"

## Property Details

### The `“extension-name”` property

      “extension-name”           char *

Owner: ESourceSelector

Flags: Read / Write / Construct Only

Default value: NULL

### The `“primary-selection”` property

      “primary-selection”        ESource *

Owner: ESourceSelector

Flags: Read / Write

### The `“registry”` property

      “registry”                 ESourceRegistry *

Owner: ESourceSelector

Flags: Read / Write / Construct Only

### The `“show-colors”` property

      “show-colors”              gboolean

Owner: ESourceSelector

Flags: Read / Write

Default value: TRUE

### The `“show-icons”` property

      “show-icons”               gboolean

Owner: ESourceSelector

Flags: Read / Write

Default value: TRUE

### The `“show-toggles”` property

      “show-toggles”             gboolean

Owner: ESourceSelector

Flags: Read / Write

Default value: TRUE

## Signal Details

### The `“data-dropped”` signal

    gboolean
    user_function (ESourceSelector  *esourceselector,
                   GtkSelectionData *arg1,
                   ESource          *arg2,
                   GdkDragAction     arg3,
                   guint             arg4,
                   gpointer          user_data)

Flags: Run Last

### The `“filter-source”` signal

    gboolean
    user_function (ESourceSelector *esourceselector,
                   ESource         *arg1,
                   gpointer         user_data)

Flags: Action

### The `“popup-event”` signal

    gboolean
    user_function (ESourceSelector *esourceselector,
                   GObject         *arg1,
                   GdkEvent        *arg2,
                   gpointer         user_data)

Flags: Run Last

### The `“primary-selection-changed”` signal

    void
    user_function (ESourceSelector *esourceselector,
                   gpointer         user_data)

Flags: Run Last

### The `“selection-changed”` signal

    void
    user_function (ESourceSelector *esourceselector,
                   gpointer         user_data)

Flags: Run Last

### The `“source-child-selected”` signal

    void
    user_function (ESourceSelector *esourceselector,
                   ESource         *arg1,
                   char            *arg2,
                   gpointer         user_data)

Flags: Run Last

### The `“source-selected”` signal

    void
    user_function (ESourceSelector *esourceselector,
                   ESource         *arg1,
                   gpointer         user_data)

Flags: Run Last

### The `“source-unselected”` signal

    void
    user_function (ESourceSelector *esourceselector,
                   ESource         *arg1,
                   gpointer         user_data)

Flags: Run Last