This isn't limited to filechooser, I think the same should also be done for the font chooser, icon chooser (in libgnomeui) etc.

This could be done with adding a 'help-requested' signal (and maybe 'help-available' property), but how about something more global? The signal requires you to connect to each dialogue which you might not be able to do (think filechoosers opened from buttons, or from icon choosers, or from libraries under you (epiphany has a case like this)).

A global hook function might be a solution; not just for filechooser but for all dialogues  That way you can install a handler for all dialogues and then in the handler call the correct help document. This would also have the advantage that we could implement a stock handler in libgnomeui which would take care of the common dialogues.

Like this maybe:jus

typedef gboolean (* GtkDialogHelpFunc) (GtkDialog *dialog, gpointer data);

gtk_dialog_add_help_hook (GtkDialogHelpFunc func,
                          gpointer data,
                          GDestroyNotify dnotify);
and corresponding gtk_dialog_remove_help_hook.

(_add_ instead of _set_ because we want a global handler which takes care of the common dialogues, and you may also want an app-specific handler. returning TRUE would mean "handled", FALSE would invoke the next handler).

Maybe there's also a need to have a way to determine if help is available for a given dialogue at all, i.e. whether to show the help button:

typedef gboolean (* GtkDialogShowHelpFunc) (GtkDialog *dialog, gpointer);

with gtk_dialog_add_show_help_func (...)

--
The hook function in libgnomeui could then be like this:

if (GTK_IS_FILE_CHOOSER (dialog) &&
    gtk_file_chooser_get_action (GTK_FILE_CHOOSER (dialog)) == GTK_FILE_CHOOSER_ACTION_OPEN) {
  /* show help for "open" mode filechooser */
 }
else if (GTK_IS_FILE_CHOOSER (dialog) &&
    gtk_file_chooser_get_action (GTK_FILE_CHOOSER (dialog)) == GTK_FILE_CHOOSER_ACTION_SAVE) {
  /* show help for "save" mode filechooser" */
}
else if /* etc */...

If we make this a general problem (for all GTK+ megadialogs) instead of just the file chooser, we'll need a sample API and implementation.

closing old bugs