## AnjutaCommand

AnjutaCommand — System for creating objects that provide a standard interface to external components (libraries, processes, etc.)

## Synopsis

                        AnjutaCommandClass;
                        AnjutaCommand;
                        AnjutaCommandPriv;
    void                anjuta_command_start                (AnjutaCommand *self);
    void                anjuta_command_cancel               (AnjutaCommand *self);
    void                anjuta_command_notify_data_arrived  (AnjutaCommand *self);
    void                anjuta_command_notify_complete      (AnjutaCommand *self,
                                                             guint return_code);
    void                anjuta_command_notify_progress      (AnjutaCommand *self,
                                                             gfloat progress);
    gboolean            anjuta_command_is_running           (AnjutaCommand *self);
    void                anjuta_command_set_error_message    (AnjutaCommand *self,
                                                             const gchar *error_message);
    gchar *             anjuta_command_get_error_message    (AnjutaCommand *self);
    gboolean            anjuta_command_start_automatic_monitor
                                                            (AnjutaCommand *self);
    void                anjuta_command_stop_automatic_monitor
                                                            (AnjutaCommand *self);

## Object Hierarchy

      GObject
       +----AnjutaCommand
             +----AnjutaAsyncCommand
             +----AnjutaSyncCommand

## Signals

      "command-finished"                               : Run First
      "command-started"                                : Run First
      "data-arrived"                                   : Run Last
      "progress"                                       : Run First

## Description

AnjutaCommand is the base class for objects that are designed to provide a layer of abstraction between UI code and some other component, like a library or child process. AnjutaCommand provides a simple and consistent interface for plugins to interact with these components without needing to concern themselves with the exact details of how these components work.

To create command objects, plugins derive them from an AnjutaCommand subclass like AnjutaAsyncCommand, which runs commands in another thread or AnjutaSyncCommand, which runs commands synchronously.

These classes determine how ::run is called and how signals are emitted. ::run is responsible for actually doing the work of the command. It is the responsiblity of the command object that does a certain task to implement ::run to do its job. Everything else is normally implemented by its parent classes at this point

For an example of how to use AnjutaCommand, see the Subversion and Git plugins.

## Details

### AnjutaCommandClass

    typedef struct {
    	GObjectClass parent_class;

    	/* Virtual Methods */
    	guint (*run) (AnjutaCommand *self);
    	void (*start) (AnjutaCommand *self);
    	void (*cancel) (AnjutaCommand *self);
    	void (*notify_data_arrived) (AnjutaCommand *self);
    	void (*notify_complete) (AnjutaCommand *self, guint return_code);
    	void (*notify_progress) (AnjutaCommand *self, gfloat progress);
    	void (*set_error_message) (AnjutaCommand *self, const gchar *error_message);
    	gchar * (*get_error_message) (AnjutaCommand *self);
    	gboolean (*start_automatic_monitor) (AnjutaCommand *self);
    	void (*stop_automatic_monitor) (AnjutaCommand *self);

    	/* Signals */
    	void (*data_arrived) (AnjutaCommand *command);
    	void (*command_started) (AnjutaCommand *command);
    	void (*command_finished) (AnjutaCommand *command, guint return_code);
    	void (*progress) (AnjutaCommand *command, gfloat progress);
    } AnjutaCommandClass;

### AnjutaCommand

    typedef struct _AnjutaCommand AnjutaCommand;

### AnjutaCommandPriv

    typedef struct _AnjutaCommandPriv AnjutaCommandPriv;

### anjuta_command_start ()

    void                anjuta_command_start                (AnjutaCommand *self);

Starts a command. Client code can handle data from the command by connecting to the ::data-arrived signal.

AnjutaCommand subclasses should override this method to determine how they call ::run, which actually does the command's legwork.

`self` : | Command object to start

### anjuta_command_cancel ()

    void                anjuta_command_cancel               (AnjutaCommand *self);

