Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 1 | \section{\module{webbrowser} --- |
| 2 | Convenient Web-browser controller} |
| 3 | |
| 4 | \declaremodule{standard}{webbrowser} |
| 5 | \modulesynopsis{Easy-to-use controller for Web browsers.} |
| 6 | \moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
| 7 | \sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org} |
| 8 | |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 9 | The \module{webbrowser} module provides a high-level interface to |
| 10 | allow displaying Web-based documents to users. Under most |
Eric S. Raymond | f79cb2d | 2001-01-23 13:49:44 +0000 | [diff] [blame] | 11 | circumstances, simply calling the \function{open()} function from this |
| 12 | module will do the right thing. |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 13 | |
Neal Norwitz | 178f906 | 2005-10-04 03:31:01 +0000 | [diff] [blame] | 14 | Under \UNIX{}, graphical browsers are preferred under X11, but text-mode |
Fred Drake | f6791f3 | 2000-10-02 03:42:43 +0000 | [diff] [blame] | 15 | browsers will be used if graphical browsers are not available or an X11 |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 16 | display isn't available. If text-mode browsers are used, the calling |
| 17 | process will block until the user exits the browser. |
| 18 | |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 19 | If the environment variable \envvar{BROWSER} exists, it |
Eric S. Raymond | f79cb2d | 2001-01-23 13:49:44 +0000 | [diff] [blame] | 20 | is interpreted to override the platform default list of browsers, as a |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 21 | os.pathsep-separated list of browsers to try in order. When the value of |
Georg Brandl | 23929f2 | 2006-01-20 21:03:35 +0000 | [diff] [blame] | 22 | a list part contains the string \code{\%s}, then it is |
| 23 | interpreted as a literal browser command line to be used with the argument URL |
| 24 | substituted for \code{\%s}; if the part does not contain |
Eric S. Raymond | f7f1851 | 2001-01-23 13:16:32 +0000 | [diff] [blame] | 25 | \code{\%s}, it is simply interpreted as the name of the browser to |
| 26 | launch. |
| 27 | |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 28 | For non-\UNIX{} platforms, or when a remote browser is available on |
Neal Norwitz | 178f906 | 2005-10-04 03:31:01 +0000 | [diff] [blame] | 29 | \UNIX{}, the controlling process will not wait for the user to finish |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 30 | with the browser, but allow the remote browser to maintain its own |
Neal Norwitz | 178f906 | 2005-10-04 03:31:01 +0000 | [diff] [blame] | 31 | windows on the display. If remote browsers are not available on \UNIX{}, |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 32 | the controlling process will launch a new browser and wait. |
| 33 | |
| 34 | The script \program{webbrowser} can be used as a command-line interface |
| 35 | for the module. It accepts an URL as the argument. It accepts the following |
| 36 | optional parameters: \programopt{-n} opens the URL in a new browser window, |
| 37 | if possible; \programopt{-t} opens the URL in a new browser page ("tab"). The |
| 38 | options are, naturally, mutually exclusive. |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 39 | |
| 40 | The following exception is defined: |
| 41 | |
| 42 | \begin{excdesc}{Error} |
| 43 | Exception raised when a browser control error occurs. |
| 44 | \end{excdesc} |
| 45 | |
| 46 | The following functions are defined: |
| 47 | |
Neal Norwitz | 178f906 | 2005-10-04 03:31:01 +0000 | [diff] [blame] | 48 | \begin{funcdesc}{open}{url\optional{, new=0\optional{, autoraise=1}}} |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 49 | Display \var{url} using the default browser. If \var{new} is 0, the |
| 50 | \var{url} is opened in the same browser window. If \var{new} is 1, |
| 51 | a new browser window is opened if possible. If \var{new} is 2, |
| 52 | a new browser page ("tab") is opened if possible. If \var{autoraise} is |
Eric S. Raymond | f79cb2d | 2001-01-23 13:49:44 +0000 | [diff] [blame] | 53 | true, the window is raised if possible (note that under many window |
| 54 | managers this will occur regardless of the setting of this variable). |
Georg Brandl | 23929f2 | 2006-01-20 21:03:35 +0000 | [diff] [blame] | 55 | \versionchanged[\var{new} can now be 2]{2.5} |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 56 | \end{funcdesc} |
| 57 | |
Neal Norwitz | 178f906 | 2005-10-04 03:31:01 +0000 | [diff] [blame] | 58 | \begin{funcdesc}{open_new}{url} |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 59 | Open \var{url} in a new window of the default browser, if possible, |
Neal Norwitz | 178f906 | 2005-10-04 03:31:01 +0000 | [diff] [blame] | 60 | otherwise, open \var{url} in the only browser window. |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 61 | \end{funcdesc} |
| 62 | |
| 63 | \begin{funcdesc}{open_new_tab}{url} |
| 64 | Open \var{url} in a new page ("tab") of the default browser, if possible, |
Neal Norwitz | 178f906 | 2005-10-04 03:31:01 +0000 | [diff] [blame] | 65 | otherwise equivalent to \function{open_new}. |
| 66 | \versionadded{2.5} |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 67 | \end{funcdesc} |
| 68 | |
| 69 | \begin{funcdesc}{get}{\optional{name}} |
Eric S. Raymond | f7f1851 | 2001-01-23 13:16:32 +0000 | [diff] [blame] | 70 | Return a controller object for the browser type \var{name}. If |
| 71 | \var{name} is empty, return a controller for a default browser |
Eric S. Raymond | aeb5532 | 2001-01-23 13:22:28 +0000 | [diff] [blame] | 72 | appropriate to the caller's environment. |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 73 | \end{funcdesc} |
| 74 | |
Fred Drake | 246f65f | 2000-10-23 15:41:13 +0000 | [diff] [blame] | 75 | \begin{funcdesc}{register}{name, constructor\optional{, instance}} |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 76 | Register the browser type \var{name}. Once a browser type is |
| 77 | registered, the \function{get()} function can return a controller |
| 78 | for that browser type. If \var{instance} is not provided, or is |
| 79 | \code{None}, \var{constructor} will be called without parameters to |
| 80 | create an instance when needed. If \var{instance} is provided, |
| 81 | \var{constructor} will never be called, and may be \code{None}. |
Eric S. Raymond | f7f1851 | 2001-01-23 13:16:32 +0000 | [diff] [blame] | 82 | |
| 83 | This entry point is only useful if you plan to either set the |
| 84 | \envvar{BROWSER} variable or call \function{get} with a nonempty |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 85 | argument matching the name of a handler you declare. |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 86 | \end{funcdesc} |
| 87 | |
Eric S. Raymond | f79cb2d | 2001-01-23 13:49:44 +0000 | [diff] [blame] | 88 | A number of browser types are predefined. This table gives the type |
| 89 | names that may be passed to the \function{get()} function and the |
| 90 | corresponding instantiations for the controller classes, all defined |
| 91 | in this module. |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 92 | |
| 93 | \begin{tableiii}{l|l|c}{code}{Type Name}{Class Name}{Notes} |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 94 | \lineiii{'mozilla'}{\class{Mozilla('mozilla')}}{} |
| 95 | \lineiii{'firefox'}{\class{Mozilla('mozilla')}}{} |
| 96 | \lineiii{'netscape'}{\class{Mozilla('netscape')}}{} |
| 97 | \lineiii{'galeon'}{\class{Galeon('galeon')}}{} |
| 98 | \lineiii{'epiphany'}{\class{Galeon('epiphany')}}{} |
Georg Brandl | 23929f2 | 2006-01-20 21:03:35 +0000 | [diff] [blame] | 99 | \lineiii{'skipstone'}{\class{BackgroundBrowser('skipstone')}}{} |
| 100 | \lineiii{'kfmclient'}{\class{Konqueror()}}{(1)} |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 101 | \lineiii{'konqueror'}{\class{Konqueror()}}{(1)} |
Eric S. Raymond | f79cb2d | 2001-01-23 13:49:44 +0000 | [diff] [blame] | 102 | \lineiii{'kfm'}{\class{Konqueror()}}{(1)} |
Georg Brandl | 23929f2 | 2006-01-20 21:03:35 +0000 | [diff] [blame] | 103 | \lineiii{'mosaic'}{\class{BackgroundBrowser('mosaic')}}{} |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 104 | \lineiii{'opera'}{\class{Opera()}}{} |
Eric S. Raymond | f79cb2d | 2001-01-23 13:49:44 +0000 | [diff] [blame] | 105 | \lineiii{'grail'}{\class{Grail()}}{} |
Georg Brandl | 23929f2 | 2006-01-20 21:03:35 +0000 | [diff] [blame] | 106 | \lineiii{'links'}{\class{GenericBrowser('links')}}{} |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 107 | \lineiii{'elinks'}{\class{Elinks('elinks')}}{} |
Georg Brandl | 23929f2 | 2006-01-20 21:03:35 +0000 | [diff] [blame] | 108 | \lineiii{'lynx'}{\class{GenericBrowser('lynx')}}{} |
| 109 | \lineiii{'w3m'}{\class{GenericBrowser('w3m')}}{} |
Fred Drake | c826ecb | 2000-07-07 17:08:40 +0000 | [diff] [blame] | 110 | \lineiii{'windows-default'}{\class{WindowsDefault}}{(2)} |
| 111 | \lineiii{'internet-config'}{\class{InternetConfig}}{(3)} |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 112 | \lineiii{'macosx'}{\class{MacOSX('default')}}{(4)} |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 113 | \end{tableiii} |
| 114 | |
| 115 | \noindent |
| 116 | Notes: |
| 117 | |
| 118 | \begin{description} |
| 119 | \item[(1)] |
Eric S. Raymond | f79cb2d | 2001-01-23 13:49:44 +0000 | [diff] [blame] | 120 | ``Konqueror'' is the file manager for the KDE desktop environment for |
Neal Norwitz | 178f906 | 2005-10-04 03:31:01 +0000 | [diff] [blame] | 121 | \UNIX{}, and only makes sense to use if KDE is running. Some way of |
Fred Drake | f6791f3 | 2000-10-02 03:42:43 +0000 | [diff] [blame] | 122 | reliably detecting KDE would be nice; the \envvar{KDEDIR} variable is |
Fred Drake | 21e036c | 2001-03-26 16:17:21 +0000 | [diff] [blame] | 123 | not sufficient. Note also that the name ``kfm'' is used even when |
| 124 | using the \program{konqueror} command with KDE 2 --- the |
| 125 | implementation selects the best strategy for running Konqueror. |
Fred Drake | c826ecb | 2000-07-07 17:08:40 +0000 | [diff] [blame] | 126 | |
| 127 | \item[(2)] |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 128 | Only on Windows platforms. |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 129 | |
Fred Drake | c826ecb | 2000-07-07 17:08:40 +0000 | [diff] [blame] | 130 | \item[(3)] |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 131 | Only on MacOS platforms; requires the standard MacPython \module{ic} |
| 132 | module, described in the \citetitle[../mac/module-ic.html]{Macintosh |
| 133 | Library Modules} manual. |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 134 | |
| 135 | \item[(4)] |
| 136 | Only on MacOS X platform. |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 137 | \end{description} |
| 138 | |
| 139 | |
| 140 | \subsection{Browser Controller Objects \label{browser-controllers}} |
| 141 | |
| 142 | Browser controllers provide two methods which parallel two of the |
| 143 | module-level convenience functions: |
| 144 | |
Neal Norwitz | 178f906 | 2005-10-04 03:31:01 +0000 | [diff] [blame] | 145 | \begin{funcdesc}{open}{url\optional{, new\optional{, autoraise=1}}} |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 146 | Display \var{url} using the browser handled by this controller. |
| 147 | If \var{new} is 1, a new browser window is opened if possible. |
| 148 | If \var{new} is 2, a new browser page ("tab") is opened if possible. |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 149 | \end{funcdesc} |
| 150 | |
Neal Norwitz | 178f906 | 2005-10-04 03:31:01 +0000 | [diff] [blame] | 151 | \begin{funcdesc}{open_new}{url} |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 152 | Open \var{url} in a new window of the browser handled by this |
| 153 | controller, if possible, otherwise, open \var{url} in the only |
Georg Brandl | e8f2443 | 2005-10-03 14:16:44 +0000 | [diff] [blame] | 154 | browser window. Alias \function{open_new}. |
| 155 | \end{funcdesc} |
| 156 | |
| 157 | \begin{funcdesc}{open_new_tab}{url} |
| 158 | Open \var{url} in a new page ("tab") of the browser handled by this |
Neal Norwitz | 178f906 | 2005-10-04 03:31:01 +0000 | [diff] [blame] | 159 | controller, if possible, otherwise equivalent to \function{open_new}. |
| 160 | \versionadded{2.5} |
Fred Drake | e4dbb86 | 2000-07-07 03:36:12 +0000 | [diff] [blame] | 161 | \end{funcdesc} |