				Events

This file lists the events currently in use. When they are called, what they
do and what arguments they expect.

Below is a template showing how to read the event information

Name:		<event name>
Managed By:	<what part of the code registers and unregister the event>
Arguments:

 <the order and type of the arguments>

Triggered When:

 <short description of when the event is triggered>

Description:

 <description of the arguments, what the event does etc.>

Please keep in alphabetical order!

-------------------------------------------------------------------------------
Name:		dialog-lua-console
Managed By:	The Lua scripting subsystem/backend
Triggered When:

 The user hits a key associated with 'lua-console' action.

Arguments:

 struct session *ses

Description:

 Open Lua console dialog.

-------------------------------------------------------------------------------
Name:		free-history
Managed By:	The scripting subsystem/backends
Triggered When:

 ELinks exits

Arguments:

 None

Description:

 Allow a subsystem to free its history lists.

-------------------------------------------------------------------------------
Name:		goto-url
Managed By:	The scripting subsystem/backends
Triggered When:

 The user enters something into the goto URL dialog.

Arguments:

 unsigned char **url, struct session *ses

Description:

 If a URL other than @url should be followed, the old one should be freed
 and the new one should be assigned to @url. @url must not be assigned
 NULL and must remain freeable.
 Valid values for @url are:
 - unchanged, if the original URL should be followed;
 - a new, dynamically allocated URL to be followed instead; or
 - an empty string, if no URL should be followed.

 @ses is usually used for deciding based on the current URI or for reporting
 potential errors during the hook processing through the UI. With @ses being
 NULL the hook handler should assume no current URI and no suitable UI set up
 (ie. starting up yet or -dump).

-------------------------------------------------------------------------------
Name:		follow-url
Managed By:	The scripting subsystem/backends
Triggered When:

 The user decides to load some document by following a link, entering an URL
 in the goto URL dialog, loading frames from a frameset (?) etc.

Arguments:

 unsigned char **url, struct session *ses

Description:

 If another URL than @url should be followed it is passed by setting @url.
 If @url is changed the event propagation should be ended.
 Valid values for @url includes:
 - leaving @url unchanged if the original URL should be followed.
 - NULL if no URL should be followed.
 - a dynamically allocated new URL to be followed instead.

-------------------------------------------------------------------------------
Name:		get-proxy
Managed By:	The scripting subsystem/backends
Triggered When:

 Determining what proxy, if any, should be used to load a requested URL.

Arguments:

 unsigned char **new_proxy_url, unsigned char *url

Description:

 Possible values for @new_proxy_url includes:
 - a dynamically allocated string with the format proxy:port
 - an empty string (dynamically allocated!) to use no proxy
 - NULL to use default proxies

-------------------------------------------------------------------------------
Name:		periodic-saving
Managed By:	No maintainer but used by lowlevel/timer.*
Triggered When:

 The interval timer configured through option goes off.

Arguments:

 none

Description:

 Makes it possible to periodically save files in ~/.elinks to disk.

-------------------------------------------------------------------------------
Name:		pre-format-html
Managed By:	The scripting subsystem/backends
Triggered When:

 A HTML document has been loaded - before the document rendering begins.

Arguments:

 unsigned char **html, int *html_len, struct session *ses, unsigned char *url

Description:

 Makes it possible to fix up bad HTML code, remove tags etc.  The HTML source
 is changed by making @html point to the new source.  If @html is changed the
 event propagation should be ended and @html_len should be updated to the new
 length of the document content.
 Possible values for @html includes:
 - new document content in a dynamically allocated string.
 - NULL to keep the content unchanged.

-------------------------------------------------------------------------------
Name:		quit
Managed By:	The scripting subsystem/backends
Triggered When:

 ELinks quits

Arguments:

 None

Description:

 Allows a subsystem to do whatever clean up is required when ELinks quits.

-------------------------------------------------------------------------------
$Id: events.txt,v 1.12 2004/07/16 18:33:45 jonas Exp $
