mirror of
https://github.com/rkd77/elinks.git
synced 2024-12-04 14:46:47 -05:00
248 lines
6.7 KiB
Plaintext
248 lines
6.7 KiB
Plaintext
Events
|
|
|
|
This file lists the events currently in use, when they are called, what they
|
|
do and what arguments they expect.
|
|
|
|
Events are a mechanism for communication between ELinks parts --- any ELinks
|
|
subsystem (module) can register an event, hook at an event or trigger an event.
|
|
Events are designed to allow transition to a completely message-passing model
|
|
internally, with modules talking to each other through the events.
|
|
|
|
Events are currently used primarily as a generic way to trigger event handlers
|
|
in various scripting backends.
|
|
|
|
Therefore, so far this reference sheet is useful mainly to scripting backends
|
|
developers and also scripting power users - it looks at the C side but usually
|
|
you get most (if not all) of it passed to the hook functions in your scripts.
|
|
|
|
|
|
|
|
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!
|
|
|
|
|
|
|
|
The list of events itself:
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: bookmark-delete
|
|
Managed By: The bookmarks subsystem
|
|
Triggered When:
|
|
|
|
A bookmark is being deleted.
|
|
|
|
Arguments:
|
|
|
|
struct bookmark *bookmark
|
|
|
|
Description:
|
|
|
|
Currently only used by the tab snapshotting code to avoid a dangling pointer
|
|
should the deleted bookmark be the folder to which it made the last snapshot.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: bookmark-move
|
|
Managed By: The bookmarks subsystem
|
|
Triggered When:
|
|
|
|
A bookmark is being moved.
|
|
|
|
Arguments:
|
|
|
|
struct bookmark *bookmark
|
|
struct bookmark *destination
|
|
|
|
Description:
|
|
|
|
The bookmark is moved immediately after the destination bookmark.
|
|
|
|
This is currently only used by the tab snapshotting code, which assumes
|
|
that when a user moves a bookmark, the user does not want the snapshotting
|
|
code to delete it when it makes the next snapshot.
|
|
|
|
-------------------------------------------------------------------------------
|
|
Name: bookmark-update
|
|
Managed By: The bookmarks subsystem
|
|
Triggered When:
|
|
|
|
The user finishes editing a bookmark.
|
|
|
|
Arguments:
|
|
|
|
struct bookmark *bookmark
|
|
unsigned char *new_title
|
|
unsigned char *new_url
|
|
|
|
Description:
|
|
|
|
This is triggered before the new title and URL are assigned to the bookmark.
|
|
Therefore, handlers can get the old title and URL from the bookmark structure
|
|
and the new title and URL from the event arguments.
|
|
|
|
This is currently only used by the tab snapshotting code, which assumes
|
|
that when a user edits a bookmark, the user does not want the snapshotting
|
|
code to delete it when it makes the next snapshot.
|
|
|
|
-------------------------------------------------------------------------------
|
|
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
|
|
(i.e., 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; or
|
|
- 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; or
|
|
- NULL to use the 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:
|
|
|
|
struct session *ses
|
|
struct cache_entry *cached
|
|
|
|
Description:
|
|
|
|
Makes it possible to fix up bad HTML code, remove tags etc. The parameter
|
|
cached is guaranteed to have a single fragment. The HTML source is changed
|
|
by replacing this fragment:
|
|
|
|
add_fragment(cached, 0, new_string, new_len);
|
|
normalize_cache_entry(cached, new_len);
|
|
|
|
-------------------------------------------------------------------------------
|
|
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.
|
|
|
|
-------------------------------------------------------------------------------
|