e-ui-manager: Evolution Utilities Reference Manual

## e-ui-manager e-ui-manager — a UI manager |

## Functions

EUIManager * | e_ui_manager_new ()
EUIParser * | e_ui_manager_get_parser ()
EUICustomizer * | e_ui_manager_get_customizer ()
GtkAccelGroup * | e_ui_manager_get_accel_group ()
void | e_ui_manager_freeze ()
void | e_ui_manager_thaw ()
gboolean | e_ui_manager_is_frozen ()
void | e_ui_manager_changed ()
gboolean | e_ui_manager_get_in_accel_activation ()
void | e_ui_manager_add_actions ()
void | e_ui_manager_add_actions_enum ()
void | e_ui_manager_add_action ()
void | e_ui_manager_add_actions_with_eui_data ()
void | e_ui_manager_add_action_groups_to_widget ()
void | e_ui_manager_set_action_groups_widget ()
GtkWidget * | e_ui_manager_ref_action_groups_widget ()
gboolean | e_ui_manager_has_action_group ()
EUIActionGroup * | e_ui_manager_get_action_group ()
void | e_ui_manager_add_action_group ()
GPtrArray * | e_ui_manager_list_action_groups ()
EUIAction * | e_ui_manager_get_action ()
GIcon * | e_ui_manager_get_gicon ()
GObject * | e_ui_manager_create_item ()
void | e_ui_manager_fill_menu ()
void | e_ui_manager_update_item_from_action ()
GObject * | e_ui_manager_create_item_from_menu_model ()
void | e_ui_manager_set_actions_usable_for_kinds ()
void | e_ui_manager_set_entries_usable_for_kinds ()
void | e_ui_manager_set_enum_entries_usable_for_kinds ()
guint | e_ui_manager_shortcut_def_hash ()
gboolean | e_ui_manager_shortcut_def_equal ()

## Properties

char * | customizer-filename | Read / Write / Construct Only

## Signals

void | changed | Action
gboolean | create-gicon | Action
gboolean | create-item | Action
void | freeze | Action
gboolean | ignore-accel | Action
void | thaw | Action

## Types and Values

#define | E_TYPE_UI_MANAGER
| EUIManagerShortcutDef
| EUIManager

## Object Hierarchy

        GObject
        ╰── EUIManager

## Includes

    #include <e-util/e-util.h>

## Description

The EUIManager is a central point of managing headerbars, toolbars, menubars and context menus in the application. The EUIParser is used to read the .eui definition from an XML file or data. Each item in the definition corresponds to an EUIAction, which should be added with the `e_ui_manager_add_actions()` or `e_ui_manager_add_actions_enum()` before the corresponding items are created with the `e_ui_manager_create_item()`.

The `e_ui_manager_set_action_groups_widget()` is used to assign a widget to which the action groups should be inserted (for example a GtkWindow, but can be other as well).

The GtkAccelGroup returned from the `e_ui_manager_get_accel_group()` needs to be added to the GtkWindow with `gtk_window_add_accel_group()`.

The object is not thread-safe, it's meant to be used only from the main/GUI thread.

## Functions

### e_ui_manager_new ()

    EUIManager *
    e_ui_manager_new (gchar *customizer_filename);

Creates a new EUIManager. Use `g_object_unref()` to free it, when no longer needed.

The `customizer_filename` , if not `NULL`, is a full path to a file where UI customization are stored. If not set, the UI manager will not allow the customizations. The function assumes ownership of the string.

#### Parameters

customizer_filename | an optional EUICustomizer filename, or `NULL`. | [nullable][transfer full]

#### Returns

a new EUIManager.

[transfer full]

Since: 3.56

### e_ui_manager_get_parser ()

    EUIParser *
    e_ui_manager_get_parser (EUIManager *self);

Gets an EUIParser associated with the `self` . Any UI definitions are loaded into it and the layouts are read from it.

#### Parameters

self | an EUIManager |

#### Returns

an EUIParser.

[transfer none]

Since: 3.56

### e_ui_manager_get_customizer ()

    EUICustomizer *
    e_ui_manager_get_customizer (EUIManager *self);

Gets an EUICustomizer for the `self` .

#### Parameters

self | an EUIManager |

