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