e-ui-customizer: Evolution Utilities Reference Manual

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

## Functions

const gchar * | e_ui_customizer_get_filename ()
struct _EUIManager * | e_ui_customizer_get_manager ()
EUIParser * | e_ui_customizer_get_parser ()
gboolean | e_ui_customizer_load ()
gboolean | e_ui_customizer_save ()
void | e_ui_customizer_register ()
GPtrArray * | e_ui_customizer_list_registered ()
const gchar * | e_ui_customizer_get_registered_display_name ()
EUIElement * | e_ui_customizer_get_element ()
GPtrArray * | e_ui_customizer_get_accels ()
void | e_ui_customizer_take_accels ()
void | e_ui_customizer_rename_actions ()
gchar * | e_ui_customizer_util_dup_filename_for_component ()
void | (*EUICustomizeFunc) ()
void | e_ui_customizer_util_attach_toolbar_context_menu ()

## Properties

char * | filename | Read / Write / Construct Only
EUIManager * | manager | Read / Write / Construct Only

## Signals

void | accels-changed | Action
void | changed | Action

## Types and Values

#define | E_TYPE_UI_CUSTOMIZER
| EUIActionRename
| EUICustomizer

## Object Hierarchy

        GObject
        ╰── EUICustomizer

## Includes

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

## Description

The EUICustomizer allows to customize UI elements like menus, toolbars and headerbars. The customizer is created and owned by an EUIManager, if the customizations are allowed for it. Use `e_ui_manager_get_customizer()` to get it.

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

## Functions

### e_ui_customizer_get_filename ()

    const gchar *
    e_ui_customizer_get_filename (EUICustomizer *self);

Returns the file name the `self` was constructed with.

#### Parameters

self | an EUICustomizer |

#### Returns

the file name the `self` was constructed with.

[transfer none]

Since: 3.56

### e_ui_customizer_get_manager ()

    struct _EUIManager *
    e_ui_customizer_get_manager (EUICustomizer *self);

Returns the EUIManager the `self` was constructed for.

#### Parameters

self | an EUICustomizer |

#### Returns

the EUIManager the `self` was constructed for.

[transfer none]

Since: 3.56

### e_ui_customizer_get_parser ()

    EUIParser *
    e_ui_customizer_get_parser (EUICustomizer *self);

Returns the EUIParser the `self` uses to store the customizations.

#### Parameters

self | an EUICustomizer |

#### Returns

the EUIParser the `self` uses to store the customizations.

[transfer none]

Since: 3.56

### e_ui_customizer_load ()

    gboolean
    e_ui_customizer_load (EUICustomizer *self,
                          GError **error);

Loads any changes for the `self` from the file path provided in the construction time, discarding any current changes. It's usually not needed to call this function, because it's called during the `self` construction.

Note it's okay to call the function when the file does not exist.

#### Parameters

self | an EUICustomizer |
error | an output variable for a GError, or `NULL` |

#### Returns

whether succeeded

Since: 3.56

### e_ui_customizer_save ()

    gboolean
    e_ui_customizer_save (EUICustomizer *self,
                          GError **error);

Saves any changes in the `self` to the file path provided in the construction time.

#### Parameters

self | an EUICustomizer |
error | an output variable for a GError, or `NULL` |

#### Returns

whether succeeded

Since: 3.56

### e_ui_customizer_register ()

    void
    e_ui_customizer_register (EUICustomizer *self,
                              const gchar *id,
                              const gchar *display_name);

Registers a UI element as customizable. The `id` should reference an existing element in the corresponding EUIManager, which is of kind menu, headerbar or toolbar.

The `display_name` can override the user-visible name of the customizable element. If `NULL`, the display name is assigned from the kind of the element.

#### Parameters

self | an EUICustomizer |
id | an ID of a customizable UI element |
display_name | name shown in the UI, localized, or `NULL`. | [nullable]

Since: 3.56

### e_ui_customizer_list_registered ()

    GPtrArray *
    e_ui_customizer_list_registered (EUICustomizer *self);

Returns an array of ID-s of all the registered elements by the `e_ui_customizer_register()`. Free the returned array, if not `NULL`, with the `g_ptr_array_unref()`, when no longer needed.

#### Parameters

self | an EUICustomizer |

#### Returns

a GPtrArray with id-s of the registered customizable elements, or `NULL`, when none was registered.

[transfer container][element-type utf8][nullable]

Since: 3.56

### e_ui_customizer_get_registered_display_name ()

    const gchar *
    e_ui_customizer_get_registered_display_name
                                   (EUICustomizer *self,
                                    const gchar *id);

Returns stored display name for the registered `id` by the `e_ui_customizer_register()`. This display name represents a user-visible text, under which the part shows up in the customization dialog.

#### Parameters

self | an EUICustomizer |
id | an ID of the registered element |

#### Returns

a stored display name for the `id` , or `NULL`, when the `id` is unknown.

[nullable]

Since: 3.56

### e_ui_customizer_get_element ()

    EUIElement *
    e_ui_customizer_get_element (EUICustomizer *self,
                                 const gchar *id);

