doc/events.txt

   1                                 Events
   2
   3 This file lists the events currently in use, when they are called, what they
   4 do and what arguments they expect.
   5
   6 Events are a mechanism for communication between ELinks parts --- any ELinks
   7 subsystem (module) can register an event, hook at an event or trigger an event.
   8 Events are designed to allow transition to a completely message-passing model
   9 internally, with modules talking to each other through the events.
  10
  11 Events are currently used primarily as a generic way to trigger event handlers
  12 in various scripting backends.
  13
  14 Therefore, so far this reference sheet is useful mainly to scripting backends
  15 developers and also scripting power users - it looks at the C side but usually
  16 you get most (if not all) of it passed to the hook functions in your scripts.
  17
  18
  19
  20 Below is a template showing how to read the event information
  21
  22 Name:           <event name>
  23 Managed By:     <what part of the code registers and unregister the event>
  24 Triggered When:
  25
  26  <short description of when the event is triggered>
  27
  28 Arguments:
  29
  30  <the order and type of the arguments>
  31
  32 Description:
  33
  34  <description of the arguments, what the event does etc.>
  35
  36 Please keep in alphabetical order!
  37
  38
  39
  40 The list of events itself:
  41
  42 -------------------------------------------------------------------------------
  43 Name:           bookmark-delete
  44 Managed By:     The bookmarks subsystem
  45 Triggered When:
  46
  47  A bookmark is being deleted.
  48
  49 Arguments:
  50
  51  struct bookmark *bookmark
  52
  53 Description:
  54
  55  Currently only used by the tab snapshotting code to avoid a dangling pointer
  56  should the deleted bookmark be the folder to which it made the last snapshot.
  57
  58 -------------------------------------------------------------------------------
  59 Name:           bookmark-move
  60 Managed By:     The bookmarks subsystem
  61 Triggered When:
  62
  63  A bookmark is being moved.
  64
  65 Arguments:
  66
  67  struct bookmark *bookmark
  68  struct bookmark *destination
  69
  70 Description:
  71
  72  The bookmark is moved immediately after the destination bookmark.
  73
  74  This is currently only used by the tab snapshotting code, which assumes
  75  that when a user moves a bookmark, the user does not want the snapshotting
  76  code to delete it when it makes the next snapshot.
  77
  78 -------------------------------------------------------------------------------
  79 Name:           bookmark-update
  80 Managed By:     The bookmarks subsystem
  81 Triggered When:
  82
  83  The user finishes editing a bookmark.
  84
  85 Arguments:
  86
  87  struct bookmark *bookmark
  88  unsigned char *new_title
  89  unsigned char *new_url
  90
  91 Description:
  92
  93  This is triggered before the new title and URL are assigned to the bookmark.
  94  Therefore, handlers can get the old title and URL from the bookmark structure
  95  and the new title and URL from the event arguments.
  96
  97  This is currently only used by the tab snapshotting code, which assumes
  98  that when a user edits a bookmark, the user does not want the snapshotting
  99  code to delete it when it makes the next snapshot.
 100
 101 -------------------------------------------------------------------------------
 102 Name:           dialog-lua-console
 103 Managed By:     The Lua scripting subsystem/backend
 104 Triggered When:
 105
 106  The user hits a key associated with 'lua-console' action.
 107
 108 Arguments:
 109
 110  struct session *ses
 111
 112 Description:
 113
 114  Open Lua console dialog.
 115
 116 -------------------------------------------------------------------------------
 117 Name:           flush-caches
 118 Managed By:     The scripting subsystem/backends
 119 Triggered When:
 120
 121  Elinks is going to free its caches.  This happens when the user chooses
 122  ACT_MAIN_CACHE_MINIMIZE, but currently also on ACT_MAIN_FORGET_CREDENTIALS
 123  and when ELinks is quitting.
 124
 125 Arguments:
 126
 127  None
 128
 129 Description:
 130
 131  If scripting backends hold pointers to cache entries, they should try
 132  to release those pointers so that ELinks can free the entries.  This
 133  may involve a full garbage collection.  Also, if backends have some
 134  caches of their own, they should flush them.
 135
 136 -------------------------------------------------------------------------------
 137 Name:           follow-url
 138 Managed By:     The scripting subsystem/backends
 139 Triggered When:
 140
 141  The user decides to load some document by following a link, entering an URL
 142  in the goto URL dialog, loading frames from a frameset (?) etc.
 143
 144 Arguments:
 145
 146  unsigned char **url, struct session *ses
 147
 148 Description:
 149
 150  If another URL than @url should be followed it is passed by setting @url.
 151  If @url is changed the event propagation should be ended.
 152  Valid values for @url includes:
 153  - unchanged, if the original URL should be followed;
 154  - a new, dynamically allocated URL to be followed instead; or
 155  - NULL or an empty, dynamically allocated string if no URL should be followed.
 156
 157 -------------------------------------------------------------------------------
 158 Name:           free-history
 159 Managed By:     The scripting subsystem/backends
 160 Triggered When:
 161
 162  ELinks exits
 163
 164 Arguments:
 165
 166  None
 167
 168 Description:
 169
 170  Allow a subsystem to free its history lists.
 171
 172 -------------------------------------------------------------------------------
 173 Name:           get-proxy
 174 Managed By:     The scripting subsystem/backends
 175 Triggered When:
 176
 177  Determining what proxy, if any, should be used to load a requested URL.
 178
 179 Arguments:
 180
 181  unsigned char **new_proxy_url, unsigned char *url
 182
 183 Description:
 184
 185  Possible values for @new_proxy_url includes:
 186  - a dynamically allocated string with the format proxy:port;
 187  - an empty string (dynamically allocated!) to use no proxy; or
 188  - NULL to use the default proxies.
 189
 190 -------------------------------------------------------------------------------
 191 Name:           goto-url
 192 Managed By:     The scripting subsystem/backends
 193 Triggered When:
 194
 195  The user enters something into the goto URL dialog.
 196
 197 Arguments:
 198
 199  unsigned char **url, struct session *ses
 200
 201 Description:
 202
 203  If a URL other than @url should be followed, the old one should be freed
 204  and the new one should be assigned to @url. @url must not be assigned
 205  NULL and must remain freeable.
 206  Valid values for @url are:
 207  - unchanged, if the original URL should be followed;
 208  - a new, dynamically allocated URL to be followed instead; or
 209  - NULL or an empty, dynamically allocated string if no URL should be followed.
 210
 211  @ses is usually used for deciding based on the current URI or for reporting
 212  potential errors during the hook processing through the UI. With @ses being
 213  NULL the hook handler should assume no current URI and no suitable UI set up
 214  (i.e., starting up yet or -dump).
 215
 216 -------------------------------------------------------------------------------
 217 Name:           periodic-saving
 218 Managed By:     No maintainer but used by lowlevel/timer.*
 219 Triggered When:
 220
 221  The interval timer configured through option goes off.
 222
 223 Arguments:
 224
 225  none
 226
 227 Description:
 228
 229  Makes it possible to periodically save files in ~/.elinks to disk.
 230
 231 -------------------------------------------------------------------------------
 232 Name:           pre-format-html
 233 Managed By:     The scripting subsystem/backends
 234 Triggered When:
 235
 236  A HTML document has been loaded - before the document rendering begins.
 237
 238 Arguments:
 239
 240  struct session *ses
 241  struct cache_entry *cached
 242
 243 Description:
 244
 245  Makes it possible to fix up bad HTML code, remove tags etc. The parameter
 246  cached is guaranteed to have a single fragment. The HTML source is changed
 247  by replacing this fragment:
 248
 249         add_fragment(cached, 0, new_string, new_len);
 250         normalize_cache_entry(cached, new_len);
 251
 252 -------------------------------------------------------------------------------
 253 Name:           quit
 254 Managed By:     The scripting subsystem/backends
 255 Triggered When:
 256
 257  ELinks quits
 258
 259 Arguments:
 260
 261  None
 262
 263 Description:
 264
 265  Allows a subsystem to do whatever clean-up is required when ELinks quits.
 266
 267 -------------------------------------------------------------------------------