stuff describing e_error_*

svn path=/trunk/; revision=25654

1 files changed, 160 insertions, 0 deletions

diff --git a/devel-docs/misc/errors.txt b/devel-docs/misc/errors.txt
new file mode 100644
index 0000000000..fc81dd4eff
--- /dev/null
+++ b/devel-docs/misc/errors.txt
@@ -0,0 +1,160 @@
+
+
+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.
+
+List the files, and build rules:
+
+error_in_files = error-file-name.xml.in
+error_DATA = $(error_in_files:.xml.in=.xml)
+errordir = $(privdatadir)/errors
+@INTLTOOL_XML_RULE@
+
+Add to EXTRA_DIST:
+
+EXTRA_DIST =			\
+	$(error_in_files)
+
+And add to BUILT_SOURCES:
+
+BUILT_SOURCES = $(error_DATA)
+
+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.
+
+_title, _primary, and _secondary are all optional, if missing,
+standard text (for title) or blank text will be used.
+
+<button /> is optional, if missing, a single stock Ok button 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.
+
+