From 4af6c2fd62c5db7fcdeefca11f8ca59c2ab1c748 Mon Sep 17 00:00:00 2001
From: Lex Trotman <elextr@gmail.com>
Date: Wed, 22 Jul 2009 03:04:17 +0000
Subject: [PATCH] Added Plugin interface for Build menu functionality

git-svn-id: https://geany.svn.sourceforge.net/svnroot/geany/branches/build-system@4011 ea778897-0a13-0410-b9d1-a72fbfd435f5
---
 ChangeLog       |  10 ++++
 doc/geany.html  |   6 +--
 src/Makefile.am |   3 +-
 src/build.c     |  79 ++++++++++++++++++++------------
 src/build.h     | 119 +++++++++++++++++++++++++++++++++++++++---------
 src/project.c   |   4 +-
 wscript         |   2 +-
 7 files changed, 167 insertions(+), 56 deletions(-)

diff --git a/ChangeLog b/ChangeLog
index 5e834219a..0057173bc 100644
--- a/ChangeLog
+++ b/ChangeLog
@@ -1,3 +1,13 @@
+2009-07-22  Lex Trotman  <elextr(at)gmail(dot)com>
+
+ * src/build.h, src/build.c, src/project.c
+   Created and documented plugins interface to build menu.
+   Factored out new get_cmd_group function.
+   Changed name of remove_command function to be consistent with the rest
+   of the interface & changed calls in project.c.
+ * src/Makefile.am, wscript
+   Added build.h to installed files lists.
+
 2009-07-20  Lex Trotman  <elextr(at)gmail(dot)com>
 
  * doc/geany.txt
diff --git a/doc/geany.html b/doc/geany.html
index 6fc1bac26..24aa83ece 100644
--- a/doc/geany.html
+++ b/doc/geany.html
@@ -6,7 +6,7 @@
 <meta name="generator" content="Docutils 0.4: http://docutils.sourceforge.net/" />
 <title>Geany</title>
 <meta name="authors" content="Enrico Tröger  Nick Treleaven  Frank Lanitz" />