Cancels a running command.

`self` : | Command object.

### anjuta_command_notify_data_arrived ()

    void                anjuta_command_notify_data_arrived  (AnjutaCommand *self);

Used by base classes derived from AnjutaCommand to emit the ::data-arrived signal. This method should be used by both base command classes and non-base classes as appropriate.

`self` : | Command object.

### anjuta_command_notify_complete ()

    void                anjuta_command_notify_complete      (AnjutaCommand *self,
                                                             guint return_code);

Used by base classes derived from AnjutaCommand to emit the ::command-finished signal. This method should not be used by client code or AnjutaCommand objects that are not base classes.

`self` : | Command object
`return_code` : | The returned code that is passed to the notify callback

### anjuta_command_notify_progress ()

    void                anjuta_command_notify_progress      (AnjutaCommand *self,
                                                             gfloat progress);

Emits the ::progress signal. Can be used by both base classes and commands as needed.

`self` : | Command object.
`progress` : | The of the command that is passed to the notify callback

### anjuta_command_is_running ()

    gboolean            anjuta_command_is_running           (AnjutaCommand *self);

`self` : | Command object.
Returns : | `TRUE` if the command is currently running; `FALSE` otherwise.

### anjuta_command_set_error_message ()

    void                anjuta_command_set_error_message    (AnjutaCommand *self,
                                                             const gchar *error_message);

Command objects use this to set error messages when they encounter some kind of failure.

`self` : | Command object.
`error_message` : | Error message.

### anjuta_command_get_error_message ()

    gchar *             anjuta_command_get_error_message    (AnjutaCommand *self);

Get the error message from the command, if there is one. This method is normally used from a ::command-finished handler to report errors to the user when a command finishes.

`self` : | Command object.
Returns : | Error message string that must be freed when no longer needed. If no error is set, return `NULL`.

### anjuta_command_start_automatic_monitor ()

    gboolean            anjuta_command_start_automatic_monitor
                                                            (AnjutaCommand *self);

Sets up any monitoring needed for commands that should start themselves automatically in response to some event.

`self` : | Command object.
Returns : | `TRUE` if automatic starting is supported by the command and no errors were encountered; `FALSE` if automatic starting is unsupported or on error.

### anjuta_command_stop_automatic_monitor ()

    void                anjuta_command_stop_automatic_monitor
                                                            (AnjutaCommand *self);

Stops automatic monitoring for self executing commands. For commands that do not support self-starting, this function does nothing.

`self` : | Command object.

## Signal Details

### The `"command-finished"` signal

    void                user_function                      (AnjutaCommand *command,
                                                            guint          return_code,
                                                            gpointer       user_data)        : Run First

Indicates that the command has completed. Clients should at least handle this signal to unref the command object.

### Note

Sublasses that override the method for this signal should chain up to the parent implementation to ensure proper handling of running/not running states.

`command` : | Command
`return_code` : | The return code of the finished commmand
`user_data` : | user data set when the signal handler was connected.

### The `"command-started"` signal

    void                user_function                      (AnjutaCommand *anjutacommand,
                                                            gpointer       user_data)          : Run First

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

### The `"data-arrived"` signal

    void                user_function                      (AnjutaCommand *command,
                                                            gpointer       user_data)      : Run Last

Notifies clients that the command has processed data that is ready to be used.

`command` : | Command
`user_data` : | user data set when the signal handler was connected.

### The `"progress"` signal

    void                user_function                      (AnjutaCommand *command,
                                                            gfloat         progress,
                                                            gpointer       user_data)      : Run First

Notifies clients of changes in progress during command execution.

`command` : | Command
`progress` : | Fraction of the command's task that is complete, between 0.0 and 1.0, inclusive.
`user_data` : | user data set when the signal handler was connected.

## See Also

AnjutaAsyncCommand, AnjutaSyncCommand `include` libanjuta/anjuta-command.h