e-ui-parser: Evolution Utilities Reference Manual

## e-ui-parser e-ui-parser — a UI definition parser |

## Functions

EUIElement * | e_ui_element_copy ()
void | e_ui_element_free ()
EUIElement * | e_ui_element_new_separator ()
EUIElement * | e_ui_element_new_for_action ()
void | e_ui_element_add_child ()
gboolean | e_ui_element_remove_child ()
gboolean | e_ui_element_remove_child_by_id ()
EUIElementKind | e_ui_element_get_kind ()
const gchar * | e_ui_element_get_id ()
guint | e_ui_element_get_n_children ()
EUIElement * | e_ui_element_get_child ()
EUIElement * | e_ui_element_get_child_by_id ()
gboolean | e_ui_element_menu_get_is_popup ()
const gchar * | e_ui_element_submenu_get_action ()
gboolean | e_ui_element_headerbar_get_use_gtk_type ()
gboolean | e_ui_element_toolbar_get_primary ()
guint | e_ui_element_item_get_label_priority ()
gint | e_ui_element_item_get_order ()
void | e_ui_element_item_set_order ()
gboolean | e_ui_element_item_get_icon_only_is_set ()
gboolean | e_ui_element_item_get_icon_only ()
gboolean | e_ui_element_item_get_text_only_is_set ()
gboolean | e_ui_element_item_get_text_only ()
gboolean | e_ui_element_item_get_important ()
gboolean | e_ui_element_item_get_use_secondary_label ()
const gchar * | e_ui_element_item_get_css_classes ()
const gchar * | e_ui_element_item_get_action ()
const gchar * | e_ui_element_item_get_group ()
EUIParser * | e_ui_parser_new ()
gboolean | e_ui_parser_merge_file ()
gboolean | e_ui_parser_merge_data ()
void | e_ui_parser_clear ()
EUIElement * | e_ui_parser_get_root ()
EUIElement * | e_ui_parser_create_root ()
GPtrArray * | e_ui_parser_get_accels ()
void | e_ui_parser_take_accels ()
gchar * | e_ui_parser_export ()

## Signals

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

## Types and Values

#define | E_TYPE_UI_PARSER
| EUIParser

## Object Hierarchy

        GBoxed
        ╰── EUIElement
        GObject
        ╰── EUIParser

## Includes

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

## Description

EUIParser parses UI definitions for menus, headerbar and toolbar from an XML data. It's associated with an EUIManager.

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

## Functions

### e_ui_element_copy ()

    EUIElement *
    e_ui_element_copy (const EUIElement *src);

Creates a copy of the `src` . Free the returned pointer with `e_ui_element_free()`, when no longer needed. The function does nothing when the `src` is NULL.

This does not copy the `src` children, it only copies the `src` itself.

#### Parameters

src | an EUIElement to create a copy of |

#### Returns

copy of the `src` , or `NULL`, when the `src` is `NULL`.

[transfer full][nullable]

Since: 3.56

### e_ui_element_free ()

    void
    e_ui_element_free (EUIElement *self);

Frees the `self` . The function does nothing when the `self` is `NULL`.

#### Parameters

self | an EUIElement. | [nullable][transfer full]

Since: 3.56

### e_ui_element_new_separator ()

    EUIElement *
    e_ui_element_new_separator (void);

Creates a new EUIElement of kind `E_UI_ELEMENT_KIND_SEPARATOR`. Free it with `e_ui_element_free()`, when no longer needed.

#### Returns

a new separator EUIElement.

[transfer full]

Since: 3.56

### e_ui_element_new_for_action ()

    EUIElement *
    e_ui_element_new_for_action (EUIAction *action);

Creates a new EUIElement referencing the `action` .

#### Parameters

action | an EUIAction |

#### Returns

a new EUIElement referencing the `action` .

[transfer full]

Since: 3.58

### e_ui_element_add_child ()

    void
    e_ui_element_add_child (EUIElement *self,
                            EUIElement *child);