-<meta name="date" content="2009-07-17" />
+<meta name="date" content="2009-07-20" />
 <style type="text/css">
 
 /*
@@ -139,7 +139,7 @@ Stylesheet for Geany's documentation based on a version of John Gabriele.
 <br />Nick Treleaven
 <br />Frank Lanitz</td></tr>
 <tr><th class="docinfo-name">Date:</th>
-<td>2009-07-17</td></tr>
+<td>2009-07-20</td></tr>
 <tr><th class="docinfo-name">Version:</th>
 <td>0.18</td></tr>
 </tbody>
@@ -5336,7 +5336,7 @@ USE OR PERFORMANCE OF THIS SOFTWARE.</p>
 <div class="footer">
 <hr class="footer" />
 <a class="reference" href="geany.txt">View document source</a>.
-Generated on: 2009-07-20 03:46 UTC.
+Generated on: 2009-07-22 02:16 UTC.
 Generated by <a class="reference" href="http://docutils.sourceforge.net/">Docutils</a> from <a class="reference" href="http://docutils.sourceforge.net/rst.html">reStructuredText</a> source.
 
 </div>
diff --git a/src/Makefile.am b/src/Makefile.am
index 0df1748be..3ce6edebb 100644
--- a/src/Makefile.am
+++ b/src/Makefile.am
@@ -71,7 +71,8 @@ geany_include_HEADERS = \
 	templates.h \
 	toolbar.h \
 	ui_utils.h \
-	utils.h
+	utils.h \
+	build.h
 
 
 INCLUDES = -I$(srcdir)/../scintilla/include -I$(srcdir)/../tagmanager/include @GTK_CFLAGS@ @GIO_CFLAGS@
diff --git a/src/build.c b/src/build.c
index b471dd8fb..e860cec1e 100644
--- a/src/build.c
+++ b/src/build.c
@@ -291,8 +291,8 @@ static GeanyBuildCommand *get_next_build_cmd(GeanyDocument *doc, gint cmdgrp, gi
 
 	if (printbuildcmds)printfcmds();
 	if (cmdgrp>=GBG_COUNT)return NULL;
-	if (from!=NULL)fr=from;
-	if (doc==NULL)doc=document_get_current();
+	if (from!=NULL)fr = from;
+	if (doc==NULL)doc = document_get_current();
 	if (doc!=NULL)ft = doc->file_type;
 	switch(cmdgrp)
 	{
@@ -357,63 +357,86 @@ gchar **get_build_regex(GeanyBuildGroup grp, GeanyFiletype *ft, gint *from)
 	return NULL;
 }
 
-/* remove the specified command, cmd<0 remove whole group */
-void remove_command(GeanyBuildSource src, GeanyBuildGroup grp, gint cmd)
+/* get pointer to the command group array */
+GeanyBuildCommand *get_build_group(GeanyBuildSource src, GeanyBuildGroup grp)
 {
-	GeanyBuildCommand *bc;
-	gint i;
 	GeanyDocument *doc;
 	GeanyFiletype *ft;
 	
 	switch(grp)
 	{
 		case GBG_FT:
-			if ((doc=document_get_current())==NULL)return;
-			if ((ft=doc->file_type)==NULL)return;
+			if ((doc=document_get_current())==NULL)return NULL;
+			if ((ft=doc->file_type)==NULL)return NULL;
 			switch(src)
 			{
-				case BCS_DEF:     bc=ft->ftdefcmds; break;
-				case BCS_FT:      bc=ft->filecmds; break;
-				case BCS_HOME_FT: bc=ft->homefilecmds; break;
-				case BCS_PREF:    bc=ft->homefilecmds; break;
-				case BCS_PROJ:    bc=ft->projfilecmds; break;
-				default: return;
+				case BCS_DEF:     return ft->ftdefcmds;
+				case BCS_FT:      return ft->filecmds;
+				case BCS_HOME_FT: return ft->homefilecmds;
+				case BCS_PREF:    return ft->homefilecmds;
+				case BCS_PROJ:    return ft->projfilecmds;
+				default: return NULL;
 			}
 			break;
 		case GBG_NON_FT:
 			switch(src)
 			{
-				case BCS_DEF:     bc=non_ft_def; break;
-				case BCS_PREF:    bc=non_ft_pref; break;
-				case BCS_PROJ:    bc=non_ft_proj; break;
-				default: return;
+				case BCS_DEF:     return non_ft_def;
+				case BCS_PREF:    return non_ft_pref;
+				case BCS_PROJ:    return non_ft_proj;
+				default: return NULL;
 			}
 			break;
 		case GBG_EXEC:
-			if ((doc=document_get_current())==NULL)return;
-			if ((ft=doc->file_type)==NULL)return;
+			if ((doc=document_get_current())==NULL)return NULL;
+			if ((ft=doc->file_type)==NULL)return NULL;
 			switch(src)
 			{
-				case BCS_DEF:     bc=exec_def; break;
-				case BCS_FT:      bc=ft->execcmds; break;
-				case BCS_HOME_FT: bc=ft->homeexeccmds; break;
-				case BCS_PREF:    bc=exec_pref; break;
-				case BCS_PROJ:    bc=exec_proj; break;
-				default: return;
+				case BCS_DEF:     return exec_def;
+				case BCS_FT:      return ft->execcmds;
+				case BCS_HOME_FT: return ft->homeexeccmds;
+				case BCS_PREF:    return exec_pref;
+				case BCS_PROJ:    return exec_proj;
+				default: return NULL;
 				
 			}
 			break;
 		default:
-			return;
+			return NULL;
 	}
+}
+
+/* remove the specified command, cmd<0 remove whole group */
+void build_remove_menu_item(GeanyBuildSource src, GeanyBuildGroup grp, gint cmd)
+{
+	GeanyBuildCommand *bc;
+	gint i;
+	bc = get_build_group(src, grp);
 	if (bc==NULL)return;
 	if (cmd<0)
 		for (i=0; i<build_groups_count[grp]; ++i)
 			bc[i].exists=FALSE;
-	else
+	else if(cmd<build_groups_count[grp])
 		bc[cmd].exists=FALSE;
 }
 
+/* get the build build command for the specified menu item */
+GeanyBuildCommand *build_get_menu_item(GeanyBuildSource src, GeanyBuildGroup grp, gint cmd)
+{
+	GeanyBuildCommand *bc;
+	if (src>=BCS_COUNT || grp>=GBG_COUNT || cmd>=build_groups_count[grp]) return NULL;
+	bc = get_build_group(src, grp);
+	if (bc==NULL) return NULL;
+	return &(bc[cmd]);
+}
+
+/* parameter checked version of get_build_cmd for external interface */
+GeanyBuildCommand *build_get_current_menu_item(GeanyBuildGroup grp, gint cmd, gint *src)
+{
+	if (src>=BCS_COUNT || grp>=GBG_COUNT || cmd>=build_groups_count[grp]) return NULL;
+	return get_build_cmd(NULL, grp, cmd, src);
+}
+
 /* Clear all error indicators in all documents. */
 static void clear_errors(GeanyDocument *doc)
 {
diff --git a/src/build.h b/src/build.h
index 590790e20..b4af4a900 100644
--- a/src/build.h
+++ b/src/build.h
@@ -21,6 +21,7 @@
  * $Id$
  */
 
+/** @file build.h Interface to the Build menu functionality. */
 
 #ifndef GEANY_BUILD_H
 #define GEANY_BUILD_H 1
@@ -40,12 +41,13 @@ typedef enum
 	GBO_COUNT	/* count of how many */
 } GeanyBuildType;
 
