PATCH: Remove dependency on implementation specifics, add comments in toolbar-factory.c

["M . Thielker" <balsa t-data com>]

Hi,

a new toolbar patch:

Fixes:
- dependency on implementation specifics removed, use standard API instead
- Comments added to toolbar-factory.c

Provides:
- nothing

Requires:
- current CVS tree

Hope that helps a bit. I couldn't reproduce any case in which a nonexistent
object is destroyed, neither with the old code, nor with the new.
Destruction of toolbar children is much more gtk-ish now, maybe the problem
is fixed by that.

Melanie
diff -b -B -r -u -P --exclude-from=ignore ../balsa-cvs/src/toolbar-factory.c ./src/toolbar-factory.c
--- ../balsa-cvs/src/toolbar-factory.c	Mon Jul 23 17:43:36 2001
+++ ./src/toolbar-factory.c	Mon Jul 23 22:29:13 2001
@@ -149,15 +149,23 @@
 }
 
 /* get_tool_widget:
-   FIXME: comment needed.
+   Get the GtkWidget * to a button in a specific toolbar.
+
+   Parameters:
+   		window		The window the toolbar is attached to
+		toolbar		The type of the toolbar to search
+		id			The ID string of the button pixmap
+
+   Returns:
+   		GtkWidget *, or NULL if error / not found
 */
 GtkWidget *
 get_tool_widget(GtkWidget *window, BalsaToolbarType toolbar, char *id)
 {
     GtkToolbar *bar;
-    GList *lp;
+    GList *lp, *children;
     int position;
-    GtkToolbarChild *child;
+    GtkWidget *child;
 
     bar=get_bar_instance(window, toolbar);
     if(!bar)
@@ -167,22 +175,42 @@
     if(position == -1)
 	return NULL;
     
-    lp=g_list_first(bar->children);
-    while(position--)
+    lp=children=gtk_container_children(GTK_CONTAINER(bar));
+	if(!children)
+	return(NULL);
+
+    while(position-- && lp) {
 	lp=g_list_next(lp);
+	}
 
-    if(!lp)
+    if(!lp) {
+		g_list_free(children);
 	return NULL;
+	}
+	
+    child=(GtkWidget *)(lp->data);
+
+	if(children)
+	g_list_free(children);
 	
-    child=(GtkToolbarChild *)(lp->data);
     if(!child)
 	return NULL;
 	
-    return child->widget;
+    return child;
 }
 
 /* get_bar_instance:
-   FIXME: comment needed.
+   Get a pointer to the toolbar for a given window
+
+   Parameters:
+   	window		Window the toolbar is attached to
+	toolbar		The type of the toolbar
+
+   Returns:
+   	GtkToolbar *, or NULL if error / not found
+
+   Notes:
+   	Uses the internal map tables, _not_ the GtkWidget "children" list
 */
 static GtkToolbar*
 get_bar_instance(GtkWidget *window, BalsaToolbarType toolbar)
@@ -248,7 +276,17 @@
 }
 
 /* get_toolbar_index:
-   FIXME: comment needed.
+   Get the index of the given toolbar in the data read from config
+   
+   Toolbar numbering in the config file is dependent on the order in that
+   each toolbar was customized. Therefore, the toolbar ID is not the same
+   as the config index. This maps the toolbar id to the config index.
+
+   Parameters:
+   	id		ID of the desired toolbar
+
+   Returns:
+   	Toolbar index in config data, or -1 if error / not found
 */
 int
 get_toolbar_index(int id)
@@ -263,7 +301,16 @@
 }
 
 /* create_stock_toolbar:
-   FIXME: comment needed.
+   Create a stock toolbar (uncustomized version) from the tables in this file
+   
+   This function is called to create a toolbar template when a toolbar has
+   never been customized.
+
+   Parameters:
+   	id			ID of the toolbar to create
+
+   Returns:
+	0 if OK, -1 if error
 */
 int
 create_stock_toolbar(int id)
