[Usability]dialog convenience API

[Havoc Pennington <hp redhat com>]

Ettore Perazzoli <ettore ximian com> writes: 
> 	int gtk_message_dialog_prompt (GtkWindow *parent, 
>                                        GtkMessageType type,
> 		                       GtkButtonsType buttons, 
> 				       const char *message_format,
> 				       ...);

What is the return value? From gtk_dialog_run()?

For the error dialog case, do you want a recursive main loop, or do
you want:

static GtkWidget *dialog;

gtk_message_dialog_create_with_weak_pointer (&widget, 
                                             parent, type, buttons, format);

i.e. fire-and-forget but recording a weak pointer to avoid dialog spam
if the codepath is entered twice.

Neither one allows using buttons that are not found in GtkButtonsType,
which is pretty problematic since the UI guidelines discourage the use
of most things in GtkButtonsType. My guess is that GtkButtonsType is
no good for 90% of cases where you want to gtk_dialog_run() and get a
the user to make a choice, but is probably fine for cases where the
dialog has only one button (as in an error dialog).

To get around the GtkButtonsType limitation you really need to provide
the buttons via varargs, but varargs are already used for the message
text format.

A strawman alternative API would be for error dialogs only:

 gtk_message_dialog_create_error (&widget, parent,
                                  "Foo is horked");

So simpler to use, always has just a Close button.

Switching to top-down mode, the HIG suggests:
 http://developer.gnome.org/projects/gup/hig/draft_hig/alert-windows.html#alerts-error

That would require two strings, the boldface one and the regular, or
alternatively a single markup string. The problem with the markup
string is that you need a g_strdup_printf() that escapes the args to
%s, or you'll have oceans of bugs like this:

 ("<b>Foo bar in file %s</b>\nblah blah", filename)

filename needs to go through g_markup_escape_text() to get XML special
chars escaped.

The HIG recommendation also means you need a way to add the
"convenience handle the error now" button, and does not yet specify
the dialog title (if it isn't "Error" then we'd need to pass it in).

So maybe:
 gtk_message_dialog_create_error (&widget, parent, 
                                  extra_button_name,
                                  title,
                                  bold_text,
                                  regular_text);

Which text argument gets the varargs and is a printf format?

Should any/all of these functions take a GtkDialogFlags so you can
make them modal or destroy_with_parent? Or are they automatically
destroy_with_parent?

What about the non-error kinds of alert in the HIG?

We could maybe make the API cohere around the concept of an "alert"
so name it that way:
 
 gtk_alert_dialog_new (widget, parent, bold_text, regular_text);

Another thing I've been using pretty often is a "details" button,
i.e. the dialog text might be "there was a problem loading
preferences" and if you click "Details" you get a bunch of GConf
gobbledygook. Should an API support that? gtk_dialog_add_details()?

> Also, I think gtk_message_dialog_new() should return a non-resizable
> dialog by default.

IIRC, originally wasn't done because there is no way to change the
default value of an object property in a subclass. Can't be done now
as it's an ABI change. (Apps that wanted resizable will break.)

Havoc