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         PROGRESS,
  62
  63         LAST_SIGNAL
  64 };
  65
  66
  67 static guint anjuta_command_signals[LAST_SIGNAL] = { 0 };
  68
  69 G_DEFINE_TYPE (AnjutaCommand, anjuta_command, G_TYPE_OBJECT);
  70
  71 static void
  72 anjuta_command_init (AnjutaCommand *self)
  73 {
  74         self->priv = g_new0 (AnjutaCommandPriv, 1);
  75 }
  76
  77 static void
  78 anjuta_command_finalize (GObject *object)
  79 {
  80         AnjutaCommand *self;
  81
  82         self = ANJUTA_COMMAND (object);
  83
  84         g_free (self->priv->error_message);
  85         g_free (self->priv);
  86
  87         G_OBJECT_CLASS (anjuta_command_parent_class)->finalize (object);
  88 }
  89
  90 static void
  91 anjuta_command_class_init (AnjutaCommandClass *klass)
  92 {
  93         GObjectClass* object_class = G_OBJECT_CLASS (klass);
  94
  95         object_class->finalize = anjuta_command_finalize;
  96
  97         klass->run = NULL;
  98         klass->start = NULL;
  99         klass->notify_data_arrived = NULL;
 100         klass->notify_complete = NULL;
 101         klass->notify_progress = NULL;
 102         klass->set_error_message = anjuta_command_set_error_message;
 103         klass->get_error_message = anjuta_command_get_error_message;
 104         klass->progress = NULL;
 105
 106         /**
 107          * AnjutaCommand::data-arrived:
 108          * @command: Command
 109          *
 110          * Notifies clients that the command has processed data that is ready to
 111          * be used.
 112          */
 113         anjuta_command_signals[DATA_ARRIVED] =
 114                 g_signal_new ("data-arrived",
 115                               G_OBJECT_CLASS_TYPE (klass),
 116                               G_SIGNAL_RUN_FIRST,
 117                               0,
 118                               NULL, NULL,
 119                               g_cclosure_marshal_VOID__VOID,
 120                               G_TYPE_NONE,
 121                                           0);
 122
 123         /**
 124          * AnjutaCommand::command-finished:
 125          * @command: Command
 126          * @return_code: The return code of the finished commmand
 127          *
 128          * Indicates that the command has completed. Clients should at least handle
 129          * this signal to unref the command object.
 130          */
 131         anjuta_command_signals[COMMAND_FINISHED] =
 132                 g_signal_new ("command-finished",
 133                               G_OBJECT_CLASS_TYPE (klass),
 134                               G_SIGNAL_RUN_FIRST,
 135                               0,
 136                               NULL, NULL,
 137                               g_cclosure_marshal_VOID__UINT ,
 138                               G_TYPE_NONE, 1,
 139                               G_TYPE_UINT);
 140
 141
 142         /**
 143          * AnjutaCommand::progress:
 144          * @command: Command
 145          * @progress: Fraction of the command's task that is complete, between 0.0
 146          *                        and 1.0, inclusive.
 147          *
 148          * Notifies clients of changes in progress during command execution.
 149          */
 150         anjuta_command_signals[PROGRESS] =
 151                 g_signal_new ("progress",
 152                               G_OBJECT_CLASS_TYPE (klass),
 153                               G_SIGNAL_RUN_FIRST,
 154                               G_STRUCT_OFFSET (AnjutaCommandClass, progress),
 155                               NULL, NULL,
 156                               g_cclosure_marshal_VOID__FLOAT ,
 157                               G_TYPE_NONE, 1,
 158                               G_TYPE_FLOAT);
 159 }
 160
 161 /**
 162  * anjuta_command_start:
 163  * @self: Command object to start
 164  *
 165  * Starts a command. Client code can handle data from the command by connecting
 166  * to the ::data-arrived signal.
 167  *
 168  * #AnjutaCommand subclasses should override this method to determine how they
 169  * call ::run, which actually does the command's legwork.
 170  */
 171 void
 172 anjuta_command_start (AnjutaCommand *self)
 173 {
 174         ANJUTA_COMMAND_GET_CLASS (self)->start (self);
 175 }
 176
 177
 178 /**
 179  * anjuta_command_notify_data_arrived:
 180  * @self: Command object.
 181  *
 182  * Used by base classes derived from #AnjutaCommand to emit the ::data-arrived
 183  * signal. This method should not be used by client code or #AnjutaCommand
 184  * objects that are not base classes.
 185  */
 186 void
 187 anjuta_command_notify_data_arrived (AnjutaCommand *self)
 188 {
 189         ANJUTA_COMMAND_GET_CLASS (self)->notify_data_arrived (self);
 190 }
 191
 192 /**
 193  * anjuta_command_notify_complete:
 194  * @self: Command object.
 195  *
 196  * Used by base classes derived from #AnjutaCommand to emit the
 197  * ::command-finished signal. This method should not be used by client code or
 198  * #AnjutaCommand objects that are not base classes.
 199  */
 200 void
 201 anjuta_command_notify_complete (AnjutaCommand *self, guint return_code)
 202 {
 203         ANJUTA_COMMAND_GET_CLASS (self)->notify_complete (self, return_code);
 204 }
 205
 206 /**
 207  * anjuta_command_notify_progress:
 208  * @self: Command object.
 209  *
 210  * Emits the ::progress signal. Can be used by both base classes and
 211  * commands as needed.
 212  */
 213 void
 214 anjuta_command_notify_progress (AnjutaCommand *self, gfloat progress)
 215 {
 216         ANJUTA_COMMAND_GET_CLASS (self)->notify_progress (self, progress);
 217 }
 218
 219 /**
 220  * anjuta_command_set_error_message:
 221  * @self: Command object.
 222  * @error_message: Error message.
 223  *
 224  * Command objects use this to set error messages when they encounter some kind
 225  * of failure.
 226  */
 227 void
 228 anjuta_command_set_error_message (AnjutaCommand *self, gchar *error_message)
 229 {
 230         if (self->priv->error_message)
 231                 g_free (error_message);
 232
 233         self->priv->error_message = g_strdup (error_message);
 234 }
 235
 236 /**
 237  * anjuta_command_get_error_message:
 238  * @self: Command object.
 239  * @error_message: Error message.
 240  *
 241  * Get the error message from the command, if there is one. This method is
 242  * normally used from a ::command-finished handler to report errors to the user
 243  * when a command finishes.
 244  *
 245  * Return value: Error message string that must be freed when no longer needed.
 246  * If no error is set, return %NULL.
 247  */
 248 gchar *
 249 anjuta_command_get_error_message (AnjutaCommand *self)
 250 {
 251         return g_strdup (self->priv->error_message);
 252 }