#### Returns

an EUICustomizer, or `NULL`, when customizations are disabled.

[transfer none][nullable]

Since: 3.56

### e_ui_manager_get_accel_group ()

    GtkAccelGroup *
    e_ui_manager_get_accel_group (EUIManager *self);

Gets a GtkAccelGroup associated with the `self` . Actions with configured accelerators register themselves to this accel group.

It should be added to a GtkWindow with `gtk_window_add_accel_group()`.

#### Parameters

self | an EUIManager |

#### Returns

a GtkAccelGroup.

[transfer none]

Since: 3.56

### e_ui_manager_freeze ()

    void
    e_ui_manager_freeze (EUIManager *self);

Freezes change notifications on the `self` . The function can be called multiple times, only each call should be followed by a corresponding `e_ui_manager_thaw()`.

#### Parameters

self | an EUIManager |

Since: 3.56

### e_ui_manager_thaw ()

    void
    e_ui_manager_thaw (EUIManager *self);

Reverts effect of one `e_ui_manager_freeze()` call. It's a programming error to call this function when the `self` is not frozen.

#### Parameters

self | an EUIManager |

Since: 3.56

### e_ui_manager_is_frozen ()

    gboolean
    e_ui_manager_is_frozen (EUIManager *self);

Check whether the change notifications are frozen with `e_ui_manager_freeze()` call.

#### Parameters

self | an EUIManager |

#### Returns

whether change notifications are frozen

Since: 3.56

### e_ui_manager_changed ()

    void
    e_ui_manager_changed (EUIManager *self);

Let the `self` know that something changed, indicating the UI parts should be regenerated. In case the `self` is frozen, the regeneration is done once it's unfrozen.

#### Parameters

self | an EUIManager |

Since: 3.56

### e_ui_manager_get_in_accel_activation ()

    gboolean
    e_ui_manager_get_in_accel_activation (EUIManager *self);

Gets whether the `self` is currently in an accelerator activation process, thus whether an action is activated due to a key press.

#### Parameters

self | an EUIManager |

#### Returns

`TRUE` when processing accelerator, `FALSE` otherwise

Since: 3.58

### e_ui_manager_add_actions ()

    void
    e_ui_manager_add_actions (EUIManager *self,
                              const gchar *group_name,
                              const gchar *translation_domain,
                              const EUIActionEntry *entries,
                              gint n_entries,
                              gpointer user_data);

Just like `g_action_map_add_action_entries()`, only uses EUIAction instead of GSimpleAction actions and adds the actions into a named action group. When there is no action group of the `group_name` , a new is added.

The `translation_domain` can be NULL, in which case the Evolution's translation domain is used. It's used also when the `translation_domain` is an empty string.

#### Parameters

self | an EUIManager |
group_name | a name of an action group to add the actions to. | [not nullable]
translation_domain | translation domain for the `entries` ' localized members, or `NULL`. | [nullable]
entries | action entries to be added, as EUIActionEntry array |
n_entries | how many items `entries` has, or -1 when NULL-terminated |
user_data | user data to pass to action callbacks |

Since: 3.56

### e_ui_manager_add_actions_enum ()

    void
    e_ui_manager_add_actions_enum (EUIManager *self,
                                   const gchar *group_name,
                                   const gchar *translation_domain,
                                   const EUIActionEnumEntry *entries,
                                   gint n_entries,
                                   gpointer user_data);

The same as `e_ui_manager_add_actions()`, only creates radio actions, whose states correspond to certain enum value. If bindings between the action's state and a corresponding enum GObject property is needed, a utility function `e_ui_action_util_gvalue_to_enum_state()` and `e_ui_action_util_enum_state_to_gvalue()` can be used to transform the value from the GObject to an action state or vice versa.

The `translation_domain` can be `NULL`, in which case the Evolution's translation domain is used. It's used also when the `translation_domain` is an empty string.

#### Parameters

self | an EUIManager |
group_name | a name of an action group to add the actions to. | [not nullable]
translation_domain | translation domain for the `entries` ' localized members, or `NULL`. | [nullable]
entries | action entries to be added, as EUIActionEnumEntry array |
n_entries | how many items `entries` has, or -1 when NULL-terminated |
user_data | user data to pass to action callbacks |