@@ -290,14 +337,43 @@
 }
 
 /* get_toolbar:
-   FIXME: comment needed.
+   This is the main toolbar generating function
+
+   It will check if there is a toolbar for the given window/type combination
+   If one is found, it will empty and repopulate it, if none is found it
+   will create one, enter it into the local tables and fill it with the
+   buttons loaded from config or a default set of buttons.
+
+   The first time this function is called for a given window, thr caller
+   is responsible for attaching the newly created toolbar to it's window.
+   On subsequent calls for the same window / id combination this _must_ not
+   be done.
+   Once the toolbar is attached to a window, it will be updated in place. It
+   will never be destroyed for the lifetime of the window. Therefore, the
+   results of calling any of the toolbar add functions on the second and
+   further calls to this function will yield unsightly results and maybe
+   cause crashes.
+
+   Correct usage is:
+   	-	Call get_toolbar _once_ during window construction. Attach the
+		returned toolbar handle to the window.
+	-	When a toolbar needs to be refreshed, call get_toolbar again, but
+		_discard_ the return value
+	-	In a "destroy" handler for a window, call release_toolbars
+   
+   Parameters:
+	window		the GtkWindow for which a toolbar should be created
+	toolbar		the ID of the toolbar to create
+
+   Returns:
+    a GtkToolbar *, or NULL if error
 */
 GtkToolbar *
 get_toolbar(GtkWidget *window, BalsaToolbarType toolbar)
 {
     GtkToolbar *bar;
     GtkToolbarChild *child;
-    GList *lp;
+    GList *lp, *children;
     int index;
     int i, j, button;
     int position;
@@ -326,25 +402,16 @@
     } else  {
 	bar=GTK_TOOLBAR(toolbar_map[i].toolbar);
 	
-	lp=bar->children;
-	if(lp) {
+	/* Remove all toolbar children. Toolbars are in some way intelligent */
+	/* enough to automatically remove unneeded separators when this is done */
+	lp=children=gtk_container_children(GTK_CONTAINER(bar));
+	if(lp && g_list_length(lp)) {
 	    do {
-		--bar->num_children;
-		bar->children=g_list_remove_link(bar->children, lp);
-
 		child=(GtkToolbarChild *)lp->data;
-		if(child->label)
-		    gtk_widget_destroy(GTK_WIDGET(child->label));
-		if(child->icon)
-		    gtk_widget_destroy(GTK_WIDGET(child->icon));
-		if(child->widget)
-		    gtk_widget_destroy(GTK_WIDGET(child->widget));
-		g_free(child); 
-		g_list_free(lp);
-		if(!bar->children)
-		    break;
-		lp=g_list_first(bar->children);
+		gtk_container_remove(GTK_CONTAINER(bar), (void *)child);
+		lp=g_list_next(lp);
 	    } while(lp);
+		g_list_free(children);
 	} else /* !lp */ {
 	    for(i=0; i<MAXTOOLBARITEMS; i++)
 		tmpdata[i].disabled=0;
@@ -378,7 +445,6 @@
 
 	if(!*(balsa_app.toolbars[index][j])) {
 	    gtk_toolbar_append_space(bar);
-	    ++position;
 	    continue;
 	}
 	for(i=0; i<MAXTOOLBARITEMS; i++) {
@@ -450,7 +516,23 @@
 }
 
 /* set_toolbar_button_callback:
-   FIXME: comment needed.
+   This _must_ be called for each toolbar button to set a handler
+   _before_ get_toolbar is called. Failure to do so will keep the
+   buttons without handlers from appearing on the toolbar
+
+   Parameters:
+   	toolbar		ID of the toolbar to set callbacks for
+	id			Pixmap ID of the button to associate
+	callback	The callback function
+	data		User data to be passed to the callback
+
+   Returns:
+   	nothing
+
+   Notes:
+   	If data == NULL, the GtkWidget * of the toolbar's parent window will
+	be passed to the callback
+
 */
 void
 set_toolbar_button_callback(BalsaToolbarType toolbar, char *id, 
@@ -468,7 +550,21 @@
 }
 
 /* set_toolbar_button_sensitive:
-   FIXME: comment needed.
+   Sensitize or desensitize a toolbar button
+
+   This should be used in preference to gtk_widget_set_sensitive because it
+   also sets internal flags. This way sensitivity will be preserved across
+   toolbar reconfiguration.
+
+   Parameters:
+   	window		Window * of the toolbar's parent window
+	toolbar		Type if the toolbar
+	id			Pixmap ID of the button to set
+	sensitive	1 sets sensitive, 0 desensitizes
+
+   Notes:
+   	This function may be called before the toolbar is instantiated using
+	get_toolbar.
 */
 void
 set_toolbar_button_sensitive(GtkWidget *window, BalsaToolbarType toolbar, 
@@ -489,7 +585,17 @@
 }
 
 /* release_toolbars:
-   FIXME: comment needed.
+   Another mainstay of the toolbar system. This function will release the
+   toolbar from the module internal data tables. These tables have a finite
+   (100) size and may overflow if toolbars are not released. The proper way
+   to do this is to call release_toolbars from a "destroy" handler for the
+   window using the toolbar.
+
+   Parameters:
+   	window		The window that is being destroyed
+
+   Returns:
+   	nothing
 */
 void
 release_toolbars(GtkWidget *window)
@@ -508,7 +614,10 @@
 }
 
 /* update_all_toolbars:
-   FIXME: comment needed.
+   Update all toolbars in all windows displaying a toolbar
+
+   Called from toolbar-prefs.c after a change has been mada to a toolbar
+   layout.
 */
 void
 update_all_toolbars(void)
@@ -520,7 +629,11 @@
 }
 
 /* get_legal_toolbar_buttons:
-   FIXME: comment needed.
+   Returns a pointer to an array of char * listing the buttons that can
+   be placed on the given toolbar. A pointer to an empty string, if present,
+   _must_ be the first item and means that separators are legal to insert
+   in the given toolbar. If the first item is not a separator, the behavior
+   of the preferences dialog is undefined.
 */
 char**
 get_legal_toolbar_buttons(int toolbar)