Re: [Evolution-hackers] Alert Dialog API

[Dave Malcolm <david davemalcolm demon co uk>]

On Tue, 2004-02-03 at 18:55, Rodney Dawes wrote:
> So, my current thoughts on writing the API for the HIG-compliant alert
> dialogs, is that there will be a generic API call for creating custom,
> and/or extended alert dialogs, and some simplistic API calls for popping
> up simple dialogs to alert the user of an error, warning, or a simple
> informational piece of text. The API would look something like this:
> 
> GtkWidget  * e_alert_dialog_new (const gchar * summary,
> 				 const gchar * message,
> 				 GtkMessageDialogType alert_type,
> 				 GtkWindow * parent);

Just to make this explicit: am I right in assuming that "summary"
corresponds to the "Primary" string and "message" to the "Secondary"
string as described in the Alert Text section of the HIG?

If so, does the function internally wrap the input strings with the
necessary Pango markup "<span weight="bold" size="larger">%s</span>"?

Overall, looks like a nice API.

> 
> void e_alert_dialog_set_icon (EAlertDialog * dialog,
> 			      const gchar * name);
> void e_alert_dialog_set_icon_from_pixbuf (EAlertDialog * dialog,
> 					  GdkPixbuf * pixbuf);
> void e_alert_dialog_set_icon_from_... (...);
> 
> This would be the generic interface for creating a custom or extended
> alert dialog. The _new () call creates a new dialog with the appropriate
> summary, message, icons, and window title, based on the given
> alert_type, and sets the appropriate flags for blocking the given parent
> when it is shown. The current GtkDialog APIs can be used to add buttons
> to the dialog, and run it. And, the response signal will get emitted,
> when the user clicks one of the buttons.
> 
> void e_alert_dialog_popup_simple (const gchar * summary,
> 				  const gchar * message,
> 				  GtkMessageDialogType alert_type,
> 				  GtkWindow * parent);
> 
> This would be the simple interface for popping up quick alert dialogs
> that don't need extra programmatic interaction. It is useful for simple
> warnings and errors, so that no extra code needs to be written to handle
> running and closing the dialog, for instance, when there is only an "OK"
> button, in the case of most common errors.
> 
> GtkWidget * e_alert_dialog_new_confirmation (const gchar * summary,
> 					     const gchar * message,
> 					     GtkWindow * parent);
> 
> This is to handle simple confirmation dialogs, such as confirming the
> "Empty Trash" request, or such. It returns a GtkWidget, so that the
> programmatic interface can be set up to do the right thing if the
> user confirms the action.
> 
> GtkWidget * e_alert_dialog_new_save_confirmation (const gchar * summary,
> 						  const gchar * message,
> 						  GtkWindow * parent);
> 
> This is to handle save confirmation dialogs. It also returns a GtkWidget
> for use in the programmatic interface needed to do the correct thing
> when the user chooses to save, not save, or cancel.

What exactly does this do?  "save confirmation" could mean "confirm
quitting/closing a modified document without saving" or it could mean
"confirm saving over the top of an existing file" (typically when doing
a "Save As..." operation).  I'm fairly sure that the labels on the
buttons ought to be different for these two cases.

What are the response values from the dialog?  I think there should be a
custom enum to make it explicit, since it's slightly confusing what the
"not save" vs "cancel" terms actually mean.

BTW, assuming its a "confirm close without saving", you might eventually
have another version which lets you pass a "time elapsed since last
save" parameter, if you're going to completely mimic the mockup in the
HIG.  I do this in Conglomerate, see:
http://cvs.gnome.org/bonsai/cvsblame.cgi?file=conglomerate%2Fsrc/cong-dialog.c&rev=&root=/cvs/gnome

where there's a function: cong_dialog_save_confirmation_alert_new
...though that code is looking a bit shoddy to me two years later on :-(

> 
> So, that is all I have now. A simple API for having HIG-compliant alerts
> that can be extended and customized if need be. Any thoughts, or other
> requests or constructive complaints?

Hope the above is useful

> -- dobey