Since: 3.56

### e_ui_manager_add_action ()

    void
    e_ui_manager_add_action (EUIManager *self,
                             const gchar *group_name,
                             EUIAction *action,
                             EUIActionFunc activate,
                             EUIActionFunc change_state,
                             gpointer user_data);

Adds a single `action` to the `group_name` . The actions group cannot contain an action of the same name.

#### Parameters

self | an EUIManager |
group_name | a name of an action group to add the action to. | [not nullable]
action | the action to add. | [transfer none]
activate | an optional callback to call on "activate" signal, or `NULL`. | [nullable]
change_state | an optional callback to call on "change-state" signal, or `NULL`. | [nullable]
user_data | user data to pass to action callbacks |

Since: 3.56

### e_ui_manager_add_actions_with_eui_data ()

    void
    e_ui_manager_add_actions_with_eui_data
                                   (EUIManager *self,
                                    const gchar *group_name,
                                    const gchar *translation_domain,
                                    const EUIActionEntry *entries,
                                    gint n_entries,
                                    gpointer user_data,
                                    const gchar *eui);

Combines `e_ui_manager_add_actions()` with `e_ui_parser_merge_data()`, in this order, printing any errors in the `eui` into the terminal. This can be used to add built-in UI definition with the related actions in a single call.

#### Parameters

self | an EUIManager |
group_name | a name of an action group to add the actions to. | [not nullable]
translation_domain | translation domain for the `entries` ' localized members, or `NULL`. | [nullable]
entries | action entries to be added, as EUIActionEntry array |
n_entries | how many items `entries` has, or -1 when NULL-terminated |
user_data | user data to pass to action callbacks |
eui | Evolution UI definition |

Since: 3.56

### e_ui_manager_add_action_groups_to_widget ()

    void
    e_ui_manager_add_action_groups_to_widget
                                   (EUIManager *self,
                                    GtkWidget *widget);

Adds all currently known action groups into the `widget` with `gtk_widget_insert_action_group()`. In contrast to `e_ui_manager_set_action_groups_widget()`, this does not add any later added action groups into the `widget` . In other words, this is a one-time operation only.

#### Parameters

self | an EUIManager |
widget | a GtkWidget |

Since: 3.56

### e_ui_manager_set_action_groups_widget ()

    void
    e_ui_manager_set_action_groups_widget (EUIManager *self,
                                           GtkWidget *widget);

Sets the `widget` to be the one where all action groups will be inserted. When the `self` creates a new action group, it is automatically added into the `widget` .

When the `widget` is `NULL`, any previous widget is unset.

Overwriting any existing `widget` will remove the groups from the previous widget first.

#### Parameters

self | an EUIManager |
widget | a GtkWidget, or `NULL`. | [nullable]

Since: 3.56

### e_ui_manager_ref_action_groups_widget ()

    GtkWidget *
    e_ui_manager_ref_action_groups_widget (EUIManager *self);

References a GtkWidget, which is used to add action groups to.

The returned widget, if not `NULL`, should be dereferenced with `g_object_unref()`, when no longer needed.

#### Parameters

self | an EUIManager |

#### Returns

a referenced GtkWidget used to add action groups to, or `NULL`, when none is set.

[transfer full][nullable]

Since: 3.56

### e_ui_manager_has_action_group ()

    gboolean
    e_ui_manager_has_action_group (EUIManager *self,
                                   const gchar *name);

Check whether an action group named `name` already exists in `self` .

#### Parameters

self | an EUIManager |
name | an action group name |

#### Returns

`TRUE`, when the action group exists, `FALSE` otherwise

Since: 3.56

### e_ui_manager_get_action_group ()

    EUIActionGroup *
    e_ui_manager_get_action_group (EUIManager *self,
                                   const gchar *name);

Gets an EUIActionGroup named `name` . If no such exists, a new is created. Use `e_ui_manager_has_action_group()` to check whether an action group exists.

#### Parameters

self | an EUIManager |
name | an action group name |

#### Returns

an EUIActionGroup named `name` .

[transfer none]

Since: 3.56

### e_ui_manager_add_action_group ()

    void
    e_ui_manager_add_action_group (EUIManager *self,
                                   EUIActionGroup *action_group);

