1
2
3
4
5
6
7
8
9
10
11
12
13
14
15
16
17
18
19
20
21
22
23
24
25
26
27
28
29
30
31
32
33
34
35
36
37
38
39
40
41
42
43
44
45
46
47
48
49
50
51
52
53
54
55
56
57
58
59
60
61
62
63
64
65
66
67
68
69
70
71
72
73
74
75
76
77
78
79
80
81
82
83
84
85
86
87
88
89
90
91
92
93
94
95
96
97
98
99
100
101
102
103
104
105
106
107
108
109
110
111
112
113
114
115
116
117
118
119
120
121
122
123
124
125
126
127
128
|
\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}
|
