Re: [Evolution-hackers] Error reporting changes

[Jonathon Jongsma <jonathon jongsma collabora co uk>]

On Mon, 2009-11-30 at 14:07 -0600, Jonathon Jongsma wrote:
> I just pushed a branch to master that changes how errors are reported.
> This is part of a bigger effort to isolate the front end from the
> backend, but it's just a small first step.  In general, errors have been
> presented directly to the user (as dialogs) as soon as they happened.
> This is demonstrated by the fact that e_error_new() returned a
> GtkDialog*.  This is problematic for a few reasons.  The first being
> that it's not always desirable to show an error as a dialog (for
> instance, we might want to display them in the future in a GtkInfoBar
> widget or something similar).  In addition, it makes it very difficult
> to separate the backend functionality from the UI, or to let the calling
> function make a policy decision about whether the error should be
> displayed or handled in some other way.
> 
> So, as a first step to fix this, I've created a new 'object' (really
> just a plain struct right now, but in the future it could be a proper
> GObject if we thought it was useful) called EAlert.  I chose EAlert
> rather than EError based on Matthew Barnes advice since evolution often
> uses this infrastructure to present general informative messages, not
> only errors.
> 
> I have kept the convenience API in place to create / display a dialog
> directly, but the function names will be a bit different.  For instance,
> where you previously used e_error_new(), you can now achieve the same
> thing with e_alert_new_dialog_for_args() (the _for_args() is to
> distinguish it from e_alert_new_dialog() which accepts a EAlert* object
> -- if you can think of a better name for this function, feel free to
> suggest one).  Where you previously used e_error_run(), you can now do
> the same thing with e_alert_run_dialog_for_args() (same note about
> function naming as above).
> 
> However, my goal is to phase out use of these dialog-related helper
> functions.  The plan is that in the future, instead of reporting errors
> directly, functions that can fail will take a EAlert** parameter and
> return a newly allocated EAlert object describing the situation (i.e.
> the same idiom as GError).  The calling function can then determine how
> to handle or present that to the user.
> 
> I started changing the files in filter/ to use the design I mentioned in
> the previous paragraph, so for example, the function:
>   e_filter_element_validate(EFilterElement *element, GtkWindow *parent)
> became:
>   e_filter_element_validate(EFilterElement *element, EAlert **alert)
> 
> Other parts of the tree have only been changed to use the equivalent
> helper functions mentioned above.
> 

Quick follow-up to this: I was convinced by a couple of people that we'd
probably want EAlert to be a GObject, so I bit the bullet and just did
it.  In addition, I factored out the convenience dialog functionality
and created a GtkDialog subclass called EAlertDialog. This means that
there are a couple additional changes since I wrote this mail.  The most
important ones for developers and plugin authors:

- e_alert_free() no longer exists.  use g_object_unref()
- to use the dialog functionality, include e-alert-dialog.h rather than
just e-alert.h
- e_alert_new_dialog() -> e_alert_dialog_new()

Also, there's one little picky cleanup that I snuck in along with those
changes.  e_alert_newv() was renamed to e_alert_new_valist() to be more
consistent with other API in glib (e.g. g_object_newv() takes an array
and a length vs g_object_new_valist() which takes a va_list)

Evolution, evolution-mapi and evolution-exchange should all be
up-to-date with these changes in git.  If you have a plugin that's
out-of-tree, it may need to be updated.

-- 
Jonathon Jongsma <jonathon jongsma collabora co uk>