Adds an existing action group to the `self` , being able to call actions from it. The function does nothing when the `action_group` is already part of the `self` , nonetheless it's considered a programming error to try to add a different group of the same name into the `self` .

#### Parameters

self | an EUIManager |
action_group | an EUIActionGroup to add. | [transfer none]

Since: 3.56

### e_ui_manager_list_action_groups ()

    GPtrArray *
    e_ui_manager_list_action_groups (EUIManager *self);

Lists all action groups added into the `self` .

#### Parameters

self | an EUIManager |

#### Returns

a GPtrArray of an EUIActionGroup groups.

[transfer container][element-type EUIActionGroup]

Since: 3.56

### e_ui_manager_get_action ()

    EUIAction *
    e_ui_manager_get_action (EUIManager *self,
                             const gchar *name);

Looks up an EUIAction by its `name` among all known action maps and returns it.

#### Parameters

self | an EUIManager |
name | an action name |

#### Returns

an EUIAction named `name` , or `NULL`, if not found.

[nullable][transfer none]

Since: 3.56

### e_ui_manager_get_gicon ()

    GIcon *
    e_ui_manager_get_gicon (EUIManager *self,
                            const gchar *name);

Retrieves a named GIcon. These are cached. The signal "create-gicon" is used to create icons prefixed with "gicon::" in the .eui definitions, as they are custom icons. The `name` is without this prefix.

While returning `NULL` is possible, it's considered an error and a runtime warning is printed on the terminal, thus there should always be a "create-gicon" signal handler providing the GIcon.

#### Parameters

self | an EUIManager |
name | a GIcon name to retrieve |

#### Returns

a GIcon named `name` , or `NULL`, if not found.

[transfer none][nullable]

Since: 3.56

### e_ui_manager_create_item ()

    GObject *
    e_ui_manager_create_item (EUIManager *self,
                              const gchar *id);

Creates a new item corresponding to the identifier `id` . This is supposed to be part of the `self` 's EUIParser on the toplevel, thus either a menu, a headerbar or a toolbar. It's an error to ask for an item which does not exist.

The returned GObject is an EUIMenu (a GMenuModel descendant) for the menu, an EHeaderBar for the headerbar and a GtkToolbar for the toolbar.

#### Parameters

self | an EUIManager |
id | an identifier of the toplevel item |

#### Returns

a new GObject for the `id` .

[transfer full]

Since: 3.56

### e_ui_manager_fill_menu ()

    void
    e_ui_manager_fill_menu (EUIManager *self,
                            const gchar *id,
                            struct _EUIMenu *ui_menu);

Fills the `ui_menu` with the menu definition with ID `id` . This is meant to be used by EUIMenu itself during its rebuild.

#### Parameters

self | an EUIManager |
id | a menu ID to fill the `ui_menu` with |
ui_menu | an EUIMenu to be filled |

Since: 3.56

### e_ui_manager_update_item_from_action ()

    void
    e_ui_manager_update_item_from_action (EUIManager *self,
                                          gpointer item,
                                          EUIAction *action);

Updates properties of the `item` with the values from the `action` . The function can handle only GMenuItem, GtkToolButton, GtkButton and EHeaderBarButton descendants.

Passing other than supported types into the function is considered a programming error.

#### Parameters

self | an EUIManager |
item | an item object, its type varies based on the place of use |
action | an EUIAction to update the `item` with |

Since: 3.56

### e_ui_manager_create_item_from_menu_model ()

    GObject *
    e_ui_manager_create_item_from_menu_model
                                   (EUIManager *self,
                                    EUIElement *elem,
                                    EUIAction *action,
                                    EUIElementKind for_kind,
                                    GMenuModel *menu_model);

Creates a new UI item suitable for the `for_kind` , containing the `menu_model` . For `E_UI_ELEMENT_KIND_MENU` returns a submenu GMenuItem; for `E_UI_ELEMENT_KIND_TOOLBAR` returns a GtkMenuToolButton and for `E_UI_ELEMENT_KIND_HEADERBAR` returns an EHeaderBarButton.

This might be usually called from EUIManager 's "create-item" callback.

#### Parameters

