docs/devel/misc/errors.txt

   1
   2
   3 Errors can be displayed using e_error_* functions.  This will ensure
   4 that Evolution presents a common and consistent face to the user.
   5 e_error also automatically does HIG presentation, and allows
   6 simplification of code.
   7
   8 Errors are defined in an XML file, given an identifier, and some
   9 formatting information.  The XML format is described below.
  10
  11 Translators also see the section "Error template format" for
  12 information on the substitution format.
  13
  14 To use these functions, include "widgets/misc/e-error.h"
  15
  16 A source build also includes the test program test-error, which may be
  17 used to test the errors being written.  It resides in
  18 "widgets/misc/test-error".
  19
  20 API
  21 ---
  22
  23 The error API is very simple, it consists of 2 main entry points, with
  24 varags alternatives of each.
  25
  26 struct _GtkWidget *e_error_new(struct _GtkWindow *parent,
  27    const char *tag, const char *arg0, ...);
  28 int e_error_run(struct _GtkWindow *parent,
  29    const char *tag, const char *arg0, ...);
  30
  31 The first is to create a GtkDialog filled out with the error
  32 information, which can be added to, and/or run asynchronously.  It can
  33 be used as if it was a normal GtkDialog, except the buttons and some
  34 content will already be setup.
  35
  36 The second is to create this GtkDialog, run it synchronously, get its
  37 response, and then destroy it.
  38
  39 They share common arguments:
  40
  41 parent: The parent GtkWindow if available.  If set, then this window
  42 will be set as the transient parent for this dialog.  It will also
  43 implictly set the DESTROY_WITH_PARENT flag.
  44
  45 tag: The id of the error message to use as a template.  This consists
  46 of two parts, domain:id, where domain is defined in each error
  47 definition file, and id is defined for each error itself.
  48
  49 arg0, ...: The arguments to the error template.  These consist of a
  50 NULL terminated array of strings which are inserted into the template
  51 at the appropriate location(s).
  52
  53 struct _GtkWidget *e_error_newv(struct _GtkWindow *parent,
  54     const char *tag, const char *arg0, va_list ap);
  55 int e_error_runv(struct _GtkWindow *parent,
  56     const char *tag, const char *arg0, va_list ap);
  57
  58 These are identical to above, but can be used from other varags
  59 functions.
  60
  61 Predefined Errors
  62 -----------------
  63
  64 Note that this list is liable to become out of date, but the
  65 currently known list of system errors follows.
  66
  67 #define E_ERROR_WARNING "builtin:warning"
  68 #define E_ERROR_ERROR "builtin:error"
  69
  70 Blank templates of each error type which pass the first argument as
  71 the whole primary text, and the second argument as the whole secondary
  72 text to be displayed.  A single Ok button is available to close the
  73 window.
  74
  75 #define E_ERROR_WARNING_PRIMARY "builtin:warning-primary"
  76 #define E_ERROR_ERROR_PRIMARY "builtin:error-primary"
  77
  78 As above, but no secondary text is supplied.
  79
  80 #define E_ERROR_ASK_FILE_EXISTS_OVERWRITE "system:ask-save-file-exists-overwrite"
  81
  82 The user has tried to save a file, but they have chosen an existing
  83 file.  Ask the user if they wish to overwrite the file or cancel the
  84 operation.  The first argument is the name of the file.  A return of
  85 GTK_RESPONSE_OK indicates that the user wishes to overwrite.
  86
  87 #define E_ERROR_NO_SAVE_FILE "system:no-save-file"
  88
  89 The program has tried to save a file, but it could not be written for
  90 some reason.  The first argument is the file name, the second is the
  91 reason.
  92
  93 #define E_ERROR_NO_LOAD_FILE "system:no-save-file"
  94
  95 The program has tried to load a file, but it could not be opened or
  96 read for some reason.  The first argument is the file name, the second
  97 is the reason.
  98
  99 Error templates
 100 ---------------
 101
 102 Error templates are xml files which are installed in an Evolution
 103 defined, version-specific directory.  They should be installed in
 104 "${privdatadir}/errors".
 105
 106 The following Makefile.am entries should be setup for each error
 107 template file.  This is required to generate the i18n template files
 108 used for internationalisation.
 109
 110 List the files, and build rules:
 111
 112 error_DATA = error-file-name.xml
 113 error_i18n = $(error_DATA:.xml=.xml.h)
 114 errordir = $(privdatadir)/errors
 115 %.xml.h: %.xml
 116          $(top_builddir)/e-util/e-error-tool $^
 117
 118 Add to EXTRA_DIST:
 119
 120 EXTRA_DIST =                    \
 121         $(error_DATA)           \
 122         $(error_i18n)
 123
 124 And add to BUILT_SOURCES:
 125
 126 BUILT_SOURCES = $(error_i18n)
 127
 128 Error template format
 129 ---------------------
 130
 131 The XML file is in the following format.
 132
 133 <?xml version="1.0"?>
 134 <error-list domain="ERRORDOMAIN" translation-domain="translation domain" translation-localedir="localedir">
 135  <error id="error-id" type="info|warning|question|error"? response="default_response"? modal="true"? >
 136   <title>Window Title</title>?
 137   <primary>Primary error text.</primary>?
 138   <secondary>Secondary error text.</secondary>?
 139   <button stock="stock-button-id"? label="button label"? response="response_id"? /> *
 140  </error>
 141 </error-list>
 142
 143 translation-domain and translation-localedir are used to specify a custom
 144 translation domain for this error file, and where to find it.
 145
 146 response_id is a standard GTK_RESPONSE_* GtkDialog response
 147 enumeration.
 148
 149 stock-button-id is a standard GtkStock button name.
 150
 151 label is a translatable string for the button name otherwise,
 152 including an underlined mnemonic.
 153
 154 One of stock and _label must be supplied for all buttons defined.
 155 Both may be defined, in which case you get a stock-looking button with
 156 a different label text.
 157
 158 <button /> is optional, if missing, a single stock Ok button will be
 159 used.
 160
 161 title, primary, and secondary are all optional, if missing,
 162 standard text (for title) or blank text will be used.
 163
 164 For the title, primary and secondary texts, substitution of the passed
 165 e_error parameters can be performed using "{n}" syntax, where n is a
 166 decimal index of the string parameter argument.  This allows the same
 167 arguments to be re-used in different locations within the same error
 168 box.