Adds a new `child` into the `self` . The function assumes ownership of the `child` .

#### Parameters

self | an EUIElement to add the child to |
child | the child to add. | [transfer full]

Since: 3.56

### e_ui_element_remove_child ()

    gboolean
    e_ui_element_remove_child (EUIElement *self,
                               EUIElement *child);

Removes a direct `child` from the children of the `self` .

See `e_ui_element_remove_child_by_id()`.

#### Parameters

self | an EUIElement |
child | a direct child to remove |

#### Returns

whether the `child` had been removed; if it is, it is also freed

Since: 3.56

### e_ui_element_remove_child_by_id ()

    gboolean
    e_ui_element_remove_child_by_id (EUIElement *self,
                                     const gchar *id);

Removes a direct child of the `self` with ID `id` .

#### Parameters

self | an EUIElement |
id | a direct child ID to be removed |

#### Returns

whether the child with the ID `id` had been removed; if it is, it is also freed

Since: 3.56

### e_ui_element_get_kind ()

    EUIElementKind
    e_ui_element_get_kind (const EUIElement *self);

Gets the kind of the `self` .

#### Parameters

self | an EUIElement |

#### Returns

an EUIElementKind of the `self`

Since: 3.56

### e_ui_element_get_id ()

    const gchar *
    e_ui_element_get_id (const EUIElement *self);

Gets the identifier of the `self` .

#### Parameters

self | an EUIElement |

#### Returns

an identifier of the `self` .

[nullable]

Since: 3.56

### e_ui_element_get_n_children ()

    guint
    e_ui_element_get_n_children (const EUIElement *self);

Gets how many children the element has.

#### Parameters

self | an EUIElement |

#### Returns

count of children of the `self`

Since: 3.56

### e_ui_element_get_child ()

    EUIElement *
    e_ui_element_get_child (EUIElement *self,
                            guint index);

Gets a child at `index` , which should be less than `e_ui_element_get_n_children()`.

#### Parameters

self | an EUIElement |
index | an index of the child to get |

#### Returns

a child element at index `index` , or `NULL`, when `index` is out of bounds.

[transfer none][nullable]

Since: 3.56

### e_ui_element_get_child_by_id ()

    EUIElement *
    e_ui_element_get_child_by_id (EUIElement *self,
                                  const gchar *id);

Gets a child by its identifier. It searches the direct children of the `self` only.

#### Parameters

self | an EUIElement |
id | an identified of the child to get |

#### Returns

a child element with identifier `id` , or `NULL`, when not found.

[transfer none][nullable]

Since: 3.56

### e_ui_element_menu_get_is_popup ()

    gboolean
    e_ui_element_menu_get_is_popup (const EUIElement *self);

Gets a whether a menu is a popup (context) menu. Such menu hides actions when they are insensitive. The default value is `FALSE`.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_MENU`.

#### Parameters

self | an EUIElement |

#### Returns

whether the menu is a popup menu

Since: 3.56

### e_ui_element_submenu_get_action ()

    const gchar *
    e_ui_element_submenu_get_action (const EUIElement *self);

Gets a submenu action name.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_SUBMENU`.

#### Parameters

self | an EUIElement |

#### Returns

an action name for the submenu element

Since: 3.56

### e_ui_element_headerbar_get_use_gtk_type ()

    gboolean
    e_ui_element_headerbar_get_use_gtk_type
                                   (const EUIElement *self);

Gets whether a GtkHeaderBar should be created, instead of an EHeaderBar.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_HEADERBAR`.

#### Parameters

self | an EUIElement |

#### Returns

whether create GtkHeaderBar

Since: 3.56

### e_ui_element_toolbar_get_primary ()

    gboolean
    e_ui_element_toolbar_get_primary (const EUIElement *self);

Gets whether the toolbar is a primary toolbar.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_TOOLBAR`.

#### Parameters

self | an EUIElement |

#### Returns

whether the toolbar is a primary toolbar

