evolution/devel-docs/misc/errors.txt

Errors can be displayed using e_error_* functions.  This will ensure
that Evolution presents a common and consistent face to the user.
e_error also automatically does HIG presentation, and allows
simplification of code.

Errors are defined in an XML file, given an identifier, and some
formatting information.  The XML format is described below.

Translators also see the section "Error template format" for
information on the substitution format.

To use these functions, include "widgets/misc/e-error.h"

A source build also includes the test program test-error, which may be
used to test the errors being written.  It resides in
"widgets/misc/test-error".

API
---

The error API is very simple, it consists of 2 main entry points, with
varags alternatives of each.

struct _GtkWidget *e_error_new(struct _GtkWindow *parent,
   const char *tag, const char *arg0, ...);
int e_error_run(struct _GtkWindow *parent,
   const char *tag, const char *arg0, ...);

The first is to create a GtkDialog filled out with the error
information, which can be added to, and/or run asynchronously.  It can
be used as if it was a normal GtkDialog, except the buttons and some
content will already be setup.

The second is to create this GtkDialog, run it synchronously, get its
response, and then destroy it.

They share common arguments:

parent: The parent GtkWindow if available.  If set, then this window
will be set as the transient parent for this dialog.  It will also
implictly set the DESTROY_WITH_PARENT flag.

tag: The id of the error message to use as a template.  This consists
of two parts, domain:id, where domain is defined in each error
definition file, and id is defined for each error itself.

arg0, ...: The arguments to the error template.  These consist of a
NULL terminated array of strings which are inserted into the template
at the appropriate location(s).

struct _GtkWidget *e_error_newv(struct _GtkWindow *parent,
    const char *tag, const char *arg0, va_list ap);
int e_error_runv(struct _GtkWindow *parent,
    const char *tag, const char *arg0, va_list ap);

These are identical to above, but can be used from other varags
functions.

Predefined Errors
-----------------

Note that this list is liable to become out of date, but the
currently known list of system errors follows.

#define E_ERROR_WARNING "builtin:warning"
#define E_ERROR_ERROR "builtin:error"

Blank templates of each error type which pass the first argument as
the whole primary text, and the second argument as the whole secondary
text to be displayed.  A single Ok button is available to close the
window.

#define E_ERROR_WARNING_PRIMARY "builtin:warning-primary"
#define E_ERROR_ERROR_PRIMARY "builtin:error-primary"

As above, but no secondary text is supplied.

#define E_ERROR_ASK_FILE_EXISTS_OVERWRITE "system:ask-save-file-exists-overwrite"

The user has tried to save a file, but they have chosen an existing
file.  Ask the user if they wish to overwrite the file or cancel the
operation.  The first argument is the name of the file.  A return of
GTK_RESPONSE_OK indicates that the user wishes to overwrite.

#define E_ERROR_NO_SAVE_FILE "system:no-save-file"

The program has tried to save a file, but it could not be written for
some reason.  The first argument is the file name, the second is the
reason.

#define E_ERROR_NO_LOAD_FILE "system:no-save-file"

The program has tried to load a file, but it could not be opened or
read for some reason.  The first argument is the file name, the second
is the reason.

Error templates
---------------

Error templates are xml files which are installed in an Evolution
defined, version-specific directory.  They should be installed in
"${privdatadir}/errors".

The following Makefile.am entries should be setup for each error
template file.  This is required to generate the i18n template files
used for internationalisation.

List the files, and build rules:

error_DATA = error-file-name.xml
error_i18n = $(error_DATA:.xml=.xml.h)
errordir = $(privdatadir)/errors
%.xml.h: %.xml
	 $(top_builddir)/e-util/e-error-tool $^

Add to EXTRA_DIST:

EXTRA_DIST =			\
	$(error_DATA)		\
	$(error_i18n)

And add to BUILT_SOURCES:

BUILT_SOURCES = $(error_i18n)

Error template format
---------------------

The XML file is in the following format.

<?xml version="1.0"?>
<error-list domain="ERRORDOMAIN">
 <error id="error-id" type="info|warning|question|error"? response="default_response"? modal="true"? >
  <title>Window Title</title>?
  <primary>Primary error text.</primary>?
  <secondary>Secondary error text.</secondary>?
  <button stock="stock-button-id"? label="button label"? response="response_id"? /> *
 </error>
</error-list>

response_id is a standard GTK_RESPONSE_* GtkDialog response
enumeration.

stock-button-id is a standard GtkStock button name.

label is a translatable string for the button name otherwise,
including an underlined mnemonic.

One of stock and _label must be supplied for all buttons defined.
Both may be defined, in which case you get a stock-looking button with
a different label text.

<button /> is optional, if missing, a single stock Ok button will be
used.

title, primary, and secondary are all optional, if missing,
standard text (for title) or blank text will be used.

For the title, primary and secondary texts, substitution of the passed
e_error parameters can be performed using "{n}" syntax, where n is a
decimal index of the string parameter argument.  This allows the same
arguments to be re-used in different locations within the same error
box.