## AnjutaShell AnjutaShell — Application shell interface |

## Stability Level

Unstable, unless otherwise indicated

## Synopsis

    #include <libanjuta/anjuta-shell.h>

    #define             ANJUTA_SHELL_ERROR
                        AnjutaShell;
                        AnjutaShellIface;
    enum                AnjutaShellError;
    enum                AnjutaShellPlacement;
    GQuark              anjuta_shell_error_quark            (void);
    AnjutaStatus*       anjuta_shell_get_status             (AnjutaShell *shell,
                                                             GError **error);
    AnjutaUI*           anjuta_shell_get_ui                 (AnjutaShell *shell,
                                                             GError **error);
    AnjutaPreferences*  anjuta_shell_get_preferences        (AnjutaShell *shell,
                                                             GError **error);
    AnjutaPluginManager* anjuta_shell_get_plugin_manager    (AnjutaShell *shell,
                                                             GError **error);
    AnjutaProfileManager* anjuta_shell_get_profile_manager  (AnjutaShell *shell,
                                                             GError **error);
    void                anjuta_shell_freeze                 (AnjutaShell *shell,
                                                             GError **error);
    void                anjuta_shell_thaw                   (AnjutaShell *shell,
                                                             GError **error);
    void                anjuta_shell_add_widget             (AnjutaShell *shell,
                                                             GtkWidget *widget,
                                                             const char *name,
                                                             const char *title,
                                                             const char *stock_id,
                                                             AnjutaShellPlacement placement,
                                                             GError **error);
    void                anjuta_shell_add_widget_full        (AnjutaShell *shell,
                                                             GtkWidget *widget,
                                                             const char *name,
                                                             const char *title,
                                                             const char *stock_id,
                                                             AnjutaShellPlacement placement,
                                                             gboolean locked,
                                                             GError **error);
    void                anjuta_shell_add_widget_custom      (AnjutaShell *shell,
                                                             GtkWidget *widget,
                                                             const char *name,
                                                             const char *title,
                                                             const char *stock_id,
                                                             GtkWidget *label,
                                                             AnjutaShellPlacement placement,
                                                             GError **error);
    void                anjuta_shell_remove_widget          (AnjutaShell *shell,
                                                             GtkWidget *widget,
                                                             GError **error);
    void                anjuta_shell_present_widget         (AnjutaShell *shell,
                                                             GtkWidget *widget,
                                                             GError **error);
    void                anjuta_shell_add_value              (AnjutaShell *shell,
                                                             const char *name,
                                                             const GValue *value,
                                                             GError **error);
    void                anjuta_shell_add_valist             (AnjutaShell *shell,
                                                             const char *first_name,
                                                             GType first_type,
                                                             va_list var_args);
    void                anjuta_shell_add                    (AnjutaShell *shell,
                                                             const char *first_name,
                                                             GType first_type,
                                                             ...);
    void                anjuta_shell_get_value              (AnjutaShell *shell,
                                                             const char *name,
                                                             GValue *value,
                                                             GError **error);
    void                anjuta_shell_get_valist             (AnjutaShell *shell,
                                                             const char *first_name,
                                                             GType first_type,
                                                             va_list var_args);
    void                anjuta_shell_get                    (AnjutaShell *shell,
                                                             const char *first_name,
                                                             GType first_type,
                                                             ...);
    void                anjuta_shell_remove_value           (AnjutaShell *shell,
                                                             const char *name,
                                                             GError **error);
    GObject *           anjuta_shell_get_object             (AnjutaShell *shell,
                                                             const gchar *iface_name,
                                                             GError **error);
    void                anjuta_shell_session_save           (AnjutaShell *shell,
                                                             const gchar *session_directory,
                                                             GError **error);
    void                anjuta_shell_session_load           (AnjutaShell *shell,
                                                             const gchar *session_directory,
                                                             GError **error);
    void                anjuta_shell_save_prompt            (AnjutaShell *shell,
                                                             AnjutaSavePrompt *prompt,
                                                             GError **error);
    void                anjuta_shell_notify_exit            (AnjutaShell *shell,
                                                             GError **error);
    #define             anjuta_shell_get_interface          (shell, iface_type, error)