-typedef enum	/* build command groups, order as above */
+/** Groups of Build menu items. */
+typedef enum
 {
-	GBG_FT,		/* filetype */
-	GBG_NON_FT,	/* non filetype */
-	GBG_EXEC,	/* execute */
-	GBG_COUNT	/* count of how many */
+	GBG_FT,		/**< filetype items */
+	GBG_NON_FT,	/**< non filetype items.*/
+	GBG_EXEC,	/**< execute items */
+	GBG_COUNT	/**< count of groups. */
 } GeanyBuildGroup;
 
 /* include the fixed widgets in an array indexed by groups */
@@ -68,14 +70,15 @@ enum GeanyBuildFixedMenuItems
 	GBF_COUNT
 };
 
-typedef enum	/* build command sources, in increasing priority */
+/** Build menu item sources in increasing priority */
+typedef enum
 {
-	BCS_DEF,	/* default */
-	BCS_FT,		/* filetype */
-	BCS_HOME_FT,/* filetypes in home */
-	BCS_PREF,	/* preferences */
-	BCS_PROJ,	/* project */
-	BCS_COUNT	/* count of how many */
+	BCS_DEF,	/**< Default values. */
+	BCS_FT,		/**< System filetype values. */
+	BCS_HOME_FT,/**< Filetypes in ~/.config/geany/filedefs */
+	BCS_PREF,	/**< Preferences file ~/.config/geany/geany.conf */
+	BCS_PROJ,	/**< Project file if open. */
+	BCS_COUNT	/**< Count of sources. */
 } GeanyBuildSource;
 
 typedef struct GeanyBuildInfo
@@ -91,20 +94,24 @@ typedef struct GeanyBuildInfo
 
 extern GeanyBuildInfo build_info;
 
+/** The entries of a command for a menu item */
 typedef enum  GeanyBuildCmdEntries
 {
-    BC_LABEL,
-    BC_COMMAND,
-    BC_WORKING_DIR,
-    BC_CMDENTRIES_COUNT,
+    BC_LABEL,				/**< The menu item label, _ marks mnemonic */
+    BC_COMMAND,				/**< The command to run. */
+    BC_WORKING_DIR,			/**< The directory to run in */
+    BC_CMDENTRIES_COUNT,	/**< Count of entries */
 } GeanyBuildCmdEntries;
 
+/** The command for a menu item. */
 typedef struct GeanyBuildCommand
 {
+ 	/** Pointers to g_string values values of the command entries.
+	 * Must be freed if the pointer is changed. */
 	gchar *entries[BC_CMDENTRIES_COUNT];
-	gboolean	 exists;
-	gboolean	 changed;
-	gboolean	 old;
+	gboolean	 exists;					/**< If the entries have valid values. */
+	gboolean	 changed;					/**< Save on exit if @c changed, remove if not @c exist. */
+	gboolean	 old;						/**< Converted from old format. */
 } GeanyBuildCommand;
 
 extern GeanyBuildCommand *non_ft_proj, *exec_proj; /* project command array pointers */
@@ -144,13 +151,83 @@ void set_build_non_ft_wd_to_proj(TableData table_data);
 gboolean build_parse_make_dir(const gchar *string, gchar **prefix);
 
 /* build menu functions */
+
+/** Update the build menu to reflect changes in configuration or status.
+ * 
+ * Sets the labels and number of visible items to match the highest
+ * priority configured commands.  Also sets sensitivity if build commands are
+ * running and switches executes to stop when commands are running.
+ * 
+ * @param doc The current document, if available, to save looking it up.
+ *        If @c NULL it will be looked up.
+ * 
+ * Call this after modifying any fields of a GeanyBuildCommand structure.
+ * 
+ * @see Build Menu Configuration section of the Manual.
+ * 
+ **/
+
 void build_menu_update(GeanyDocument *doc);
 