Returns a toplevel headerbar, toolbar or menu with ID `id` , if such had been customized.

#### Parameters

self | an EUICustomizer |
id | an element ID |

#### Returns

a customized EUIElement of the ID `id` , or `NULL` when not customized.

[nullable][transfer none]

Since: 3.56

### e_ui_customizer_get_accels ()

    GPtrArray *
    e_ui_customizer_get_accels (EUICustomizer *self,
                                const gchar *action_name);

Returns an array of the defined accelerators for the `action_name` , to be used instead of those defined in the code. An empty array means no accels to be used, while a `NULL` means no accels had been set for the `action_name` .

The first item of the returned array is meant as the main accelerator, while the following are secondary accelerators.

#### Parameters

self | an EUICustomizer |
action_name | an action name |

#### Returns

a GPtrArray with the accelerators for the `action_name` , or `NULL`.

[nullable][transfer none][element-type utf8]

Since: 3.56

### e_ui_customizer_take_accels ()

    void
    e_ui_customizer_take_accels (EUICustomizer *self,
                                 const gchar *action_name,
                                 GPtrArray *accels);

Sets the `accels` as the accelerators for the action `action_name` . Use `NULL` to unset any previous values.

The function assumes ownership of the `accels` .

#### Parameters

self | an EUICustomizer |
action_name | an action name |
accels | accelerators to use, or `NULL` to unset. | [nullable][transfer full][element-type utf8]

Since: 3.56

### e_ui_customizer_rename_actions ()

    void
    e_ui_customizer_rename_actions (EUICustomizer *self,
                                    const EUIActionRename *renames,
                                    guint n_renames);

Renames action references in the loaded customization data. This is used to migrate user customizations when action names change between versions. The old action names in menus, toolbars, headerbars and accelerator overrides are replaced with the new names.

#### Parameters

self | an EUICustomizer |
renames | an array of old/new action name pairs. | [array length=n_renames]
n_renames | the number of elements in `renames` |

Since: 3.62

### e_ui_customizer_util_dup_filename_for_component ()

    gchar *
    e_ui_customizer_util_dup_filename_for_component
                                   (const gchar *component);

Builds a full path to a file, where the `component` may store its UI customizations.

#### Parameters

component | a component name |

#### Returns

a full path to store UI customizations.

[transfer full]

Since: 3.56

### EUICustomizeFunc ()

    void
    (*EUICustomizeFunc) (GtkWidget *widget,
                         const gchar *id,
                         gpointer user_data);

### e_ui_customizer_util_attach_toolbar_context_menu ()

    void
    e_ui_customizer_util_attach_toolbar_context_menu
                                   (GtkWidget *widget,
                                    const gchar *toolbar_id,
                                    EUICustomizeFunc func,
                                    gpointer user_data);

Attaches a context menu popup signal handler for the `widget` , which will popup a menu with "Customize Toolbar..." option and when this is selected, the `func` is called.

#### Parameters

widget | a GtkToolbar widget |
toolbar_id | id of the toolbar in a .eui definition |
func | an EUICustomizeFunc to call |
user_data | user data passed to the `func` |

Since: 3.56

## Types and Values

### E_TYPE_UI_CUSTOMIZER

    #define E_TYPE_UI_CUSTOMIZER e_ui_customizer_get_type ()

### EUIActionRename

    typedef struct {
    	const gchar *old_name;
    	const gchar *new_name;
    } EUIActionRename;

### EUICustomizer

    typedef struct _EUICustomizer EUICustomizer;

## Property Details

### The `“filename”` property

      “filename”                 char *

A file name, into which the customizations are saved and loaded from.

Owner: EUICustomizer

Flags: Read / Write / Construct Only

Default value: NULL

Since: 3.56

### The `“manager”` property

      “manager”                  EUIManager *

An EUIManager holding the default settings/layout of the UI actions.

Owner: EUICustomizer

Flags: Read / Write / Construct Only

Since: 3.56

## Signal Details

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

    void
    user_function (EUICustomizer *customizer,
                   char          *action_name,
                   GPtrArray     *old_accels,
                   GPtrArray     *new_accels,
                   gpointer       user_data)

Emitted when the settings for the accels change. When the `old_accels` is `NULL`, the there had not been set any accels for the `action_name` yet. When the `new_accels` is `NULL`, the accels for the `action_name` had been removed. For the `NULL` the accels defined on the EUIAction should be used.

#### Parameters

customizer | an EUICustomizer |
action_name | an action name |
old_accels | accels used before the change, or `NULL`. | [element-type utf8][nullable]
new_accels | accels used after the change, or `NULL`. | [element-type utf8][nullable]
user_data | user data set when the signal handler was connected. |

Flags: Action

Since: 3.56

### The `“changed”` signal

    void
    user_function (EUICustomizer *customizer,
                   gpointer       user_data)

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

#### Parameters

customizer | an EUICustomizer |
user_data | user data set when the signal handler was connected. |

Flags: Action

Since: 3.56