## Object Hierarchy

      GInterface
       +----AnjutaShell

## Prerequisites

AnjutaShell requires GObject.

## Signals

      "exiting"                                        : Run Last
      "load-session"                                   : Run Last
      "save-prompt"                                    : Run Last
      "save-session"                                   : Run Last
      "value-added"                                    : Run Last
      "value-removed"                                  : Run Last

## Description

Shell is the playground where plugins are loaded and their UI widgets shown. It is also a place where plugins export objects for letting other pluings to use. Plugins are loaded into shell on demand, but some plugins are loaded on startup (such as help and text editor plugin). Demand to load a plugin can be made by requesting for a primary inferface using `anjuta_shell_get_interface()` or `anjuta_shell_get_object()`.

Plugins can add widgets in shell with `anjuta_shell_add_widget()` and remove with `anjuta_shell_remove_widget()` functions.

In Anjuta, shell is implemented using an advanced widget docking system, allowing plugin widgets to dock, undock and layout in any fashion. Dock layout is also maintained internally and is transparent to plugin implementations.

AnjutaShell allows plugins to export arbitrary objects as values in its Values System. "value_added" and "value_removed" signals are emitted when a value is added to or removed from the Values System, hence notifying plugins of its state. However, plugins should really not connect directly to these signals, because they are emitted for all values and not just for the values the plugin is interested in. Instead, to monitor specific Values, plugins should setup watches using `anjuta_plugin_add_watch()`.

Values are added, get or removed with `anjuta_shell_add_value()` and `anjuta_shell_get_value()` or `anjuta_shell_remove_value()`. There multi-valued equivalent functions can be used to manipulate multiple values at once.

Values are identified with names. Since Values are effectively variables, their names should follow the standard GNOME variable naming convention and should be as descriptive as possible (e.g project_root_directory, project_name etc.). It is also essential that meaningful prefix be given to names so that Values are easily grouped (e.g all values exported by a project manager should start with project_ prefix).

Plugins can find other plugins with `anjuta_shell_get_object()` or `anjuta_shell_get_interface()` based on their primary interfaces.

## Details

### ANJUTA_SHELL_ERROR

    #define ANJUTA_SHELL_ERROR anjuta_shell_error_quark()

### AnjutaShell

    typedef struct _AnjutaShell AnjutaShell;

### AnjutaShellIface

    typedef struct {
    	GTypeInterface g_iface;

    	/* Signals */
    	void (*value_added)  (AnjutaShell *shell, char *name, GValue *value);
    	void (*value_removed) (AnjutaShell *shell, char *name);
    	void (*save_session) (AnjutaShell *shell, AnjutaSessionPhase phase,
    						  AnjutaSession *session);
    	void (*load_session) (AnjutaShell *shell, AnjutaSessionPhase phase,
    						  AnjutaSession *session);
    	void (*save_prompt)  (AnjutaShell *shell, AnjutaSavePrompt *save_prompt);
    	void (*exiting)      (AnjutaShell *shell);

    	/* Virtual Table */
    	AnjutaStatus* (*get_status) (AnjutaShell  *shell, GError **err);
    	AnjutaUI* (*get_ui) (AnjutaShell  *shell, GError **err);
    	AnjutaPreferences* (*get_preferences) (AnjutaShell *shell, GError **err);
    	AnjutaPluginManager* (*get_plugin_manager) (AnjutaShell *shell,
    												GError **err);
    	AnjutaProfileManager* (*get_profile_manager) (AnjutaShell *shell,
    												  GError **err);

    	void (*add_widget_full)   (AnjutaShell  *shell,
    							   GtkWidget    *widget,
    							   const char   *name,
    							   const char   *title,
    							   const char   *stock_id,
    							   AnjutaShellPlacement placement,
    							   gboolean locked,
    							   GError      **error);
    	void (*add_widget_custom)  (AnjutaShell  *shell,
    	                            GtkWidget    *widget,
    	                            const char   *name,
    	                            const char   *title,
    	                            const char   *stock_id,
    	                            GtkWidget    *label,
    	                            AnjutaShellPlacement placement,
    	                            GError      **error);

    	void (*remove_widget)     (AnjutaShell  *shell,
    							   GtkWidget    *widget,
    							   GError      **error);
    	void (*present_widget)    (AnjutaShell  *shell,
    							   GtkWidget    *widget,
    							   GError      **error);
    	void (*add_value)         (AnjutaShell  *shell,
    							   const char   *name,
    							   const GValue *value,
    							   GError       **error);
    	void (*get_value)         (AnjutaShell  *shell,
    							   const char   *name,
    							   GValue       *value,
    							   GError       **error);
    	void (*remove_value)      (AnjutaShell  *shell,
    							   const char   *name,
    							   GError       **error);
    	void (*saving_push)       (AnjutaShell* shell);
    	void (*saving_pop)        (AnjutaShell* shell);
    	GObject* (*get_object)    (AnjutaShell  *shell,
    							   const char   *iface_name,
    							   GError       **error);
    } AnjutaShellIface;