self | an EUIManager |
elem | corresponding EUIElement, or `NULL`. | [nullable]
action | an EUIAction |
for_kind | for which part of the UI the item should be created; it influences the type of the returned item |
menu_model | a GMenuModel to use for the created item. | [transfer none]

#### Returns

a new UI item.

[transfer full]

Since: 3.56

### e_ui_manager_set_actions_usable_for_kinds ()

    void
    e_ui_manager_set_actions_usable_for_kinds
                                   (EUIManager *self,
                                    guint32 kinds,
                                    const gchar *first_action_name,
                                    ...);

Sets "usable-for-kinds" `kinds` to one or more actions identified by their name.

The `kinds` can contain only `E_UI_ELEMENT_KIND_HEADERBAR`, `E_UI_ELEMENT_KIND_TOOLBAR` and `E_UI_ELEMENT_KIND_MENU`.

See `e_ui_manager_set_entries_usable_for_kinds()`, `e_ui_manager_set_enum_entries_usable_for_kinds()`

#### Parameters

self | an EUIManager |
kinds | a bit-or of EUIElementKind to set |
first_action_name | name of the first action |
... | NULL-terminated list of additional action names. | [null-terminated]

Since: 3.56

### e_ui_manager_set_entries_usable_for_kinds ()

    void
    e_ui_manager_set_entries_usable_for_kinds
                                   (EUIManager *self,
                                    guint32 kinds,
                                    const EUIActionEntry *entries,
                                    gint n_entries);

Sets "usable-for-kinds" `kinds` to all of the actions in the `entries` .

The `kinds` can contain only `E_UI_ELEMENT_KIND_HEADERBAR`, `E_UI_ELEMENT_KIND_TOOLBAR` and `E_UI_ELEMENT_KIND_MENU`.

See `e_ui_manager_set_enum_entries_usable_for_kinds()`, `e_ui_manager_set_actions_usable_for_kinds()`

#### Parameters

self | an EUIManager |
kinds | a bit-or of EUIElementKind to set |
entries | action entries to be added, as EUIActionEntry array |
n_entries | how many items `entries` has, or -1 when NULL-terminated |

Since: 3.56

### e_ui_manager_set_enum_entries_usable_for_kinds ()

    void
    e_ui_manager_set_enum_entries_usable_for_kinds
                                   (EUIManager *self,
                                    guint32 kinds,
                                    const EUIActionEnumEntry *entries,
                                    gint n_entries);

Sets "usable-for-kinds" `kinds` to all of the actions in the `entries` .

The `kinds` can contain only `E_UI_ELEMENT_KIND_HEADERBAR`, `E_UI_ELEMENT_KIND_TOOLBAR` and `E_UI_ELEMENT_KIND_MENU`.

See `e_ui_manager_set_entries_usable_for_kinds()`, `e_ui_manager_set_actions_usable_for_kinds()`

#### Parameters

self | an EUIManager |
kinds | a bit-or of EUIElementKind to set |
entries | action entries to be added, as EUIActionEnumEntry array |
n_entries | how many items `entries` has, or -1 when NULL-terminated |

Since: 3.56

### e_ui_manager_shortcut_def_hash ()

    guint
    e_ui_manager_shortcut_def_hash (gconstpointer ptr);

Returns a hash value of the EUIManagerShortcutDef.

#### Parameters

ptr | an EUIManagerShortcutDef |

#### Returns

a hash value of the EUIManagerShortcutDef

Since: 3.56

### e_ui_manager_shortcut_def_equal ()

    gboolean
    e_ui_manager_shortcut_def_equal (gconstpointer ptr1,
                                     gconstpointer ptr2);

Returns whether the two EUIManagerShortcutDef equal.

#### Parameters

ptr1 | an EUIManagerShortcutDef |
ptr2 | an EUIManagerShortcutDef |

#### Returns

whether the two EUIManagerShortcutDef equal

Since: 3.56

## Types and Values

### E_TYPE_UI_MANAGER

    #define E_TYPE_UI_MANAGER e_ui_manager_get_type ()

### EUIManagerShortcutDef

    typedef struct {
    	guint key;
    	GdkModifierType mods;
    } EUIManagerShortcutDef;

### EUIManager

    typedef struct _EUIManager EUIManager;

