diff options
author | Michael Zucci <zucchi@src.gnome.org> | 2004-04-28 14:41:55 +0800 |
---|---|---|
committer | Michael Zucci <zucchi@src.gnome.org> | 2004-04-28 14:41:55 +0800 |
commit | 96df3f7555c872c4806f5199529852e6d2821088 (patch) | |
tree | 02bba5c4ff69ef638e25b37d2cdb3d88c873a8e6 /devel-docs | |
parent | e23cf1ca36bcf886bcac15545166eff0e930a4bd (diff) | |
download | gsoc2013-evolution-96df3f7555c872c4806f5199529852e6d2821088.tar gsoc2013-evolution-96df3f7555c872c4806f5199529852e6d2821088.tar.gz gsoc2013-evolution-96df3f7555c872c4806f5199529852e6d2821088.tar.bz2 gsoc2013-evolution-96df3f7555c872c4806f5199529852e6d2821088.tar.lz gsoc2013-evolution-96df3f7555c872c4806f5199529852e6d2821088.tar.xz gsoc2013-evolution-96df3f7555c872c4806f5199529852e6d2821088.tar.zst gsoc2013-evolution-96df3f7555c872c4806f5199529852e6d2821088.zip |
stuff describing e_error_*
svn path=/trunk/; revision=25654
Diffstat (limited to 'devel-docs')
-rw-r--r-- | devel-docs/misc/errors.txt | 160 |
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. + + |