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, #AnjutaSyncCommand
  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 or
  43  * #AnjutaSyncCommand, which runs commands synchronously.
  44  *
  45  * These classes determine how ::run is called and how signals are emitted.
  46  * ::run is responsible for actually doing the work of the command. It is the
  47  * responsiblity of the command object that does a certain task to implement
  48  * ::run to do its job. Everything else is normally implemented by its parent
  49  * classes at this point
  50  *
  51  * For an example of how to use #AnjutaCommand, see the Subversion and Git
  52  * plugins.
  53  */
  54
  55 struct _AnjutaCommandPriv
  56 {
  57         gboolean running;
  58         gchar *error_message;
  59 };
  60
  61 enum
  62 {
  63         DATA_ARRIVED,
  64         COMMAND_STARTED,
  65         COMMAND_FINISHED,
  66         PROGRESS,
  67
  68         LAST_SIGNAL
  69 };
  70
  71
  72 static guint anjuta_command_signals[LAST_SIGNAL] = { 0 };
  73
  74 G_DEFINE_TYPE (AnjutaCommand, anjuta_command, G_TYPE_OBJECT);
  75
  76 static void
  77 anjuta_command_init (AnjutaCommand *self)
  78 {
  79         self->priv = g_new0 (AnjutaCommandPriv, 1);
  80 }
  81
  82 static void
  83 anjuta_command_finalize (GObject *object)
  84 {
  85         AnjutaCommand *self;
  86
  87         self = ANJUTA_COMMAND (object);
  88
  89         g_free (self->priv->error_message);
  90         g_free (self->priv);
  91
  92         G_OBJECT_CLASS (anjuta_command_parent_class)->finalize (object);
  93 }
  94
  95 static gboolean
  96 start_automatic_monitor (AnjutaCommand *self)
  97 {
  98         return FALSE;
  99 }
 100
 101 static void
 102 stop_automatic_monitor (AnjutaCommand *self)
 103 {
 104 }
 105
 106 static void
 107 data_arrived (AnjutaCommand *command)
 108 {
 109 }
 110
 111 static void
 112 command_started (AnjutaCommand *command)
 113 {
 114         command->priv->running = TRUE;
 115 }
 116
 117 static void
 118 command_finished (AnjutaCommand *command, guint return_code)
 119 {
 120         command->priv->running = FALSE;
 121 }
 122
 123 static void
 124 progress (AnjutaCommand *command, gfloat progress)
 125 {
 126 }
 127
 128 static void
 129 anjuta_command_class_init (AnjutaCommandClass *klass)
 130 {
 131         GObjectClass* object_class = G_OBJECT_CLASS (klass);
 132
 133         object_class->finalize = anjuta_command_finalize;
 134
 135         klass->run = NULL;
 136         klass->start = NULL;
 137         klass->cancel = NULL;
 138         klass->notify_data_arrived = NULL;
 139         klass->notify_complete = NULL;
 140         klass->notify_progress = NULL;
 141         klass->set_error_message = anjuta_command_set_error_message;
 142         klass->get_error_message = anjuta_command_get_error_message;
 143         klass->start_automatic_monitor = start_automatic_monitor;
 144         klass->stop_automatic_monitor = stop_automatic_monitor;
 145         klass->data_arrived = data_arrived;
 146         klass->command_started = command_started;
 147         klass->command_finished = command_finished;
 148         klass->progress = progress;
 149
 150         /**
 151          * AnjutaCommand::data-arrived:
 152          * @command: Command
 153          *
 154          * Notifies clients that the command has processed data that is ready to
 155          * be used.
 156          */
 157         anjuta_command_signals[DATA_ARRIVED] =
 158                 g_signal_new ("data-arrived",
 159                               G_OBJECT_CLASS_TYPE (klass),
 160                               G_SIGNAL_RUN_LAST,
 161                               G_STRUCT_OFFSET (AnjutaCommandClass, data_arrived),
 162                               NULL, NULL,
 163                               g_cclosure_marshal_VOID__VOID,
 164                               G_TYPE_NONE,
 165                                           0);
 166
 167         /**
 168          * AnjuaCommand::command-started:
 169          * @command: Command
 170          *
 171          * Indicates that a command has begun executing. This signal is intended to
 172          * be used for commands that start themselves automatically.
 173          *
 174          * <note>
 175          *  <para>
 176          *        Sublasses that override the method for this signal should chain up to
 177          *        the parent implementation to ensure proper handling of running/not
 178          *        running states.
 179          *      </para>
 180          * </note>
 181          */
 182         anjuta_command_signals[COMMAND_STARTED] =
 183                 g_signal_new ("command-started",
 184                               G_OBJECT_CLASS_TYPE (klass),
 185                               G_SIGNAL_RUN_FIRST,
 186                               G_STRUCT_OFFSET (AnjutaCommandClass, command_started),
 187                               NULL, NULL,
 188                               g_cclosure_marshal_VOID__VOID,
 189                               G_TYPE_NONE,
 190                               0);
 191
 192         /**
 193          * AnjutaCommand::command-finished:
 194          * @command: Command
 195          * @return_code: The return code of the finished commmand
 196          *
 197          * Indicates that the command has completed. Clients should at least handle
 198          * this signal to unref the command object.
 199          *
 200          * <note>
 201          *  <para>
 202          *        Sublasses that override the method for this signal should chain up to
 203          *        the parent implementation to ensure proper handling of running/not
 204          *        running states.
 205          *      </para>
 206          * </note>
 207          */
 208         anjuta_command_signals[COMMAND_FINISHED] =
 209                 g_signal_new ("command-finished",
 210                               G_OBJECT_CLASS_TYPE (klass),
 211                               G_SIGNAL_RUN_FIRST,
 212                               G_STRUCT_OFFSET (AnjutaCommandClass, command_finished),
 213                               NULL, NULL,
 214                               g_cclosure_marshal_VOID__UINT ,
 215                               G_TYPE_NONE, 1,
 216                               G_TYPE_UINT);
 217
 218
 219         /**
 220          * AnjutaCommand::progress:
 221          * @command: Command
 222          * @progress: Fraction of the command's task that is complete, between 0.0
 223          *                        and 1.0, inclusive.
 224          *
 225          * Notifies clients of changes in progress during command execution.
 226          */
 227         anjuta_command_signals[PROGRESS] =
 228                 g_signal_new ("progress",
 229                               G_OBJECT_CLASS_TYPE (klass),
 230                               G_SIGNAL_RUN_FIRST,
 231                               G_STRUCT_OFFSET (AnjutaCommandClass, progress),
 232                               NULL, NULL,
 233                               g_cclosure_marshal_VOID__FLOAT ,
 234                               G_TYPE_NONE, 1,
 235                               G_TYPE_FLOAT);
 236 }
 237
 238 /**
 239  * anjuta_command_start:
 240  * @self: Command object to start
 241  *
 242  * Starts a command. Client code can handle data from the command by connecting
 243  * to the ::data-arrived signal.
 244  *
 245  * #AnjutaCommand subclasses should override this method to determine how they
 246  * call ::run, which actually does the command's legwork.
 247  */
 248 void
 249 anjuta_command_start (AnjutaCommand *self)
 250 {
 251         if (!self->priv->running)
 252         {
 253                 g_signal_emit_by_name (self, "command-started");
 254
 255                 ANJUTA_COMMAND_GET_CLASS (self)->start (self);
 256         }
 257 }
 258
 259 /**
 260  * anjuta_command_cancel:
 261  * @self: Command object.
 262  *
 263  * Cancels a running command.
 264  */
 265 void
 266 anjuta_command_cancel (AnjutaCommand *self)
 267 {
 268         ANJUTA_COMMAND_GET_CLASS (self)->cancel (self);
 269 }
 270
 271 /**
 272  * anjuta_command_notify_data_arrived:
 273  * @self: Command object.
 274  *
 275  * Used by base classes derived from #AnjutaCommand to emit the ::data-arrived
 276  * signal. This method should be used by both base command classes and
 277  * non-base classes as appropriate.
 278  */
 279 void
 280 anjuta_command_notify_data_arrived (AnjutaCommand *self)
 281 {
 282         ANJUTA_COMMAND_GET_CLASS (self)->notify_data_arrived (self);
 283 }
 284
 285 /**
 286  * anjuta_command_notify_complete:
 287  * @self: Command object
 288  * @return_code: The returned code that is passed to the notify callback
 289  *
 290  * Used by base classes derived from #AnjutaCommand to emit the
 291  * ::command-finished signal. This method should not be used by client code or
 292  * #AnjutaCommand objects that are not base classes.
 293  */
 294 void
 295 anjuta_command_notify_complete (AnjutaCommand *self, guint return_code)
 296 {
 297         ANJUTA_COMMAND_GET_CLASS (self)->notify_complete (self, return_code);
 298 }
 299
 300 /**
 301  * anjuta_command_notify_progress:
 302  * @self: Command object.
 303  * @progress: The of the command that is passed to the notify callback
 304  *
 305  * Emits the ::progress signal. Can be used by both base classes and
 306  * commands as needed.
 307  */
 308 void
 309 anjuta_command_notify_progress (AnjutaCommand *self, gfloat progress)
 310 {
 311         ANJUTA_COMMAND_GET_CLASS (self)->notify_progress (self, progress);
 312 }
 313
 314 /**
 315  * anjuta_command_is_running:
 316  * @self: Command object.
 317  *
 318  * Return value: %TRUE if the command is currently running; %FALSE otherwise.
 319  */
 320 gboolean
 321 anjuta_command_is_running (AnjutaCommand *self)
 322 {
 323         return self->priv->running;
 324 }
 325
 326 /**
 327  * anjuta_command_set_error_message:
 328  * @self: Command object.
 329  * @error_message: Error message.
 330  *
 331  * Command objects use this to set error messages when they encounter some kind
 332  * of failure.
 333  */
 334 void
 335 anjuta_command_set_error_message (AnjutaCommand *self, const gchar *error_message)
 336 {
 337         g_free (self->priv->error_message);
 338
 339         self->priv->error_message = g_strdup (error_message);
 340 }
 341
 342 /**
 343  * anjuta_command_get_error_message:
 344  * @self: Command object.
 345  *
 346  * Get the error message from the command, if there is one. This method is
 347  * normally used from a ::command-finished handler to report errors to the user
 348  * when a command finishes.
 349  *
 350  * Return value: (transfer full) (allow-none): Error message string that must
 351  * be freed when no longer needed. If no error is set, return %NULL.
 352  */
 353 gchar *
 354 anjuta_command_get_error_message (AnjutaCommand *self)
 355 {
 356         return g_strdup (self->priv->error_message);
 357 }
 358
 359 /**
 360  * anjuta_command_start_automatic_monitor:
 361  * @self: Command object.
 362  *
 363  * Sets up any monitoring needed for commands that should start themselves
 364  * automatically in response to some event.
 365  *
 366  * Return value: %TRUE if automatic starting is supported by the command and
 367  * no errors were encountered; %FALSE if automatic starting is unsupported or on
 368  * error.
 369  */
 370 gboolean
 371 anjuta_command_start_automatic_monitor (AnjutaCommand *self)
 372 {
 373         return ANJUTA_COMMAND_GET_CLASS (self)->start_automatic_monitor (self);
 374 }
 375
 376 /**
 377  * anjuta_command_stop_automatic_monitor:
 378  * @self: Command object.
 379  *
 380  * Stops automatic monitoring for self executing commands. For commands that
 381  * do not support self-starting, this function does nothing.
 382  */
 383 void
 384 anjuta_command_stop_automatic_monitor (AnjutaCommand *self)
 385 {
 386         ANJUTA_COMMAND_GET_CLASS (self)->stop_automatic_monitor (self);
 387 }