mirror of
https://github.com/rkd77/elinks.git
synced 2024-11-03 08:07:17 -05:00
ec1bedc25e
Document what happens if goto_url_hook or follow_url_hook returns None or "". doc/events.txt already explains the corresponding C values. [ commit message by me --KON ]
255 lines
9.7 KiB
Plaintext
255 lines
9.7 KiB
Plaintext
Python programmers can customize the behavior of ELinks by creating a Python
|
|
hooks module. The embedded Python interpreter provides an internal module
|
|
called elinks that can be used by the hooks module to create keystroke
|
|
bindings for Python code, obtain information about the document being
|
|
viewed, display simple dialog boxes and menus, load documents into the
|
|
ELinks cache, or display documents to the user. These two modules are
|
|
described below.
|
|
|
|
------------------------------------------------------------------------------
|
|
|
|
MODULE
|
|
hooks - Python hooks for ELinks.
|
|
|
|
DESCRIPTION
|
|
If ELinks is compiled with an embedded Python interpreter, it will try
|
|
to import a Python module called hooks when the browser starts up. To
|
|
use Python code from within ELinks, create a file called hooks.py in
|
|
the ~/.elinks directory, or in the system-wide configuration directory
|
|
(defined when ELinks was compiled), or in the standard Python search path.
|
|
An example hooks.py file can be found in the contrib/python directory of
|
|
the ELinks source distribution.
|
|
|
|
The hooks module may implement any of several functions that will be
|
|
called automatically by ELinks in appropriate circumstances; it may also
|
|
bind ELinks keystrokes to callable Python objects so that arbitrary Python
|
|
code can be invoked at the whim of the user.
|
|
|
|
Functions that will be automatically called by ELinks (if they're defined):
|
|
|
|
follow_url_hook() -- Rewrite a URL for a link that's about to be followed.
|
|
goto_url_hook() -- Rewrite a URL received from a "Go to URL" dialog box.
|
|
pre_format_html_hook() -- Rewrite a document's body before it's formatted.
|
|
proxy_for_hook() -- Determine what proxy server to use for a given URL.
|
|
quit_hook() -- Clean up before ELinks exits.
|
|
|
|
FUNCTIONS
|
|
follow_url_hook(url)
|
|
Rewrite a URL for a link that's about to be followed.
|
|
|
|
This function should return a string containing a URL for ELinks to
|
|
follow, or an empty string if no URL should be followed, or None if
|
|
ELinks should follow the original URL.
|
|
|
|
Arguments:
|
|
|
|
url -- The URL of the link.
|
|
|
|
goto_url_hook(url)
|
|
Rewrite a URL that was entered in a "Go to URL" dialog box.
|
|
|
|
This function should return a string containing a URL for ELinks to
|
|
follow, or an empty string if no URL should be followed, or None if
|
|
ELinks should follow the original URL.
|
|
|
|
Arguments:
|
|
|
|
url -- The URL provided by the user.
|
|
|
|
pre_format_html_hook(url, html)
|
|
Rewrite the body of a document before it's formatted.
|
|
|
|
This function should return a string for ELinks to format, or None
|
|
if ELinks should format the original document body. It can be used
|
|
to repair bad HTML, alter the layout or colors of a document, etc.
|
|
|
|
Arguments:
|
|
|
|
url -- The URL of the document.
|
|
html -- The body of the document.
|
|
|
|
proxy_for_hook(url)
|
|
Determine what proxy server to use for a given URL.
|
|
|
|
This function should return a string of the form "hostname:portnumber"
|
|
identifying a proxy server to use, or an empty string if the request
|
|
shouldn't use any proxy server, or None if ELinks should use its
|
|
default proxy server.
|
|
|
|
Arguments:
|
|
|
|
url -- The URL that is about to be followed.
|
|
|
|
quit_hook()
|
|
Clean up before ELinks exits.
|
|
|
|
This function should handle any clean-up tasks that need to be
|
|
performed before ELinks exits. Its return value is ignored.
|
|
|
|
------------------------------------------------------------------------------
|
|
|
|
MODULE
|
|
elinks - Interface to the ELinks web browser.
|
|
|
|
DESCRIPTION
|
|
Functions:
|
|
|
|
bind_key() -- Bind a keystroke to a callable object.
|
|
current_document() -- Return the body of the document being viewed.
|
|
current_header() -- Return the header of the document being viewed.
|
|
current_link_url() -- Return the URL of the currently selected link.
|
|
current_title() -- Return the title of the document being viewed.
|
|
current_url() -- Return the URL of the document being viewed.
|
|
info_box() -- Display information to the user.
|
|
input_box() -- Prompt for user input.
|
|
load() -- Load a document into the ELinks cache.
|
|
menu() -- Display a menu.
|
|
open() -- View a document.
|
|
|
|
Exception classes:
|
|
|
|
error -- Errors internal to ELinks.
|
|
|
|
Other public objects:
|
|
|
|
home -- A string containing the pathname of the ~/.elinks directory, or
|
|
None if ELinks has no configuration directory.
|
|
|
|
FUNCTIONS
|
|
bind_key(...)
|
|
bind_key(keystroke, callback[, keymap]) -> None
|
|
|
|
Bind a keystroke to a callable object.
|
|
|
|
Arguments:
|
|
|
|
keystroke -- A string containing a keystroke. The syntax for
|
|
keystrokes is described in the elinkskeys(5) man page.
|
|
callback -- A callable object to be called when the keystroke is
|
|
typed. It will be called without any arguments.
|
|
|
|
Optional arguments:
|
|
|
|
keymap -- A string containing the name of a keymap. Valid keymap
|
|
names can be found in the elinkskeys(5) man page. By
|
|
default the "main" keymap is used.
|
|
|
|
current_document(...)
|
|
current_document() -> string or None
|
|
|
|
If a document is being viewed, return its body; otherwise return None.
|
|
|
|
current_header(...)
|
|
current_header() -> string or None
|
|
|
|
If a document is being viewed and it has a header, return the header;
|
|
otherwise return None.
|
|
|
|
current_link_url(...)
|
|
current_link_url() -> string or None
|
|
|
|
If a link is selected, return its URL; otherwise return None.
|
|
|
|
current_title(...)
|
|
current_title() -> string or None
|
|
|
|
If a document is being viewed, return its title; otherwise return None.
|
|
|
|
current_url(...)
|
|
current_url() -> string or None
|
|
|
|
If a document is being viewed, return its URL; otherwise return None.
|
|
|
|
info_box(...)
|
|
info_box(text[, title]) -> None
|
|
|
|
Display information to the user in a dialog box.
|
|
|
|
Arguments:
|
|
|
|
text -- The text to be displayed in the dialog box. This argument can
|
|
be a string or any object that has a string representation as
|
|
returned by str(object).
|
|
|
|
Optional arguments:
|
|
|
|
title -- A string containing a title for the dialog box. By default
|
|
the string "Info" is used.
|
|
|
|
input_box(...)
|
|
input_box(prompt, callback, title="User dialog", initial="") -> None
|
|
|
|
Display a dialog box to prompt for user input.
|
|
|
|
Arguments:
|
|
|
|
prompt -- A string containing a prompt for the dialog box.
|
|
callback -- A callable object to be called after the dialog is
|
|
finished. It will be called with a single argument, which
|
|
will be either a string provided by the user or else None
|
|
if the user canceled the dialog.
|
|
|
|
Optional keyword arguments:
|
|
|
|
title -- A string containing a title for the dialog box. By default
|
|
the string "User dialog" is used.
|
|
initial -- A string containing an initial value for the text entry
|
|
field. By default the entry field is initially empty.
|
|
|
|
load(...)
|
|
load(url, callback) -> None
|
|
|
|
Load a document into the ELinks cache and pass its contents to a
|
|
callable object.
|
|
|
|
Arguments:
|
|
|
|
url -- A string containing the URL to load.
|
|
callback -- A callable object to be called after the document has
|
|
been loaded. It will be called with two arguments: the first
|
|
will be a string representing the document's header, or None
|
|
if it has no header; the second will be a string representing
|
|
the document's body, or None if it has no body.
|
|
|
|
menu(...)
|
|
menu(items[, type]) -> None
|
|
|
|
Display a menu.
|
|
|
|
Arguments:
|
|
|
|
items -- A sequence of tuples. Each tuple must have two elements: a
|
|
string containing the name of a menu item, and a callable
|
|
object that will be called without any arguments if the user
|
|
selects that menu item.
|
|
|
|
Optional arguments:
|
|
|
|
type -- A constant specifying the type of menu to display. By default
|
|
the menu is displayed at the top of the screen, but if this
|
|
argument's value is the constant elinks.MENU_TAB then the menu
|
|
is displayed in the same location as the ELinks tab menu. If
|
|
its value is the constant elinks.MENU_LINK then the menu is
|
|
displayed in the same location as the ELinks link menu and is
|
|
not displayed unless a link is currently selected.
|
|
|
|
open(...)
|
|
open(url, new_tab=False, background=False) -> None
|
|
|
|
View a document in either the current tab or a new tab.
|
|
|
|
Arguments:
|
|
|
|
url -- A string containing the URL to view.
|
|
|
|
Optional keyword arguments:
|
|
|
|
new_tab -- By default the URL is opened in the current tab. If this
|
|
argument's value is the boolean True then the URL is instead
|
|
opened in a new tab.
|
|
background -- By default a new tab is opened in the foreground. If
|
|
this argument's value is the boolean True then a new tab is
|
|
instead opened in the background. This argument is ignored
|
|
unless new_tab's value is True.
|
|
|