### enum AnjutaShellError

    typedef enum
    {
    	ANJUTA_SHELL_ERROR_DOESNT_EXIST,
    } AnjutaShellError;

### enum AnjutaShellPlacement

    typedef enum
    {
    	ANJUTA_SHELL_PLACEMENT_NONE = 0,
    	ANJUTA_SHELL_PLACEMENT_TOP,
    	ANJUTA_SHELL_PLACEMENT_BOTTOM,
    	ANJUTA_SHELL_PLACEMENT_RIGHT,
    	ANJUTA_SHELL_PLACEMENT_LEFT,
    	ANJUTA_SHELL_PLACEMENT_CENTER,
    	ANJUTA_SHELL_PLACEMENT_FLOATING
    } AnjutaShellPlacement;

### anjuta_shell_error_quark ()

    GQuark              anjuta_shell_error_quark            (void);

Returns : |

### anjuta_shell_get_status ()

    AnjutaStatus*       anjuta_shell_get_status             (AnjutaShell *shell,
                                                             GError **error);

Retrieves the AnjutaStatus object associated with the shell.

`shell` : | A AnjutaShell interface
`error` : | Error propagation object
Returns : | The AnjutaStatus object.

### anjuta_shell_get_ui ()

    AnjutaUI*           anjuta_shell_get_ui                 (AnjutaShell *shell,
                                                             GError **error);

Retrieves the AnjutaUI object associated with the shell.

`shell` : | A AnjutaShell interface
`error` : | Error propagation object
Returns : | The AnjutaUI object.

### anjuta_shell_get_preferences ()

    AnjutaPreferences*  anjuta_shell_get_preferences        (AnjutaShell *shell,
                                                             GError **error);

Retrieves the AnjutaPreferences object associated with the shell.

`shell` : | A AnjutaShell interface
`error` : | Error propagation object
Returns : | The AnjutaPreferences object.

### anjuta_shell_get_plugin_manager ()

    AnjutaPluginManager* anjuta_shell_get_plugin_manager    (AnjutaShell *shell,
                                                             GError **error);

Retrieves the AnjutaPluginManager object associated with the shell.

`shell` : | A AnjutaShell interface
`error` : | Error propagation object
Returns : | The AnjutaPluginManager object.

### anjuta_shell_get_profile_manager ()

    AnjutaProfileManager* anjuta_shell_get_profile_manager  (AnjutaShell *shell,
                                                             GError **error);

Retrieves the AnjutaProfileManager object associated with the shell.

`shell` : | A AnjutaShell interface
`error` : | Error propagation object
Returns : | The AnjutaProfileManager object.