## Property Details

### The `“customizer-filename”` property

      “customizer-filename”      char *

A file name, into which the customizations are saved and loaded from. It can be `NULL`, when the customizations are disabled.

Owner: EUIManager

Flags: Read / Write / Construct Only

Default value: NULL

Since: 3.56

## Signal Details

### The `“changed”` signal

    void
    user_function (EUIManager *manager,
                   gpointer    user_data)

A signal called when the `manager` content changed. It's a signal to regenerate the UI elements.

#### Parameters

manager | an EUIManager |
user_data | user data set when the signal handler was connected. |

Flags: Action

Since: 3.56

### The `“create-gicon”` signal

    gboolean
    user_function (EUIManager *manager,
                   char       *name,
                   gpointer    out_gicon,
                   gpointer    user_data)

The actions can have defined custom icons as "gicon::name", aka with a "gicon::" prefix, which are looked for by the name (without the special prefix) using this callback.

It's expected only one handler can create the GIcon, thus the first which returns `TRUE` will stop further signal emission.

#### Parameters

manager | an EUIManager |
name | a custom icon name |
out_gicon | an output location to store a created GIcon to. | [out][transfer full]
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` when the item was created and set into the `out_gicon` , `FALSE` when cannot create the item

Flags: Action

Since: 3.56

### The `“create-item”` signal

    gboolean
    user_function (EUIManager    *manager,
                   gpointer       elem,
                   EUIAction     *action,
                   EUIElementKind for_kind,
                   gpointer       out_item,
                   gpointer       user_data)

Return `TRUE`, when could create the item described by `elem` with associated `action` and sets it into the `out_item` . The `for_kind` can only be `E_UI_ELEMENT_KIND_HEADERBAR`, `E_UI_ELEMENT_KIND_TOOLBAR` or `E_UI_ELEMENT_KIND_MENU`.

For the `E_UI_ELEMENT_KIND_HEADERBAR` any widget can be returned, though the mostly used might be an EHeaderBarButton.

For the `E_UI_ELEMENT_KIND_TOOLBAR` only a GtkToolItem descendant is expected.

For the `E_UI_ELEMENT_KIND_MENU` only a GMenuItem descendant is expected.

It's expected only one handler can create the item, thus the first which returns `TRUE` will stop further signal emission.

[skip]

#### Parameters

manager | an EUIManager |
elem | an EUIElement to create the item for |
action | an associated `EUIAction` for the new item |
for_kind | for which part of the UI the item should be created; it influences the type of the returned item |
out_item | a location to set the created item to. | [out][transfer full]
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE` when the item was created and set into the `out_item` , `FALSE` when cannot create the item

Flags: Action

Since: 3.56

### The `“freeze”` signal

    void
    user_function (EUIManager *manager,
                   gpointer    user_data)

A signal called when the `manager` has called `e_ui_manager_freeze()`.

#### Parameters

manager | an EUIManager |
user_data | user data set when the signal handler was connected. |

Flags: Action

Since: 3.56

### The `“ignore-accel”` signal

    gboolean
    user_function (EUIManager *manager,
                   EUIAction  *action,
                   gpointer    user_data)

The signal allows to ignore accelerators to be activated.

Multiple signal handlers can be connected, the first which returns `TRUE` will stop the signal emission and the accelerator will be ignored. When all handlers return `FALSE`, the accelerator will be used and the `action` will be activated.

#### Parameters

manager | an EUIManager |
action | an EUIAction whose accelerator is about to be activated |
user_data | user data set when the signal handler was connected. |

#### Returns

`TRUE`, when the accel should be ignored, `FALSE` to allow the accel to be activated.

Flags: Action

Since: 3.56

### The `“thaw”` signal

    void
    user_function (EUIManager *manager,
                   gboolean    changed_while_frozen,
                   gpointer    user_data)

A signal called when the `manager` has called `e_ui_manager_thaw()`. When the `changed_while_frozen` is set to `TRUE`, there will also be called the “changed” signal once the `manager` is completely unfrozen.

#### Parameters

manager | an EUIManager |
changed_while_frozen | whether changed while had been frozen |
user_data | user data set when the signal handler was connected. |

Flags: Action

Since: 3.56