libanjuta/anjuta-command.c

   1 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 4; tab-width: 4 -*- */
   2 /*
   3  * anjuta
   4  * Copyright (C) James Liggett 2007 <jrliggett@cox.net>
   5  *
   6  * anjuta is free software.
   7  *
   8  * You may redistribute it and/or modify it under the terms of the
   9  * GNU General Public License, as published by the Free Software
  10  * Foundation; either version 2 of the License, or (at your option)
  11  * any later version.
  12  *
  13  * anjuta is distributed in the hope that it will be useful,
  14  * but WITHOUT ANY WARRANTY; without even the implied warranty of
  15  * MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.
  16  * See the GNU General Public License for more details.
  17  *
  18  * You should have received a copy of the GNU General Public License
  19  * along with anjuta.  If not, write to:
  20  *      The Free Software Foundation, Inc.,
  21  *      51 Franklin Street, Fifth Floor
  22  *      Boston, MA  02110-1301, USA.
  23  */
  24
  25 #include "anjuta-command.h"
  26
  27 /**
  28  * SECTION: anjuta-command
  29  * @short_description: System for creating objects that provide a standard
  30  *                                         interface to external components (libraries, processes,
  31  *                                         etc.)
  32  * @see_also: #AnjutaAsyncCommand
  33  * @include libanjuta/anjuta-command.h
  34  *
  35  * #AnjutaCommand is the base class for objects that are designed to provide
  36  * a layer of abstraction between UI code and some other component, like a
  37  * library or child process. AnjutaCommand provides a simple and consistent
  38  * interface for plugins to interact with these components without needing
  39  * to concern themselves with the exact details of how these components work.
  40  *
  41  * To create command objects, plugins derive them from an #AnjutaCommand
  42  * subclass like #AnjutaAsyncCommand, which runs commands in another thread.
  43  * These classes determine how ::run is called and how signals are emitted.
  44  * ::run is responsible for actually doing the work of the command. It is the
  45  * responsiblity of the command object that does a certain task to implement
  46  * ::run to do its job. Everything else is normally implemented by its parent
  47  * classes at this point
  48  *
  49  * For an example of how to use #AnjutaCommand, see the Subversion plugin.
  50  */
  51
  52 struct _AnjutaCommandPriv
  53 {
  54         gchar *error_message;
  55 };
  56
  57 enum
  58 {
  59         DATA_ARRIVED,
  60         COMMAND_FINISHED,
  61
  62         LAST_SIGNAL
  63 };
  64
  65
  66 static guint anjuta_command_signals[LAST_SIGNAL] = { 0 };
  67
  68 G_DEFINE_TYPE (AnjutaCommand, anjuta_command, G_TYPE_OBJECT);
  69
  70 static void
  71 anjuta_command_init (AnjutaCommand *self)
  72 {
  73         self->priv = g_new0 (AnjutaCommandPriv, 1);
  74 }
  75
  76 static void
  77 anjuta_command_finalize (GObject *object)
  78 {
  79         AnjutaCommand *self;
  80
  81         self = ANJUTA_COMMAND (object);
  82
  83         g_free (self->priv->error_message);
  84         g_free (self->priv);
  85
  86         G_OBJECT_CLASS (anjuta_command_parent_class)->finalize (object);
  87 }
  88
  89 static void
  90 anjuta_command_class_init (AnjutaCommandClass *klass)
  91 {
  92         GObjectClass* object_class = G_OBJECT_CLASS (klass);
  93
  94         object_class->finalize = anjuta_command_finalize;
  95
  96         klass->run = NULL;
  97         klass->start = NULL;
  98         klass->notify_data_arrived = NULL;
  99         klass->notify_complete = NULL;
 100         klass->set_error_message = anjuta_command_set_error_message;
 101         klass->get_error_message = anjuta_command_get_error_message;
 102
 103         /**
 104          * AnjutaCommand::data-arrived:
 105          * @command: Command
 106          *
 107          * Notifies clients that the command has processed data that is ready to
 108          * be used.
 109          */
 110         anjuta_command_signals[DATA_ARRIVED] =
 111                 g_signal_new ("data-arrived",
 112                               G_OBJECT_CLASS_TYPE (klass),
 113                               G_SIGNAL_RUN_FIRST,
 114                               0,
 115                               NULL, NULL,
 116                               g_cclosure_marshal_VOID__VOID,
 117                               G_TYPE_NONE,
 118                                           0);
 119
 120         /**
 121          * AnjutaCommand::command-finished:
 122          * @command: Command
 123          * @return_code: The return code of the finished commmand
 124          *
 125          * Indicates that the command has completed. Clients should at least handle
 126          * this signal to unref the command object.
 127          */
 128         anjuta_command_signals[COMMAND_FINISHED] =
 129                 g_signal_new ("command-finished",
 130                               G_OBJECT_CLASS_TYPE (klass),
 131                               G_SIGNAL_RUN_FIRST,
 132                               0,
 133                               NULL, NULL,
 134                               g_cclosure_marshal_VOID__UINT ,
 135                               G_TYPE_NONE, 1,
 136                               G_TYPE_UINT);
 137 }
 138
 139 /**
 140  * anjuta_command_start:
 141  * @self: Command object to start
 142  *
 143  * Starts a command. Client code can handle data from the command by connecting
 144  * to the ::data-arrived signal.
 145  *
 146  * #AnjutaCommand subclasses should override this method to determine how they
 147  * call ::run, which actually does the command's legwork.
 148  */
 149 void
 150 anjuta_command_start (AnjutaCommand *self)
 151 {
 152         ANJUTA_COMMAND_GET_CLASS (self)->start (self);
 153 }
 154
 155
 156 /**
 157  * anjuta_command_notify_data_arrived:
 158  * @self: Command object.
 159  *
 160  * Used by base classes derived from #AnjutaCommand to emit the ::data-arrived
 161  * signal. This method should not be used by client code or #AnjutaCommand
 162  * objects that are not base classes.
 163  */
 164 void
 165 anjuta_command_notify_data_arrived (AnjutaCommand *self)
 166 {
 167         ANJUTA_COMMAND_GET_CLASS (self)->notify_data_arrived (self);
 168 }
 169
 170 /**
 171  * anjuta_command_notify_complete:
 172  * @self: Command object.
 173  *
 174  * Used by base classes derived from #AnjutaCommand to emit the
 175  * ::command-finished signal. This method should not be used by client code or
 176  * #AnjutaCommand objects that are not base classes.
 177  */
 178 void
 179 anjuta_command_notify_complete (AnjutaCommand *self, guint return_code)
 180 {
 181         ANJUTA_COMMAND_GET_CLASS (self)->notify_complete (self, return_code);
 182 }
 183
 184 /**
 185  * anjuta_command_set_error_message:
 186  * @self: Command object.
 187  * @error_message: Error message.
 188  *
 189  * Command objects use this to set error messages when they encounter some kind
 190  * of failure.
 191  */
 192 void
 193 anjuta_command_set_error_message (AnjutaCommand *self, gchar *error_message)
 194 {
 195         if (self->priv->error_message)
 196                 g_free (error_message);
 197
 198         self->priv->error_message = g_strdup (error_message);
 199 }
 200
 201 /**
 202  * anjuta_command_get_error_message:
 203  * @self: Command object.
 204  * @error_message: Error message.
 205  *
 206  * Get the error message from the command, if there is one. This method is
 207  * normally used from a ::command-finished handler to report errors to the user
 208  * when a command finishes.
 209  *
 210  * Return value: Error message string that must be freed when no longer needed.
 211  * If no error is set, return %NULL.
 212  */
 213 gchar *
 214 anjuta_command_get_error_message (AnjutaCommand *self)
 215 {
 216         return g_strdup (self->priv->error_message);
 217 }