3 This file lists the events currently in use, when they are called, what they
4 do and what arguments they expect.
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.
11 Events are currently used primarily as a generic way to trigger event handlers
12 in various scripting backends.
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.
20 Below is a template showing how to read the event information
23 Managed By: <what part of the code registers and unregister the event>
26 <short description of when the event is triggered>
30 <the order and type of the arguments>
34 <description of the arguments, what the event does etc.>
36 Please keep in alphabetical order!
40 The list of events itself:
42 -------------------------------------------------------------------------------
44 Managed By: The bookmarks subsystem
47 A bookmark is being deleted.
51 struct bookmark *bookmark
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.
58 -------------------------------------------------------------------------------
60 Managed By: The bookmarks subsystem
63 A bookmark is being moved.
67 struct bookmark *bookmark
68 struct bookmark *destination
72 The bookmark is moved immediately after the destination bookmark.
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.
78 -------------------------------------------------------------------------------
80 Managed By: The bookmarks subsystem
83 The user finishes editing a bookmark.
87 struct bookmark *bookmark
88 unsigned char *new_title
89 unsigned char *new_url
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.
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.
101 -------------------------------------------------------------------------------
102 Name: dialog-lua-console
103 Managed By: The Lua scripting subsystem/backend
106 The user hits a key associated with 'lua-console' action.
114 Open Lua console dialog.
116 -------------------------------------------------------------------------------
118 Managed By: The scripting subsystem/backends
121 The user decides to load some document by following a link, entering a URL
122 in the goto URL dialog, loading frames from a frameset (?) etc.
126 unsigned char **url, struct session *ses
130 If another URL than @url should be followed it is passed by setting @url.
131 If @url is changed the event propagation should be ended.
132 Valid values for @url includes:
133 - unchanged, if the original URL should be followed;
134 - a new, dynamically allocated URL to be followed instead; or
135 - NULL or an empty, dynamically allocated string if no URL should be followed.
137 -------------------------------------------------------------------------------
139 Managed By: The scripting subsystem/backends
150 Allow a subsystem to free its history lists.
152 -------------------------------------------------------------------------------
154 Managed By: The scripting subsystem/backends
157 Determining what proxy, if any, should be used to load a requested URL.
161 unsigned char **new_proxy_url, unsigned char *url
165 Possible values for @new_proxy_url includes:
166 - a dynamically allocated string with the format proxy:port;
167 - an empty string (dynamically allocated!) to use no proxy; or
168 - NULL to use the default proxies.
170 -------------------------------------------------------------------------------
172 Managed By: The scripting subsystem/backends
175 The user enters something into the goto URL dialog.
179 unsigned char **url, struct session *ses
183 If a URL other than @url should be followed, the old one should be freed
184 and the new one should be assigned to @url. @url must not be assigned
185 NULL and must remain freeable.
186 Valid values for @url are:
187 - unchanged, if the original URL should be followed;
188 - a new, dynamically allocated URL to be followed instead; or
189 - NULL or an empty, dynamically allocated string if no URL should be followed.
191 @ses is usually used for deciding based on the current URI or for reporting
192 potential errors during the hook processing through the UI. With @ses being
193 NULL the hook handler should assume no current URI and no suitable UI set up
194 (i.e., starting up yet or -dump).
196 -------------------------------------------------------------------------------
197 Name: periodic-saving
198 Managed By: No maintainer but used by lowlevel/timer.*
201 The interval timer configured through option goes off.
209 Makes it possible to periodically save files in ~/.elinks to disk.
211 -------------------------------------------------------------------------------
212 Name: pre-format-html
213 Managed By: The scripting subsystem/backends
216 A HTML document has been loaded - before the document rendering begins.
221 struct cache_entry *cached
225 Makes it possible to fix up bad HTML code, remove tags etc. The parameter
226 cached is guaranteed to have a single fragment. The HTML source is changed
227 by replacing this fragment:
229 add_fragment(cached, 0, new_string, new_len);
230 normalize_cache_entry(cached, new_len);
232 The caller must ensure that there is a reference to cached, so that
233 calling garbage_collection() from the event handler cannot free it.
235 -------------------------------------------------------------------------------
237 Managed By: The scripting subsystem/backends
248 Allows a subsystem to do whatever clean-up is required when ELinks quits.
250 -------------------------------------------------------------------------------