### anjuta_shell_freeze ()

    void                anjuta_shell_freeze                 (AnjutaShell *shell,
                                                             GError **error);

Freezes addition of any UI elements (widgets) in the shell. All widget additions are queued for later additions when freeze count reaches 0. Any number of this function can be called and each call will increase the freeze count. `anjuta_shell_thaw()` will reduce the freeze count by 1 and real thawing happens when the count reaches 0.

`shell` : | A AnjutaShell interface.
`error` : | Error propagation object.

### anjuta_shell_thaw ()

    void                anjuta_shell_thaw                   (AnjutaShell *shell,
                                                             GError **error);

Reduces the freeze count by one and performs pending widget additions when the count reaches 0.

`shell` : | A AnjutaShell interface.
`error` : | Error propagation object.

### anjuta_shell_add_widget ()

    void                anjuta_shell_add_widget             (AnjutaShell *shell,
                                                             GtkWidget *widget,
                                                             const char *name,
                                                             const char *title,
                                                             const char *stock_id,
                                                             AnjutaShellPlacement placement,
                                                             GError **error);

Adds `widget` in the shell. The `placement` tells where the widget should appear, but generally it will be overridden by the container (dock, notebook, GtkContainer etc.) saved layout.

`shell` : | A AnjutaShell interface.
`widget` : | Then widget to add
`name` : | Name of the widget. None translated string used to identify it in the shell.
`title` : | Translated string which is displayed along side the widget when required (eg. as window title or notebook tab label).
`stock_id` : | Icon stock ID. Could be null.
`placement` : | Placement of the widget in shell.
`error` : | Error propagation object.

### anjuta_shell_add_widget_full ()

    void                anjuta_shell_add_widget_full        (AnjutaShell *shell,
                                                             GtkWidget *widget,
                                                             const char *name,
                                                             const char *title,
                                                             const char *stock_id,
                                                             AnjutaShellPlacement placement,
                                                             gboolean locked,
                                                             GError **error);

Adds `widget` in the shell. The `placement` tells where the widget should appear, but generally it will be overridden by the container (dock, notebook, GtkContainer etc.) saved layout.

Normally just use `anjuta_shell_add_widget()` because you do not use locking.

