## AnjutaUI

AnjutaUI — User Interface manager

##

# Synopsis

    struct      AnjutaUI;
    AnjutaUI*   anjuta_ui_new                   (void);
    GtkActionGroup* anjuta_ui_add_action_group_entries
                                                (AnjutaUI *ui,
                                                 const gchar *action_group_name,
                                                 const gchar *action_group_label,
                                                 GtkActionEntry *entries,
                                                 gint num_entries,
                                                 gpointer user_data);
    GtkActionGroup* anjuta_ui_add_toggle_action_group_entries
                                                (AnjutaUI *ui,
                                                 const gchar *action_group_name,
                                                 const gchar *action_group_label,
                                                 GtkToggleActionEntry *entries,
                                                 gint num_entries,
                                                 gpointer user_data);
    void        anjuta_ui_add_action_group      (AnjutaUI *ui,
                                                 const gchar *action_group_name,
                                                 const gchar *action_group_label,
                                                 GtkActionGroup *action_group);
    void        anjuta_ui_remove_action_group   (AnjutaUI *ui,
                                                 GtkActionGroup *action_group);
    GtkAction*  anjuta_ui_get_action            (AnjutaUI *ui,
                                                 const gchar *action_group_name,
                                                 const gchar *action_name);
    void        anjuta_ui_activate_action_by_path
                                                (AnjutaUI *ui,
                                                 const gchar *action_path);
    void        anjuta_ui_activate_action_by_group
                                                (AnjutaUI *ui,
                                                 GtkActionGroup *action_group,
                                                 const gchar *action_name);
    gint        anjuta_ui_merge                 (AnjutaUI *ui,
                                                 const gchar *ui_filename);
    void        anjuta_ui_unmerge               (AnjutaUI *ui,
                                                 gint id);
    GtkIconFactory* anjuta_ui_get_icon_factory  (AnjutaUI *ui);
    GtkAccelGroup* anjuta_ui_get_accel_group    (AnjutaUI *ui);
    GtkWidget*  anjuta_ui_get_accel_editor      (AnjutaUI *ui);
    void        anjuta_ui_dump_tree             (AnjutaUI *ui);

## Object Hierarchy

      GObject
       +----GtkUIManager
             +----AnjutaUI

## Description

AnjutaUI subclasses GtkUIManager, so you should really read GtkUIManager documentation first to know about Actions, UI merging and UI XML file format. This documentation will cover only the relevent APIs.

AnjutaUI has its own methods for adding action groups, which is differnt from GtkUIManager methods. All AnjutaPlugin based classes should use these methods instead of GtkUIManager methods. The reason is, in addition to adding the actions and groups to the UI manager, it also resgisters them for UI customization and accellerators editing. It also keeps record of all actions.

An interesting side effect of this is that these actions could be conveniently accessed or activated with `anjuta_ui_get_action()` or `anjuta_ui_activate_action_by_path()`, without the need of original action group object. This makes it is possible for activating actions remotely from other plugins.

`anjuta_ui_get_accel_editor()` will return a widget containing the UI customization and accellerators editor. All actions and action groups are organized into a tree view, which should be added to a visible container (e.g. a GtkDialog based object) and displayed to users.

### Note

Any actions additions/removals using GtkUIManager are not registred with AnjutaUI and hence their accellerators cannot be edited. Nor will they be listed in UI manager dialog. Hence, use AnjutaUI methods whenever possible.

## Details

### struct AnjutaUI

    struct AnjutaUI;

### anjuta_ui_new ()

    AnjutaUI*   anjuta_ui_new                   (void);

Creates a new instance of AnjutaUI.

Returns : | A AnjutaUI object

### anjuta_ui_add_action_group_entries ()

    GtkActionGroup* anjuta_ui_add_action_group_entries
                                                (AnjutaUI *ui,
                                                 const gchar *action_group_name,
                                                 const gchar *action_group_label,
                                                 GtkActionEntry *entries,
                                                 gint num_entries,
                                                 gpointer user_data);

GtkAction objects are created from the GtkActionEntry structures and added to the UI Manager. "activate" signal of GtkAction is connected for all the action objects using the callback in the entry structure and the `user_data` passed here.

This group of actions are registered with the name `action_group_name` in AnjutaUI. A GtkAction object from this action group can be later retrieved by `anjuta_ui_get_action()` using `action_group_name` and action name. `action_group_label` is used as the display name for the action group in UI manager dialog where action shortcuts are configured.

`ui` : | A AnjutaUI object.
`action_group_name` : | Untranslated name of the action group.
`action_group_label` : | Translated label of the action group.
`entries` : | An array of action entries.
`num_entries` : | Number of elements in the action entries array.
`user_data` : | User data to pass to action objects. This is the data that will come as user_data in "activate" signal of the actions.
Returns : | A GtkActionGroup object holding all the action objects.

### anjuta_ui_add_toggle_action_group_entries ()

    GtkActionGroup* anjuta_ui_add_toggle_action_group_entries
                                                (AnjutaUI *ui,
                                                 const gchar *action_group_name,
                                                 const gchar *action_group_label,
                                                 GtkToggleActionEntry *entries,
                                                 gint num_entries,
                                                 gpointer user_data);

