new libxfce4combo API doc

[edscott wilson garcia]

Guess what? I had previously written an API doc for the libxfce4combo
module and forgot all about it. The doc is included in combo.h file of
the xfce4-modules directory. I'm including it here because it explains
things better than my previous post, especially the functions I thought
were not supposed to be exported... 

EXTERN gboolean xfc_is_in_history(char *path2dbh_file,char *path2find);
/* Query dbhashtable for path2find.
 *
 * Call: if(xfc_is_in_history(path2dbh_file,path2find){do_something}
 *  
 * Returns: TRUE if path2find is in dbhashtable */

EXTERN gboolean xfc_set_combo(xfc_combo_info_t *combo_info, char
*token);
/* sets the glist for the combo, reduced by autocompletion. 
 * autocompletion and glist reduction done with variable: token.
 *
 * Call: if(xfc_set_combo(combo_info, token)){do_something}
 *
 * Returns: TRUE is autocompletion is possible.
 * */

EXTERN void xfc_set_blank(xfc_combo_info_t *combo_info);
/* sets the initial glist for the combo, and puts a blank
 * as the value for the combo entry.
 *
 * Call:  xfc_set_blank(combo_info);
 * */

EXTERN void xfc_set_entry(xfc_combo_info_t *combo_info,char
*entry_string);
/* set the initial glist for the combo, and puts variable: top
 * as the value for the combo entry. The glist is not reduced by
 * the value of top (use xfce_set_combo() for that.
 *
 * Call:  xfc_set_entry(combo_info, entry_string);
 * */

EXTERN void xfc_save_to_history(char *path2dbh_file,char *path2save);
/* This saves path2save to dbhashtable or increments the hit counter
 * if path2save is already in the dbhashtable 
 *
 * Call: xfc_save_to_history(path2dbh_file,path2save);
 * */

EXTERN void xfc_remove_from_history(char *path2dbh_file,char
*path2remove);
/* This removes path2save from the dbhastable, if it exists in the
dbhastable
 *
 * Call: xfc_remove_from_history(path2dbh_file, path2remove);
 * */

EXTERN void xfc_read_history(xfc_combo_info_t *combo_info, gchar
*path2dbh_file);
/* This reads the dbhashtable. This is done before all other functions
 * except xfc_init_combo() and need be done only once (except if you
want to
 * switch glists on the same combo: see xffm/libs/input.c for an example
 * on how to use multiple lists on the same combo). Normally this
function
 * is not necessary.
 * 
 * Call: xfc_read_history(combo_info, path2dbh_file);
 * */

EXTERN void xfc_clear_history(xfc_combo_info_t *combo_info);
/* This clears the glist associated with the combo. Only need it if you
 * plan to use multiple glists on the same combo (see xffm/libs/input.c 
 * for an example) to avoid memory leaks. Normally not necessary since
 * it is implied by xfce_destroy_combo().
 *
 * Call: xfc_clear_history(combo_info);
 * */ 

EXTERN xfc_combo_info_t *xfc_init_combo(GtkCombo *combo);
/* This should be called before any other function. It will allocate the
 * necessary memory for the xfc_combo object and initialize variables.
 * 
 * Call (example): 
 * 	combo_info = xfc_init_combo(combo_info);
 * 	xfc_read_history(combo_info, path2dbh_file);
 * 	xfc_set_blank(combo_info);
 * 	
 * 	[optional stuff:]
 * 	combo->activate_func = user_callback_1;
 * 	combo->cancel_func = user_callback_2;
 * 	combo->cancel_user_data = user_data_1;
 * 	combo->activate_user_data = user_data_2;
 * 
 * Returns: pointer to newly created xfc_combo object or NULL if fails.
 * */

EXTERN xfc_combo_info_t *xfc_destroy_combo(xfc_combo_info_t
*combo_info);
/* This destroys a previously allocated xfc_combo object.
 * 
 * Call: combo_info = xfc_destroy_combo(combo_info);
 * 
 * Returns: NULL. 
 * */