`shell` : | A AnjutaShell interface.
`widget` : | Then widget to add
`name` : | Name of the widget. None translated string used to identify it in the shell.
`title` : | Translated string which is displayed along side the widget when required (eg. as window title or notebook tab label).
`stock_id` : | Icon stock ID. Could be null.
`placement` : | Placement of the widget in shell.
`locked` : | Whether to lock that widget (do not use this, it's only useful to some stock plugins
`error` : | Error propagation object.

### anjuta_shell_add_widget_custom ()

    void                anjuta_shell_add_widget_custom      (AnjutaShell *shell,
                                                             GtkWidget *widget,
                                                             const char *name,
                                                             const char *title,
                                                             const char *stock_id,
                                                             GtkWidget *label,
                                                             AnjutaShellPlacement placement,
                                                             GError **error);

Adds `widget` in the shell. The `placement` tells where the widget should appear, but generally it will be overridden by the container (dock, notebook, GtkContainer etc.) saved layout.

Using this method you can pass a custom widget as label.

`shell` : | A AnjutaShell interface.
`widget` : | Then widget to add
`name` : | Name of the widget. None translated string used to identify it in the shell.
`title` : | title of the widget (translated)
`stock_id` : | Icon stock ID. Could be null.
`label` : | Label widget to use
`placement` : | Placement of the widget in shell.
`error` : | Error propagation object.

### anjuta_shell_remove_widget ()

    void                anjuta_shell_remove_widget          (AnjutaShell *shell,
                                                             GtkWidget *widget,
                                                             GError **error);

Removes the widget from shell. The widget should have been added before with anjuta_shell_add_widget.

`shell` : | A AnjutaShell interface
`widget` : | The widget to remove
`error` : | Error propagation object

### anjuta_shell_present_widget ()

    void                anjuta_shell_present_widget         (AnjutaShell *shell,
                                                             GtkWidget *widget,
                                                             GError **error);

Make sure the widget is visible to user. If the widget is hidden, it will be shown. If it is not visible to user, it will be made visible.

`shell` : | A AnjutaShell interface
`widget` : | The widget to present
`error` : | Error propagation object

### anjuta_shell_add_value ()

    void                anjuta_shell_add_value              (AnjutaShell *shell,
                                                             const char *name,
                                                             const GValue *value,
                                                             GError **error);

Sets a value in the shell with the given name. Any previous value will be overridden. "value_added" signal will be emitted. Objects connecting to this signal can then update their data according to the new value.

`shell` : | A AnjutaShell interface
`name` : | Name of the value
`value` : | Value to add
`error` : | Error propagation object

### anjuta_shell_add_valist ()

    void                anjuta_shell_add_valist             (AnjutaShell *shell,
                                                             const char *first_name,
                                                             GType first_type,
                                                             va_list var_args);

Adds a valist of values in the shell. The valist should be in the order - value1, name2, type2, value2,... "value_added" signal will be emitted for each of the value.

`shell` : | A AnjutaShell interface
`first_name` : | First value name
`first_type` : | First value type
`var_args` : | First value, Second value name, Second value type ....

### anjuta_shell_add ()

    void                anjuta_shell_add                    (AnjutaShell *shell,
                                                             const char *first_name,
                                                             GType first_type,
                                                             ...);

Adds a list of values in the shell. The list should be NULL terminated and should be in the order - name1, type1, value1, name2, type2, value2, ..., NULL. "value_added" signal will be emitted for each of the value.

`shell` : | A AnjutaShell interface
`first_name` : | First value name
`first_type` : | First value type
`...` : | First value, Second value name, Second value type .... NULL

### anjuta_shell_get_value ()

    void                anjuta_shell_get_value              (AnjutaShell *shell,
                                                             const char *name,
                                                             GValue *value,
                                                             GError **error);

Gets a value from the shell with the given name. The value will be set in the passed value pointer.

`shell` : | A AnjutaShell interface
`name` : | Name of the value to get
`value` : | Value to get
`error` : | Error propagation object

### anjuta_shell_get_valist ()

    void                anjuta_shell_get_valist             (AnjutaShell *shell,
                                                             const char *first_name,
                                                             GType first_type,
                                                             va_list var_args);

Gets a valist of values from the shell. The valist should be in the order - value1, name2, type2, value2,...

`shell` : | A AnjutaShell interface
`first_name` : | First value name
`first_type` : | First value type
`var_args` : | First value holder, Second value name, Second value type ....

### anjuta_shell_get ()

    void                anjuta_shell_get                    (AnjutaShell *shell,
                                                             const char *first_name,
                                                             GType first_type,
                                                             ...);

Gets a list of values in the shell. The list should be NULL terminated and should be in the order - name1, type1, value1, name2, type2, value2, ..., NULL.

`shell` : | A AnjutaShell interface
`first_name` : | First value name
`first_type` : | First value type
`...` : | First value holder, Second value name, Second value type .... NULL

### anjuta_shell_remove_value ()

    void                anjuta_shell_remove_value           (AnjutaShell *shell,
                                                             const char *name,
                                                             GError **error);

Removes a value from the shell with the given name. "value_removed" signal will be emitted. Objects connecting to this signal can then update their data/internal-state accordingly.

`shell` : | A AnjutaShell interface
`name` : | Name of the value to remove
`error` : | Error propagation object

### anjuta_shell_get_object ()

    GObject *           anjuta_shell_get_object             (AnjutaShell *shell,
                                                             const gchar *iface_name,
                                                             GError **error);

Searches the currently available plugins to find the one which implements the given interface as primary interface and returns it. If the plugin is not yet loaded, it will be loaded and activated. The returned object is garanteed to be an implementor of the interface (as exported by the plugin metafile). It only searches from the pool of plugin objects loaded in this shell and can only search by primary interface. If there are more objects implementing this primary interface, user might be prompted to select one from them (and might give the option to use it as default for future queries). A typical usage of this function is:

    GObject *docman =
        anjuta_plugins_get_object (shell, "IAnjutaDocumentManager", error);

Notice that this function takes the interface name string as string, unlike `anjuta_plugins_get_interface()` which takes the type directly.

`shell` : | A AnjutaShell interface
`iface_name` : | The interface implemented by the object to be found
`error` : | Error propagation.
Returns : | A plugin object implementing the primary interface or NULL.

### anjuta_shell_session_save ()

    void                anjuta_shell_session_save           (AnjutaShell *shell,
                                                             const gchar *session_directory,
                                                             GError **error);

`shell` : |
`session_directory` : |
`error` : |

### anjuta_shell_session_load ()

    void                anjuta_shell_session_load           (AnjutaShell *shell,
                                                             const gchar *session_directory,
                                                             GError **error);

`shell` : |
`session_directory` : |
`error` : |

### anjuta_shell_save_prompt ()

    void                anjuta_shell_save_prompt            (AnjutaShell *shell,
                                                             AnjutaSavePrompt *prompt,
                                                             GError **error);

`shell` : |
`prompt` : |
`error` : |

### anjuta_shell_notify_exit ()

    void                anjuta_shell_notify_exit            (AnjutaShell *shell,
                                                             GError **error);

`shell` : |
`error` : |

### anjuta_shell_get_interface()

    #define             anjuta_shell_get_interface(shell, iface_type, error)

Equivalent to `anjuta_shell_get_object()`, but additionally typecasts returned object to the interface type. It also takes interface type directly. A usage of this function is:

    IAnjutaDocumentManager *docman =
        anjuta_shell_get_interface (shell, IAnjutaDocumentManager, error);

`shell` : | A AnjutaShell object
`iface_type` : | The interface type implemented by the object to be found
`error` : | Error propagation object.

## Signal Details

### The `"exiting"` signal

    void                user_function                      (AnjutaShell *anjutashell,
                                                            gpointer     user_data)        : Run Last

`anjutashell` : | the object which received the signal.
`user_data` : | user data set when the signal handler was connected.

### The `"load-session"` signal

    void                user_function                      (AnjutaShell *anjutashell,
                                                            gint         arg1,
                                                            GObject     *arg2,
                                                            gpointer     user_data)        : Run Last

`anjutashell` : | the object which received the signal.
`arg1` : |
`arg2` : |
`user_data` : | user data set when the signal handler was connected.

### The `"save-prompt"` signal

    void                user_function                      (AnjutaShell *anjutashell,
                                                            GObject     *arg1,
                                                            gpointer     user_data)        : Run Last

`anjutashell` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.

### The `"save-session"` signal

    void                user_function                      (AnjutaShell *anjutashell,
                                                            gint         arg1,
                                                            GObject     *arg2,
                                                            gpointer     user_data)        : Run Last

`anjutashell` : | the object which received the signal.
`arg1` : |
`arg2` : |
`user_data` : | user data set when the signal handler was connected.

### The `"value-added"` signal

    void                user_function                      (AnjutaShell *anjutashell,
                                                            gchar       *arg1,
                                                            GValue      *arg2,
                                                            gpointer     user_data)        : Run Last

`anjutashell` : | the object which received the signal.
`arg1` : |
`arg2` : |
`user_data` : | user data set when the signal handler was connected.

### The `"value-removed"` signal

    void                user_function                      (AnjutaShell *anjutashell,
                                                            gchar       *arg1,
                                                            gpointer     user_data)        : Run Last

`anjutashell` : | the object which received the signal.
`arg1` : |
`user_data` : | user data set when the signal handler was connected.