1 /* -*- Mode: C; indent-tabs-mode: t; c-basic-offset: 4; tab-width: 4 -*- */
4 * Copyright (C) James Liggett 2007 <jrliggett@cox.net>
6 * anjuta is free software.
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)
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.
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.
25 #include "anjuta-command.h"
28 * SECTION: anjuta-command
29 * @short_description: System for creating objects that provide a standard
30 * interface to external components (libraries, processes,
32 * @see_also: #AnjutaAsyncCommand
33 * @include libanjuta/anjuta-command.h
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.
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
49 * For an example of how to use #AnjutaCommand, see the Subversion plugin.
52 struct _AnjutaCommandPriv
67 static guint anjuta_command_signals
[LAST_SIGNAL
] = { 0 };
69 G_DEFINE_TYPE (AnjutaCommand
, anjuta_command
, G_TYPE_OBJECT
);
72 anjuta_command_init (AnjutaCommand
*self
)
74 self
->priv
= g_new0 (AnjutaCommandPriv
, 1);
78 anjuta_command_finalize (GObject
*object
)
82 self
= ANJUTA_COMMAND (object
);
84 g_free (self
->priv
->error_message
);
87 G_OBJECT_CLASS (anjuta_command_parent_class
)->finalize (object
);
91 anjuta_command_class_init (AnjutaCommandClass
*klass
)
93 GObjectClass
* object_class
= G_OBJECT_CLASS (klass
);
95 object_class
->finalize
= anjuta_command_finalize
;
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
;
107 * AnjutaCommand::data-arrived:
110 * Notifies clients that the command has processed data that is ready to
113 anjuta_command_signals
[DATA_ARRIVED
] =
114 g_signal_new ("data-arrived",
115 G_OBJECT_CLASS_TYPE (klass
),
119 g_cclosure_marshal_VOID__VOID
,
124 * AnjutaCommand::command-finished:
126 * @return_code: The return code of the finished commmand
128 * Indicates that the command has completed. Clients should at least handle
129 * this signal to unref the command object.
131 anjuta_command_signals
[COMMAND_FINISHED
] =
132 g_signal_new ("command-finished",
133 G_OBJECT_CLASS_TYPE (klass
),
137 g_cclosure_marshal_VOID__UINT
,
143 * AnjutaCommand::progress:
145 * @progress: Fraction of the command's task that is complete, between 0.0
146 * and 1.0, inclusive.
148 * Notifies clients of changes in progress during command execution.
150 anjuta_command_signals
[PROGRESS
] =
151 g_signal_new ("progress",
152 G_OBJECT_CLASS_TYPE (klass
),
154 G_STRUCT_OFFSET (AnjutaCommandClass
, progress
),
156 g_cclosure_marshal_VOID__FLOAT
,
162 * anjuta_command_start:
163 * @self: Command object to start
165 * Starts a command. Client code can handle data from the command by connecting
166 * to the ::data-arrived signal.
168 * #AnjutaCommand subclasses should override this method to determine how they
169 * call ::run, which actually does the command's legwork.
172 anjuta_command_start (AnjutaCommand
*self
)
174 ANJUTA_COMMAND_GET_CLASS (self
)->start (self
);
179 * anjuta_command_notify_data_arrived:
180 * @self: Command object.
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.
187 anjuta_command_notify_data_arrived (AnjutaCommand
*self
)
189 ANJUTA_COMMAND_GET_CLASS (self
)->notify_data_arrived (self
);
193 * anjuta_command_notify_complete:
194 * @self: Command object.
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.
201 anjuta_command_notify_complete (AnjutaCommand
*self
, guint return_code
)
203 ANJUTA_COMMAND_GET_CLASS (self
)->notify_complete (self
, return_code
);
207 * anjuta_command_notify_progress:
208 * @self: Command object.
210 * Emits the ::progress signal. Can be used by both base classes and
211 * commands as needed.
214 anjuta_command_notify_progress (AnjutaCommand
*self
, gfloat progress
)
216 ANJUTA_COMMAND_GET_CLASS (self
)->notify_progress (self
, progress
);
220 * anjuta_command_set_error_message:
221 * @self: Command object.
222 * @error_message: Error message.
224 * Command objects use this to set error messages when they encounter some kind
228 anjuta_command_set_error_message (AnjutaCommand
*self
, gchar
*error_message
)
230 if (self
->priv
->error_message
)
231 g_free (error_message
);
233 self
->priv
->error_message
= g_strdup (error_message
);
237 * anjuta_command_get_error_message:
238 * @self: Command object.
239 * @error_message: Error message.
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.
245 * Return value: Error message string that must be freed when no longer needed.
246 * If no error is set, return %NULL.
249 anjuta_command_get_error_message (AnjutaCommand
*self
)
251 return g_strdup (self
->priv
->error_message
);