This is similar to `anjuta_ui_add_action_group_entries()`, except that it adds GtkToggleAction objects after creating them from the `entries`.

`ui` : | A AnjutaUI object.
`action_group_name` : | Untranslated name of the action group.
`action_group_label` : | Translated label of the action group.
`entries` : | An array of action entries.
`num_entries` : | Number of elements in the action entries array.
`user_data` : | User data to pass to action objects. This is the data that will come as user_data in "activate" signal of the actions.
Returns : | A GtkActionGroup object holding all the action objects.

### anjuta_ui_add_action_group ()

    void        anjuta_ui_add_action_group      (AnjutaUI *ui,
                                                 const gchar *action_group_name,
                                                 const gchar *action_group_label,
                                                 GtkActionGroup *action_group);

This is similar to `anjuta_ui_add_action_group_entries()`, except that it adds GtkActionGroup object `action_group` directly. All actions in this group are automatically registered in AnjutaUI and can be retrieved normally with `anjuta_ui_get_action()`.

`ui` : | A AnjutaUI object.
`action_group_name` : | Untranslated name of the action group.
`action_group_label` : | Translated label of the action group.
`action_group` : | GtkActionGroup object to add.

### anjuta_ui_remove_action_group ()

    void        anjuta_ui_remove_action_group   (AnjutaUI *ui,
                                                 GtkActionGroup *action_group);

Removes a previous added action group. All actions in this group are also unregistered from UI manager.

`ui` : | A AnjutaUI object
`action_group` : | GtkActionGroup object to remove.

### anjuta_ui_get_action ()

    GtkAction*  anjuta_ui_get_action            (AnjutaUI *ui,
                                                 const gchar *action_group_name,
                                                 const gchar *action_name);

`ui` : | This AnjutaUI object
`action_group_name` : | Group name.
`action_name` : | Action name. returns: A GtkAction object
Returns : | the action object with the name `action_name` in `action_group_name`. Note that it will be only sucessully returned if the group has been added using methods in AnjutaUI.

### anjuta_ui_activate_action_by_path ()

    void        anjuta_ui_activate_action_by_path
                                                (AnjutaUI *ui,
                                                 const gchar *action_path);

Activates the action represented by `action_path`. The path is in the form "ActionGroupName/ActionName". Note that it will only work if the group has been added using methods in AnjutaUI.

`ui` : | This AnjutaUI object
`action_path` : | Path of the action in the form "GroupName/ActionName"

### anjuta_ui_activate_action_by_group ()

    void        anjuta_ui_activate_action_by_group
                                                (AnjutaUI *ui,
                                                 GtkActionGroup *action_group,
                                                 const gchar *action_name);

Activates the action `action_name` in the GtkActionGroup `action_group`. "ActionGroupName/ActionName". Note that it will only work if the group has been added using methods in AnjutaUI.

`ui` : | This AnjutaUI object
`action_group` : | Action group.
`action_name` : | Action name.

### anjuta_ui_merge ()

    gint        anjuta_ui_merge                 (AnjutaUI *ui,
                                                 const gchar *ui_filename);

Merges XML UI definition in `ui_filename`. UI elements defined in the xml are merged with existing UI elements in UI manager. The format of the file content is the standard XML UI definition tree. For more detail, read the documentation for GtkUIManager.

`ui` : | A AnjutaUI object.
`ui_filename` : | UI file to merge into UI manager.
Returns : | Integer merge ID

### anjuta_ui_unmerge ()

    void        anjuta_ui_unmerge               (AnjutaUI *ui,
                                                 gint id);

Unmerges UI with the ID value `id` (returned by `anjuta_ui_merge()` when it was merged. For more detail, read the documentation for GtkUIManager.

`ui` : | A AnjutaUI object.
`id` : | Merge ID returned by `anjuta_ui_merge()`.

### anjuta_ui_get_icon_factory ()

    GtkIconFactory* anjuta_ui_get_icon_factory  (AnjutaUI *ui);

This returns the IconFactory object. All icons should be registered using this icon factory. Read the documentation for GtkIconFactory on how to use it.

`ui` : | A AnjutaUI object
Returns : | The GtkIconFactory object used by it

### anjuta_ui_get_accel_group ()

    GtkAccelGroup* anjuta_ui_get_accel_group    (AnjutaUI *ui);

`ui` : | A AnjutaUI object. returns: A GtkAccelGroup object.
Returns : | the GtkAccelGroup object associated with this UI manager.

### anjuta_ui_get_accel_editor ()

    GtkWidget*  anjuta_ui_get_accel_editor      (AnjutaUI *ui);

Creates an accel editor widget and returns it. It should be added to container and displayed to users.

`ui` : | A AnjutaUI object. returns: A GtkWidget object.
Returns : | a GtkWidget containing the editor.

### anjuta_ui_dump_tree ()

    void        anjuta_ui_dump_tree             (AnjutaUI *ui);

Dumps the current UI XML tree in STDOUT. Useful for debugging.

`ui` : | A AnjutaUI object.

## See Also

GtkAction, GtkActionEntry, GtkToggleAction, GtkToggleActionEntry, GtkRadioAction, GtkRadioActionEntry, GtkActionGroup, GtkUIManager