Since: 3.56

### e_ui_element_item_get_label_priority ()

    guint
    e_ui_element_item_get_label_priority (const EUIElement *self);

Gets a label priority value for an item element. It is set only for headerbar items.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_ITEM`.

#### Parameters

self | an EUIElement |

#### Returns

a label priority

Since: 3.56

### e_ui_element_item_get_order ()

    gint
    e_ui_element_item_get_order (const EUIElement *self);

Gets order of the button in the header bar. Items with lower number are added before items with higher number. The default value is zero, meaning use the order as added through the .eui file.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_ITEM`.

#### Parameters

self | an EUIElement |

#### Returns

order index of the header bar item

Since: 3.56

### e_ui_element_item_set_order ()

    void
    e_ui_element_item_set_order (EUIElement *self,
                                 gint order);

Sets an order of the button in the header bar. See `e_ui_element_item_get_order()` for more information.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_ITEM`.

#### Parameters

self | an EUIElement |
order | the value to set |

Since: 3.56

### e_ui_element_item_get_icon_only_is_set ()

    gboolean
    e_ui_element_item_get_icon_only_is_set
                                   (const EUIElement *self);

Gets whether an item has set icon-only property. The default value is `FALSE`. It is set only for headerbar items. Use `e_ui_element_item_get_icon_only()` to get the actual value.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_ITEM`.

#### Parameters

self | an EUIElement |

#### Returns

whether the icon-only property is set

Since: 3.56

### e_ui_element_item_get_icon_only ()

    gboolean
    e_ui_element_item_get_icon_only (const EUIElement *self);

Gets whether an item may show only icon. The default value is `FALSE`. It is set only for headerbar items. Use `e_ui_element_item_get_icon_only_is_set()` to check whether the value had been set.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_ITEM`.

#### Parameters

self | an EUIElement |

#### Returns

whether to show only icon

Since: 3.56

### e_ui_element_item_get_text_only_is_set ()

    gboolean
    e_ui_element_item_get_text_only_is_set
                                   (const EUIElement *self);

Gets whether an item has set text-only property. The default value is `FALSE`. Use `e_ui_element_item_get_text_only()` to get the actual value.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_ITEM`.

#### Parameters

self | an EUIElement |

#### Returns

whether the text-only property is set

Since: 3.56

### e_ui_element_item_get_text_only ()

    gboolean
    e_ui_element_item_get_text_only (const EUIElement *self);

Gets whether an item may show only text. The default value is `FALSE`. Use `e_ui_element_item_get_text_only_is_set()` to check whether the value had been set.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_ITEM`.

#### Parameters

self | an EUIElement |

#### Returns

whether to show only text

Since: 3.56

### e_ui_element_item_get_important ()

    gboolean
    e_ui_element_item_get_important (const EUIElement *self);

Gets whether an item is important. The default value is `FALSE`. It's used for items inside toolbars.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_ITEM`.

#### Parameters

self | an EUIElement |

#### Returns

whether the item is important

Since: 3.56

### e_ui_element_item_get_use_secondary_label ()

    gboolean
    e_ui_element_item_get_use_secondary_label
                                   (const EUIElement *self);

Gets whether the item should use the action's secondary label instead of the primary label.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_ITEM`.

#### Parameters

self | an EUIElement |

#### Returns

whether the secondary label should be used

Since: 3.62

### e_ui_element_item_get_css_classes ()

    const gchar *
    e_ui_element_item_get_css_classes (const EUIElement *self);

Gets a space-separated list of CSS classes to add on the item.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_ITEM`.

#### Parameters

self | an EUIElement |

#### Returns

a space-separated list of CSS classes to add on a GtkWidget, or `NULL`, when not set.

[nullable]

Since: 3.56

### e_ui_element_item_get_action ()

    const gchar *
    e_ui_element_item_get_action (const EUIElement *self);

Gets a item action name.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_ITEM`.

#### Parameters

self | an EUIElement |

