129 lines
5.2 KiB
TeX
129 lines
5.2 KiB
TeX
\section{\module{webbrowser} ---
|
|
Convenient Web-browser controller}
|
|
|
|
\declaremodule{standard}{webbrowser}
|
|
\modulesynopsis{Easy-to-use controller for Web browsers.}
|
|
\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
|
|
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
|
|
|
|
The \module{webbrowser} module provides a very high-level interface to
|
|
allow displaying Web-based documents to users. The controller objects
|
|
are easy to use and are platform-independent. Under most
|
|
circumstances, simply calling the \function{open()} function from this
|
|
module will do the right thing.
|
|
|
|
Under \UNIX, graphical browsers are preferred under X11, but text-mode
|
|
browsers will be used if graphical browsers are not available or an X11
|
|
display isn't available. If text-mode browsers are used, the calling
|
|
process will block until the user exits the browser.
|
|
|
|
Under \UNIX, if the environment variable \envvar{BROWSER} exists, it
|
|
is interpreted to override the platform default list of browsers, as a
|
|
colon-separated list of browsers to try in order. When the value of
|
|
a list part contains the string \code{\%s}, then it is interpreted as
|
|
a literal browser command line to be used with the argument URL
|
|
substituted for the \code{\%s}; if the part does not contain
|
|
\code{\%s}, it is simply interpreted as the name of the browser to
|
|
launch.
|
|
|
|
For non-\UNIX{} platforms, or when X11 browsers are available on
|
|
\UNIX, the controlling process will not wait for the user to finish
|
|
with the browser, but allow the browser to maintain its own window on
|
|
the display.
|
|
|
|
The following exception is defined:
|
|
|
|
\begin{excdesc}{Error}
|
|
Exception raised when a browser control error occurs.
|
|
\end{excdesc}
|
|
|
|
The following functions are defined:
|
|
|
|
\begin{funcdesc}{open}{url\optional{, new=0}\optional{, autoraise=1}}
|
|
Display \var{url} using the default browser. If \var{new} is true,
|
|
a new browser window is opened if possible. If \var{autoraise} is
|
|
true, the window is raised if possible (note that under many window
|
|
managers this will occur regardless of the setting of this variable).
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{open_new}{url}
|
|
Open \var{url} in a new window of the default browser, if possible,
|
|
otherwise, open \var{url} in the only browser window.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{get}{\optional{name}}
|
|
Return a controller object for the browser type \var{name}. If
|
|
\var{name} is empty, return a controller for a default browser
|
|
appropriate to the caller's environment.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{register}{name, constructor\optional{, instance}}
|
|
Register the browser type \var{name}. Once a browser type is
|
|
registered, the \function{get()} function can return a controller
|
|
for that browser type. If \var{instance} is not provided, or is
|
|
\code{None}, \var{constructor} will be called without parameters to
|
|
create an instance when needed. If \var{instance} is provided,
|
|
\var{constructor} will never be called, and may be \code{None}.
|
|
|
|
This entry point is only useful if you plan to either set the
|
|
\envvar{BROWSER} variable or call \function{get} with a nonempty
|
|
argument matching the name of a handler you declare.
|
|
\end{funcdesc}
|
|
|
|
A number of browser types are predefined. This table gives the type
|
|
names that may be passed to the \function{get()} function and the
|
|
corresponding instantiations for the controller classes, all defined
|
|
in this module.
|
|
|
|
\begin{tableiii}{l|l|c}{code}{Type Name}{Class Name}{Notes}
|
|
\lineiii{'mozilla'}{\class{Netscape('mozilla')}}{}
|
|
\lineiii{'netscape'}{\class{Netscape('netscape')}}{}
|
|
\lineiii{'mosaic'}{\class{GenericBrowser('mosaic \%s \&')}}{}
|
|
\lineiii{'kfm'}{\class{Konqueror()}}{(1)}
|
|
\lineiii{'grail'}{\class{Grail()}}{}
|
|
\lineiii{'links'}{\class{GenericBrowser('links \%s')}}{}
|
|
\lineiii{'lynx'}{\class{GenericBrowser('lynx \%s')}}{}
|
|
\lineiii{'w3m'}{\class{GenericBrowser('w3m \%s')}}{}
|
|
\lineiii{'windows-default'}{\class{WindowsDefault}}{(2)}
|
|
\lineiii{'internet-config'}{\class{InternetConfig}}{(3)}
|
|
\end{tableiii}
|
|
|
|
\noindent
|
|
Notes:
|
|
|
|
\begin{description}
|
|
\item[(1)]
|
|
``Konqueror'' is the file manager for the KDE desktop environment for
|
|
UNIX, and only makes sense to use if KDE is running. Some way of
|
|
reliably detecting KDE would be nice; the \envvar{KDEDIR} variable is
|
|
not sufficient. Note also that the name ``kfm'' is used even when
|
|
using the \program{konqueror} command with KDE 2 --- the
|
|
implementation selects the best strategy for running Konqueror.
|
|
|
|
\item[(2)]
|
|
Only on Windows platforms; requires the common
|
|
extension modules \module{win32api} and \module{win32con}.
|
|
|
|
\item[(3)]
|
|
Only on MacOS platforms; requires the standard MacPython \module{ic}
|
|
module, described in the \citetitle[../mac/module-ic.html]{Macintosh
|
|
Library Modules} manual.
|
|
\end{description}
|
|
|
|
|
|
\subsection{Browser Controller Objects \label{browser-controllers}}
|
|
|
|
Browser controllers provide two methods which parallel two of the
|
|
module-level convenience functions:
|
|
|
|
\begin{funcdesc}{open}{url\optional{, new}}
|
|
Display \var{url} using the browser handled by this controller. If
|
|
\var{new} is true, a new browser window is opened if possible.
|
|
\end{funcdesc}
|
|
|
|
\begin{funcdesc}{open_new}{url}
|
|
Open \var{url} in a new window of the browser handled by this
|
|
controller, if possible, otherwise, open \var{url} in the only
|
|
browser window.
|
|
\end{funcdesc}
|