-BuildMenuItems *build_get_menu_items(gint filetype_idx);
 
 void build_toolbutton_build_clicked(GtkAction *action, gpointer user_data);
 
-void remove_command(GeanyBuildSource src, GeanyBuildGroup grp, gint cmd);
+/** Remove the specified Build menu item.
+ * 
+ * Makes the specified menu item configuration no longer exist. This
+ * is different to setting fields to blank because the menu item
+ * will be deleted from the configuration file on saving 
+ * (except the system filetypes settings @see Build Menu Configuration 
+ * section of the Manual).  
+ * 
+ * @param src the source of the menu item to remove.
+ * @param grp the group of the command to remove.
+ * @param cmd the index (from 0) of the command within the group. A negative 
+ *        value will remove the whole group.
+ * 
+ * If any parameter is out of range does nothing.
+ * 
+ * @see build_menu_update
+ **/
+
+void build_remove_menu_item(GeanyBuildSource src, GeanyBuildGroup grp, gint cmd);
+
+/** Get the @a GeanyBuildCommand structure for the specified Build menu item.
+ * 
+ * Get the command for any menu item specified by @a src, @a grp and @a cmd even if it is 
+ * hidden by higher priority commands.
+ * 
+ * @param src the source of the specified menu item.
+ * @param grp the group of the specified menu item.
+ * @param cmd the index of the command within the group.
+ * 
+ * @return a pointer to the @a GeanyBuildCommand structure or @a NULL if it doesn't exist.
+ *         This is a pointer to an internal structure and must not be freed.
+ * 
+ * @see build_menu_update
+ **/
+
+GeanyBuildCommand *build_get_menu_item(GeanyBuildSource src, GeanyBuildGroup grp, gint cmd);
+
+/** Get the @a GeanyBuildCommand structure for the menu item.
+ * 
+ * Get the current highest priority command specified by @a grp and @a cmd.  This is the one 
+ * that the menu item will use if activated.
+ * 
+ * @param grp the group of the specified menu item.
+ * @param cmd the index of the command within the group.
+ * @param src pointer to @a gint to return which source provided the command. Ignored if @a NULL.
+ *        Values are one of @a GeanyBuildSource but returns a signed type not the enum.
+ * 
+ * @return a pointer to the @a GeanyBuildCommand structure or @a NULL if it doesn't exist.
+ *         This is a pointer to an internal structure and must not be freed.
+ * 
+ * @see build_menu_update
+ **/
+
+GeanyBuildCommand *build_get_current_menu_item(GeanyBuildGroup grp, gint cmd, gint *src);
+
+BuildMenuItems *build_get_menu_items(gint filetype_idx);
 
 /* load and store menu configuration */
 void load_build_menu( GKeyFile *config, GeanyBuildSource dst, gpointer ptr);
diff --git a/src/project.c b/src/project.c
index b82ca1f72..c2b3c5143 100644
--- a/src/project.c
+++ b/src/project.c
@@ -352,8 +352,8 @@ void project_close(gboolean open_default)
 	g_ptr_array_free(app->project->build_filetypes_list, FALSE);
 	
 	/* remove project non filetype build menu items */
-	remove_command( BCS_PROJ, GBG_NON_FT, -1 );
-	remove_command( BCS_PROJ, GBG_EXEC, -1 );
+	build_remove_menu_item( BCS_PROJ, GBG_NON_FT, -1 );
+	build_remove_menu_item( BCS_PROJ, GBG_EXEC, -1 );
 	
 	/* remove project regexen */
 	setptr(regex_proj, NULL);
diff --git a/wscript b/wscript
index 707131aae..86415ee10 100644
--- a/wscript
+++ b/wscript
@@ -453,7 +453,7 @@ def build(bld):
 			src/highlighting.h src/keybindings.h src/main.h src/msgwindow.h src/plugindata.h
 			src/plugins.h src/prefs.h src/project.h src/sciwrappers.h src/search.h src/support.h
 			src/templates.h src/toolbar.h src/ui_utils.h src/utils.h plugins/pluginmacros.h
-			plugins/geanyplugin.h plugins/geanyfunctions.h ''')
+			plugins/geanyplugin.h plugins/geanyfunctions.h src/build.h ''')
 		bld.install_files('${PREFIX}/include/geany/scintilla', '''
 			scintilla/include/SciLexer.h scintilla/include/Scintilla.h
 			scintilla/include/Scintilla.iface scintilla/include/ScintillaWidget.h ''')