From 96df3f7555c872c4806f5199529852e6d2821088 Mon Sep 17 00:00:00 2001 From: Michael Zucci Date: Wed, 28 Apr 2004 06:41:55 +0000 Subject: stuff describing e_error_* svn path=/trunk/; revision=25654 --- devel-docs/misc/errors.txt | 160 +++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 160 insertions(+) create mode 100644 devel-docs/misc/errors.txt 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. + + + + + <_title>Window Title? + <_primary>Primary error text.? + <_secondary>Secondary error text.? +