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 ()
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
| 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_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 ()

### 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