Initial commit of OpenSPARC T2 design and verification files.
[OpenSPARC-T2-DV] / tools / src / nas,5.n2.os.2 / lib / python / html / python / lib / module-webbrowser.html
CommitLineData
86530b38
AT
1<!DOCTYPE html PUBLIC "-//W3C//DTD HTML 4.0 Transitional//EN">
2<html>
3<head>
4<link rel="STYLESHEET" href="lib.css" type='text/css' />
5<link rel="SHORTCUT ICON" href="../icons/pyfav.png" type="image/png" />
6<link rel='start' href='../index.html' title='Python Documentation Index' />
7<link rel="first" href="lib.html" title='Python Library Reference' />
8<link rel='contents' href='contents.html' title="Contents" />
9<link rel='index' href='genindex.html' title='Index' />
10<link rel='last' href='about.html' title='About this document...' />
11<link rel='help' href='about.html' title='About this document...' />
12<link rel="next" href="module-cgi.html" />
13<link rel="prev" href="internet.html" />
14<link rel="parent" href="internet.html" />
15<link rel="next" href="browser-controllers.html" />
16<meta name='aesop' content='information' />
17<title>11.1 webbrowser -- Convenient Web-browser controller</title>
18</head>
19<body>
20<DIV CLASS="navigation">
21<div id='top-navigation-panel' xml:id='top-navigation-panel'>
22<table align="center" width="100%" cellpadding="0" cellspacing="2">
23<tr>
24<td class='online-navigation'><a rel="prev" title="11. Internet Protocols and"
25 href="internet.html"><img src='../icons/previous.png'
26 border='0' height='32' alt='Previous Page' width='32' /></A></td>
27<td class='online-navigation'><a rel="parent" title="11. Internet Protocols and"
28 href="internet.html"><img src='../icons/up.png'
29 border='0' height='32' alt='Up One Level' width='32' /></A></td>
30<td class='online-navigation'><a rel="next" title="11.1.1 Browser Controller Objects"
31 href="browser-controllers.html"><img src='../icons/next.png'
32 border='0' height='32' alt='Next Page' width='32' /></A></td>
33<td align="center" width="100%">Python Library Reference</td>
34<td class='online-navigation'><a rel="contents" title="Table of Contents"
35 href="contents.html"><img src='../icons/contents.png'
36 border='0' height='32' alt='Contents' width='32' /></A></td>
37<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
38 border='0' height='32' alt='Module Index' width='32' /></a></td>
39<td class='online-navigation'><a rel="index" title="Index"
40 href="genindex.html"><img src='../icons/index.png'
41 border='0' height='32' alt='Index' width='32' /></A></td>
42</tr></table>
43<div class='online-navigation'>
44<b class="navlabel">Previous:</b>
45<a class="sectref" rel="prev" href="internet.html">11. Internet Protocols and</A>
46<b class="navlabel">Up:</b>
47<a class="sectref" rel="parent" href="internet.html">11. Internet Protocols and</A>
48<b class="navlabel">Next:</b>
49<a class="sectref" rel="next" href="browser-controllers.html">11.1.1 Browser Controller Objects</A>
50</div>
51<hr /></div>
52</DIV>
53<!--End of Navigation Panel-->
54
55<H1><A NAME="SECTION0013100000000000000000">
5611.1 <tt class="module">webbrowser</tt> --
57 Convenient Web-browser controller</A>
58</H1>
59
60<P>
61<A NAME="module-webbrowser"></A>
62
63<P>
64The <tt class="module">webbrowser</tt> module provides a very high-level interface to
65allow displaying Web-based documents to users. The controller objects
66are easy to use and are platform-independent. Under most
67circumstances, simply calling the <tt class="function">open()</tt> function from this
68module will do the right thing.
69
70<P>
71Under <span class="Unix">Unix</span>, graphical browsers are preferred under X11, but text-mode
72browsers will be used if graphical browsers are not available or an X11
73display isn't available. If text-mode browsers are used, the calling
74process will block until the user exits the browser.
75
76<P>
77Under <span class="Unix">Unix</span>, if the environment variable <a class="envvar" id='l2h-3147' xml:id='l2h-3147'>BROWSER</a> exists, it
78is interpreted to override the platform default list of browsers, as a
79colon-separated list of browsers to try in order. When the value of
80a list part contains the string <code>%s</code>, then it is interpreted as
81a literal browser command line to be used with the argument URL
82substituted for the <code>%s</code>; if the part does not contain
83<code>%s</code>, it is simply interpreted as the name of the browser to
84launch.
85
86<P>
87For non-<span class="Unix">Unix</span> platforms, or when X11 browsers are available on
88<span class="Unix">Unix</span>, the controlling process will not wait for the user to finish
89with the browser, but allow the browser to maintain its own window on
90the display.
91
92<P>
93The following exception is defined:
94
95<P>
96<dl><dt><b><span class="typelabel">exception</span>&nbsp;<tt id='l2h-3142' xml:id='l2h-3142' class="exception">Error</tt></b></dt>
97<dd>
98 Exception raised when a browser control error occurs.
99</dd></dl>
100
101<P>
102The following functions are defined:
103
104<P>
105<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
106 <td><nobr><b><tt id='l2h-3143' xml:id='l2h-3143' class="function">open</tt></b>(</nobr></td>
107 <td><var>url</var><big>[</big><var>, new=0</var><big>]</big><var></var><big>[</big><var>, autoraise=1</var><big>]</big><var></var>)</td></tr></table></dt>
108<dd>
109 Display <var>url</var> using the default browser. If <var>new</var> is true,
110 a new browser window is opened if possible. If <var>autoraise</var> is
111 true, the window is raised if possible (note that under many window
112 managers this will occur regardless of the setting of this variable).
113</dl>
114
115<P>
116<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
117 <td><nobr><b><tt id='l2h-3144' xml:id='l2h-3144' class="function">open_new</tt></b>(</nobr></td>
118 <td><var>url</var>)</td></tr></table></dt>
119<dd>
120 Open <var>url</var> in a new window of the default browser, if possible,
121 otherwise, open <var>url</var> in the only browser window.
122</dl>
123
124<P>
125<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
126 <td><nobr><b><tt id='l2h-3145' xml:id='l2h-3145' class="function">get</tt></b>(</nobr></td>
127 <td><var></var><big>[</big><var>name</var><big>]</big><var></var>)</td></tr></table></dt>
128<dd>
129 Return a controller object for the browser type <var>name</var>. If
130 <var>name</var> is empty, return a controller for a default browser
131 appropriate to the caller's environment.
132</dl>
133
134<P>
135<dl><dt><table cellpadding="0" cellspacing="0"><tr valign="baseline">
136 <td><nobr><b><tt id='l2h-3146' xml:id='l2h-3146' class="function">register</tt></b>(</nobr></td>
137 <td><var>name, constructor</var><big>[</big><var>, instance</var><big>]</big><var></var>)</td></tr></table></dt>
138<dd>
139 Register the browser type <var>name</var>. Once a browser type is
140 registered, the <tt class="function">get()</tt> function can return a controller
141 for that browser type. If <var>instance</var> is not provided, or is
142 <code>None</code>, <var>constructor</var> will be called without parameters to
143 create an instance when needed. If <var>instance</var> is provided,
144 <var>constructor</var> will never be called, and may be <code>None</code>.
145
146<P>
147This entry point is only useful if you plan to either set the
148 <a class="envvar" id='l2h-3148' xml:id='l2h-3148'>BROWSER</a> variable or call <tt class="function">get</tt> with a nonempty
149 argument matching the name of a handler you declare.
150</dl>
151
152<P>
153A number of browser types are predefined. This table gives the type
154names that may be passed to the <tt class="function">get()</tt> function and the
155corresponding instantiations for the controller classes, all defined
156in this module.
157
158<P>
159<div class="center"><table class="realtable">
160 <thead>
161 <tr>
162 <th class="left" >Type Name</th>
163 <th class="left" >Class Name</th>
164 <th class="center">Notes</th>
165 </tr>
166 </thead>
167 <tbody>
168 <tr><td class="left" valign="baseline"><code>'mozilla'</code></td>
169 <td class="left" ><tt class="class">Netscape('mozilla')</tt></td>
170 <td class="center"></td></tr>
171 <tr><td class="left" valign="baseline"><code>'netscape'</code></td>
172 <td class="left" ><tt class="class">Netscape('netscape')</tt></td>
173 <td class="center"></td></tr>
174 <tr><td class="left" valign="baseline"><code>'mosaic'</code></td>
175 <td class="left" ><tt class="class">GenericBrowser('mosaic %s &amp;')</tt></td>
176 <td class="center"></td></tr>
177 <tr><td class="left" valign="baseline"><code>'kfm'</code></td>
178 <td class="left" ><tt class="class">Konqueror()</tt></td>
179 <td class="center">(1)</td></tr>
180 <tr><td class="left" valign="baseline"><code>'grail'</code></td>
181 <td class="left" ><tt class="class">Grail()</tt></td>
182 <td class="center"></td></tr>
183 <tr><td class="left" valign="baseline"><code>'links'</code></td>
184 <td class="left" ><tt class="class">GenericBrowser('links %s')</tt></td>
185 <td class="center"></td></tr>
186 <tr><td class="left" valign="baseline"><code>'lynx'</code></td>
187 <td class="left" ><tt class="class">GenericBrowser('lynx %s')</tt></td>
188 <td class="center"></td></tr>
189 <tr><td class="left" valign="baseline"><code>'w3m'</code></td>
190 <td class="left" ><tt class="class">GenericBrowser('w3m %s')</tt></td>
191 <td class="center"></td></tr>
192 <tr><td class="left" valign="baseline"><code>'windows-default'</code></td>
193 <td class="left" ><tt class="class">WindowsDefault</tt></td>
194 <td class="center">(2)</td></tr>
195 <tr><td class="left" valign="baseline"><code>'internet-config'</code></td>
196 <td class="left" ><tt class="class">InternetConfig</tt></td>
197 <td class="center">(3)</td></tr></tbody>
198</table></div>
199
200<P>
201Notes:
202
203<P>
204<DL>
205<DT><STRONG>(1)</STRONG></DT>
206<DD>``Konqueror'' is the file manager for the KDE desktop environment for
207UNIX, and only makes sense to use if KDE is running. Some way of
208reliably detecting KDE would be nice; the <a class="envvar" id='l2h-3149' xml:id='l2h-3149'>KDEDIR</a> variable is
209not sufficient. Note also that the name ``kfm'' is used even when
210using the <b class="program">konqueror</b> command with KDE 2 -- the
211implementation selects the best strategy for running Konqueror.
212
213<P>
214</DD>
215<DT><STRONG>(2)</STRONG></DT>
216<DD>Only on Windows platforms; requires the common
217extension modules <tt class="module">win32api</tt> and <tt class="module">win32con</tt>.
218
219<P>
220</DD>
221<DT><STRONG>(3)</STRONG></DT>
222<DD>Only on MacOS platforms; requires the standard MacPython <tt class="module">ic</tt>
223module, described in the <em class="citetitle"><a
224 href="../mac/module-ic.html"
225 title="Macintosh
226Library Modules"
227 >Macintosh
228Library Modules</a></em> manual.
229</DD>
230</DL>
231
232<P>
233
234<p><br /></p><hr class='online-navigation' />
235<div class='online-navigation'>
236<!--Table of Child-Links-->
237<A NAME="CHILD_LINKS"><STRONG>Subsections</STRONG></a>
238
239<UL CLASS="ChildLinks">
240<LI><A href="browser-controllers.html">11.1.1 Browser Controller Objects</a>
241</ul>
242<!--End of Table of Child-Links-->
243</div>
244
245<DIV CLASS="navigation">
246<div class='online-navigation'>
247<p></p><hr />
248<table align="center" width="100%" cellpadding="0" cellspacing="2">
249<tr>
250<td class='online-navigation'><a rel="prev" title="11. Internet Protocols and"
251 href="internet.html"><img src='../icons/previous.png'
252 border='0' height='32' alt='Previous Page' width='32' /></A></td>
253<td class='online-navigation'><a rel="parent" title="11. Internet Protocols and"
254 href="internet.html"><img src='../icons/up.png'
255 border='0' height='32' alt='Up One Level' width='32' /></A></td>
256<td class='online-navigation'><a rel="next" title="11.1.1 Browser Controller Objects"
257 href="browser-controllers.html"><img src='../icons/next.png'
258 border='0' height='32' alt='Next Page' width='32' /></A></td>
259<td align="center" width="100%">Python Library Reference</td>
260<td class='online-navigation'><a rel="contents" title="Table of Contents"
261 href="contents.html"><img src='../icons/contents.png'
262 border='0' height='32' alt='Contents' width='32' /></A></td>
263<td class='online-navigation'><a href="modindex.html" title="Module Index"><img src='../icons/modules.png'
264 border='0' height='32' alt='Module Index' width='32' /></a></td>
265<td class='online-navigation'><a rel="index" title="Index"
266 href="genindex.html"><img src='../icons/index.png'
267 border='0' height='32' alt='Index' width='32' /></A></td>
268</tr></table>
269<div class='online-navigation'>
270<b class="navlabel">Previous:</b>
271<a class="sectref" rel="prev" href="internet.html">11. Internet Protocols and</A>
272<b class="navlabel">Up:</b>
273<a class="sectref" rel="parent" href="internet.html">11. Internet Protocols and</A>
274<b class="navlabel">Next:</b>
275<a class="sectref" rel="next" href="browser-controllers.html">11.1.1 Browser Controller Objects</A>
276</div>
277</div>
278<hr />
279<span class="release-info">Release 2.4.2, documentation updated on 28 September 2005.</span>
280</DIV>
281<!--End of Navigation Panel-->
282<ADDRESS>
283See <i><a href="about.html">About this document...</a></i> for information on suggesting changes.
284</ADDRESS>
285</BODY>
286</HTML>