[Usability]Re: dialog convenience API

[Ettore Perazzoli <ettore ximian com>]

On Wed, 2002-05-29 at 18:43, Havoc Pennington wrote:
> 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()?

Yes.

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

I think a recursive mainloop would be OK.  This is supposed to be used
for modal dialogs after all.

> 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).

Yep.

BTW, given that the HIG suggests specifying the actions in the dialog
instead of using stock buttons, we also have the problem that the
dialogs will look ugly a lot of the time because of mixing buttons with
and without icons.  (This has always been the problem with GNOME.)

I would be for dropping the icons altogether...

> 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.

Normally you don't want to have more than five buttons, and the meaning
of these buttons is already defined according to the HIG.  I.e. you want
an "action" button, a "cancel" button, and an "alternate action" button,
plus possibly "help" and "details".

So I don't think we need varargs for buttons; we can just enforce having
these specific kinds of buttons through the API, and gain in
consistency.

> 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.

Yeah, this would probably be bad.

> 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?

They should always be modal IMHO.

>  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()?

Oh, good point.  I think we should support that.

> > 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.)

This sucks, as it means that most apps will just have resizable message
dialogs.  :-/  The alert API should definitely enforce the
non-resizability though.

Anyways, here is how the API could work:

    typedef struct {
    	/* Signals.  */
    	void (* help_requested) (GtkAlert *alert);
    } GtkAlertClass;
    
    /* Will create an alert with just an OK button.  */
    GtkWidget *gtk_alert_new (GtkWindow *parent,
    			  GtkMessageType type,
    			  const char *bold_text,
    			  const char *text);
    
    /* Specify the text for each of the buttons.  */
    void  gtk_alert_set_action_button            (GtkAlert   *alert,
    					      const char *action_text);
    void  gtk_alert_set_alternate_action_button  (GtkAlert   *alert,
    					      const char *negative_action_text);
    void  gtk_alert_set_cancel_action_button     (GtkAlert   *alert,
    					      const char *cancel_text);
    
    /* Specify whether there is a help button.  If there is one,
       the widget will emit the "help_requested" signal when that button
       is clicked.  */
    void  gtk_alert_set_has_help (GtkAlert  *alert, gboolean has_help);
    
    /* Specify a widget to display when the "Details >>" button is
       clicked.  If this is not specified, there is no "Details >>"
       button.  */
    void  gtk_alert_set_details_widget  (GtkAlert  *alert,
    				     GtkWidget *details_widget);
    
    /* Error Alert.  */
    void gtk_alert_error (GtkWindow *parent,
    		      const char *title,
    		      const char *bold_text,
    		      const char *text,
                          const char *convenience_button, /* I.e. alternate action.  */
    		      GtkWidget *details_widget,
    		      GCallback help_callback,
    		      void *callback_data);
    
    /* Information Alert.  (Same as Error, but with an "information" icon.)  */
    void gtk_alert_information (GtkWindow *parent,
    			    const char *title,
    			    const char *bold_text,
    			    const char *text,
                                const char *convenience_action, /* I.e. alternate action.  */
    			    GtkWidget *details_widget,
    			    GCallback help_callback,
    			    void *callback_data);
    
    /* Confirmation Alert.  */
    GtkResponseType gtk_alert_confirmation (GtkWindow *parent,
    		                        const char *title,
    		                        const char *bold_text,
    		                        const char *text,
    		                        const char *action_button_text,
    		                        const char *alternate_action_button_text,
    		                        const char *cancel_button_text,
    		                        GtkWidget *details_widget,
    		                        GCallback help_callback,
    		                        void *callback_data);

This has the basic disadvantage of not allowing printf-style
formatting...  :-(  But if we want to enforce the bold/non-bold
convention and not have to deal with escaping the markup, I don't see
any other solution...

Also, these function calls all take several args.  Maybe we could have
gtk_alert_information_simple() or something, for the cases where you
just want to set title and text.

-- Ettore