Bug 54: Don't force 8-bit characters and no parity.
[elinks/elinks-j605.git] / doc / events.txt
blob27cae9fd70c51ae24a7b4e44a9e3e4121bcb3079
1                                 Events
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
22 Name:           <event name>
23 Managed By:     <what part of the code registers and unregister the event>
24 Triggered When:
26  <short description of when the event is triggered>
28 Arguments:
30  <the order and type of the arguments>
32 Description:
34  <description of the arguments, what the event does etc.>
36 Please keep in alphabetical order!
40 The list of events itself:
42 -------------------------------------------------------------------------------
43 Name:           bookmark-delete
44 Managed By:     The bookmarks subsystem
45 Triggered When:
47  A bookmark is being deleted.
49 Arguments:
51  struct bookmark *bookmark
53 Description:
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 -------------------------------------------------------------------------------
59 Name:           bookmark-move
60 Managed By:     The bookmarks subsystem
61 Triggered When:
63  A bookmark is being moved.
65 Arguments:
67  struct bookmark *bookmark
68  struct bookmark *destination
70 Description:
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 -------------------------------------------------------------------------------
79 Name:           bookmark-update
80 Managed By:     The bookmarks subsystem
81 Triggered When:
83  The user finishes editing a bookmark.
85 Arguments:
87  struct bookmark *bookmark
88  unsigned char *new_title
89  unsigned char *new_url
91 Description:
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
104 Triggered When:
106  The user hits a key associated with 'lua-console' action.
108 Arguments:
110  struct session *ses
112 Description:
114  Open Lua console dialog.
116 -------------------------------------------------------------------------------
117 Name:           flush-caches
118 Managed By:     The scripting subsystem/backends
119 Triggered When:
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.
125 Arguments:
127  None
129 Description:
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.
136 -------------------------------------------------------------------------------
137 Name:           follow-url
138 Managed By:     The scripting subsystem/backends
139 Triggered When:
141  The user decides to load some document by following a link, entering a URL
142  in the goto URL dialog, loading frames from a frameset (?) etc.
144 Arguments:
146  unsigned char **url, struct session *ses
148 Description:
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  - leaving @url unchanged if the original URL should be followed;
154  - NULL if no URL should be followed; or
155  - a dynamically allocated new URL to be followed instead.
157 -------------------------------------------------------------------------------
158 Name:           free-history
159 Managed By:     The scripting subsystem/backends
160 Triggered When:
162  ELinks exits
164 Arguments:
166  None
168 Description:
170  Allow a subsystem to free its history lists.
172 -------------------------------------------------------------------------------
173 Name:           get-proxy
174 Managed By:     The scripting subsystem/backends
175 Triggered When:
177  Determining what proxy, if any, should be used to load a requested URL.
179 Arguments:
181  unsigned char **new_proxy_url, unsigned char *url
183 Description:
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.
190 -------------------------------------------------------------------------------
191 Name:           goto-url
192 Managed By:     The scripting subsystem/backends
193 Triggered When:
195  The user enters something into the goto URL dialog.
197 Arguments:
199  unsigned char **url, struct session *ses
201 Description:
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  - an empty string, if no URL should be followed.
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).
216 -------------------------------------------------------------------------------
217 Name:           periodic-saving
218 Managed By:     No maintainer but used by lowlevel/timer.*
219 Triggered When:
221  The interval timer configured through option goes off.
223 Arguments:
225  none
227 Description:
229  Makes it possible to periodically save files in ~/.elinks to disk.
231 -------------------------------------------------------------------------------
232 Name:           pre-format-html
233 Managed By:     The scripting subsystem/backends
234 Triggered When:
236  A HTML document has been loaded - before the document rendering begins.
238 Arguments:
240  struct session *ses
241  struct cache_entry *cached
243 Description:
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:
249         add_fragment(cached, 0, new_string, new_len);
250         normalize_cache_entry(cached, new_len);
252 -------------------------------------------------------------------------------
253 Name:           quit
254 Managed By:     The scripting subsystem/backends
255 Triggered When:
257  ELinks quits
259 Arguments:
261  None
263 Description:
265  Allows a subsystem to do whatever clean-up is required when ELinks quits.
267 -------------------------------------------------------------------------------