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
66 static guint anjuta_command_signals
[LAST_SIGNAL
] = { 0 };
68 G_DEFINE_TYPE (AnjutaCommand
, anjuta_command
, G_TYPE_OBJECT
);
71 anjuta_command_init (AnjutaCommand
*self
)
73 self
->priv
= g_new0 (AnjutaCommandPriv
, 1);
77 anjuta_command_finalize (GObject
*object
)
81 self
= ANJUTA_COMMAND (object
);
83 g_free (self
->priv
->error_message
);
86 G_OBJECT_CLASS (anjuta_command_parent_class
)->finalize (object
);
90 anjuta_command_class_init (AnjutaCommandClass
*klass
)
92 GObjectClass
* object_class
= G_OBJECT_CLASS (klass
);
94 object_class
->finalize
= anjuta_command_finalize
;
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
;
104 * AnjutaCommand::data-arrived:
107 * Notifies clients that the command has processed data that is ready to
110 anjuta_command_signals
[DATA_ARRIVED
] =
111 g_signal_new ("data-arrived",
112 G_OBJECT_CLASS_TYPE (klass
),
116 g_cclosure_marshal_VOID__VOID
,
121 * AnjutaCommand::command-finished:
123 * @return_code: The return code of the finished commmand
125 * Indicates that the command has completed. Clients should at least handle
126 * this signal to unref the command object.
128 anjuta_command_signals
[COMMAND_FINISHED
] =
129 g_signal_new ("command-finished",
130 G_OBJECT_CLASS_TYPE (klass
),
134 g_cclosure_marshal_VOID__UINT
,
140 * anjuta_command_start:
141 * @self: Command object to start
143 * Starts a command. Client code can handle data from the command by connecting
144 * to the ::data-arrived signal.
146 * #AnjutaCommand subclasses should override this method to determine how they
147 * call ::run, which actually does the command's legwork.
150 anjuta_command_start (AnjutaCommand
*self
)
152 ANJUTA_COMMAND_GET_CLASS (self
)->start (self
);
157 * anjuta_command_notify_data_arrived:
158 * @self: Command object.
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.
165 anjuta_command_notify_data_arrived (AnjutaCommand
*self
)
167 ANJUTA_COMMAND_GET_CLASS (self
)->notify_data_arrived (self
);
171 * anjuta_command_notify_complete:
172 * @self: Command object.
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.
179 anjuta_command_notify_complete (AnjutaCommand
*self
, guint return_code
)
181 ANJUTA_COMMAND_GET_CLASS (self
)->notify_complete (self
, return_code
);
185 * anjuta_command_set_error_message:
186 * @self: Command object.
187 * @error_message: Error message.
189 * Command objects use this to set error messages when they encounter some kind
193 anjuta_command_set_error_message (AnjutaCommand
*self
, gchar
*error_message
)
195 if (self
->priv
->error_message
)
196 g_free (error_message
);
198 self
->priv
->error_message
= g_strdup (error_message
);
202 * anjuta_command_get_error_message:
203 * @self: Command object.
204 * @error_message: Error message.
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.
210 * Return value: Error message string that must be freed when no longer needed.
211 * If no error is set, return %NULL.
214 anjuta_command_get_error_message (AnjutaCommand
*self
)
216 return g_strdup (self
->priv
->error_message
);