#### Returns

an action name

Since: 3.56

### e_ui_element_item_get_group ()

    const gchar *
    e_ui_element_item_get_group (const EUIElement *self);

Gets a radio group name.

This can be called only on elements of kind `E_UI_ELEMENT_KIND_ITEM`.

#### Parameters

self | an EUIElement |

#### Returns

a radio group name of an item, or `NULL`, when the item is not part of any radio group.

[nullable]

Since: 3.56

### e_ui_parser_new ()

    EUIParser *
    e_ui_parser_new (void);

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

#### Returns

a new EUIParser.

[transfer full]

Since: 3.56

### e_ui_parser_merge_file ()

    gboolean
    e_ui_parser_merge_file (EUIParser *self,
                            const gchar *filename,
                            GError **error);

Adds content of the `filename` into the UI definition. Items with the same identifier are reused, allowing to add new items into existing hierarchy.

#### Parameters

self | an EUIParser |
filename | a filename to merge |
error | an output location to store a GError at, or `NULL` |

#### Returns

whether could successfully parse the file content. On failure, the `error` is set.

Since: 3.56

### e_ui_parser_merge_data ()

    gboolean
    e_ui_parser_merge_data (EUIParser *self,
                            const gchar *data,
                            gssize data_len,
                            GError **error);

Adds content of the `data` into the UI definition. Items with the same identifier are reused, allowing to add new items into existing hierarchy.

#### Parameters

self | an EUIParser |
data | a data to merge |
data_len | length of the `data` , or -1, when NUL-terminated |
error | an output location to store a GError at, or `NULL` |

#### Returns

whether could successfully parse the file content. On failure, the `error` is set.

Since: 3.56

### e_ui_parser_clear ()

    void
    e_ui_parser_clear (EUIParser *self);

Removes all content of the `self` .

#### Parameters

self | an EUIParser |

Since: 3.56

### e_ui_parser_get_root ()

    EUIElement *
    e_ui_parser_get_root (EUIParser *self);

Gets the root element of the `self` .

#### Parameters

self | an EUIParser |

#### Returns

a root EUIElement, or `NULL`, when nothing was parsed yet.

[nullable][transfer none]

Since: 3.56

### e_ui_parser_create_root ()

    EUIElement *
    e_ui_parser_create_root (EUIParser *self);

Clears any current content of the `self` and create a new root element, which will be used by the `self` .

#### Parameters

self | and EUIParser |

#### Returns

a new root element of the `self` .

[transfer none]

Since: 3.56

### e_ui_parser_get_accels ()

    GPtrArray *
    e_ui_parser_get_accels (EUIParser *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 EUIParser |
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_parser_take_accels ()

    void
    e_ui_parser_take_accels (EUIParser *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 EUIParser |
action_name | an action name |
accels | accelerators to use, or `NULL` to unset. | [nullable][transfer full][element-type utf8]

Since: 3.56

### e_ui_parser_export ()

    gchar *
    e_ui_parser_export (EUIParser *self,
                        EUIParserExportFlags flags);

Exports the content of the `self` in a format suitable for `e_ui_parser_merge_file()` and `e_ui_parser_merge_data()`.

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

#### Parameters

self | an EUIParser |
flags | a bit-or of EUIParserExportFlags flags |

#### Returns

a string representation of the `self` content, or `NULL`, when the `self` is empty.

[transfer full][nullable]

Since: 3.56

## Types and Values

### E_TYPE_UI_PARSER

    #define E_TYPE_UI_PARSER e_ui_parser_get_type ()

### EUIParser

    typedef struct _EUIParser EUIParser;

## Signal Details

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

    void
    user_function (EUIParser *parser,
                   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

parser | an EUIParser |
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 (EUIParser *parser,
                   gpointer   user_data)

Emitted when the content of the `parser` changes.

#### Parameters

parser | an EUIParser |
user_data | user data set when the signal handler was connected. |

Flags: Action

Since: 3.56