diff options
Diffstat (limited to 'Doc')
| -rw-r--r-- | Doc/lib/libwebbrowser.tex | 75 |
1 files changed, 53 insertions, 22 deletions
diff --git a/Doc/lib/libwebbrowser.tex b/Doc/lib/libwebbrowser.tex index 285fcf5..42c7691 100644 --- a/Doc/lib/libwebbrowser.tex +++ b/Doc/lib/libwebbrowser.tex @@ -6,9 +6,8 @@ \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 +The \module{webbrowser} module provides a high-level interface to +allow displaying Web-based documents to users. Under most circumstances, simply calling the \function{open()} function from this module will do the right thing. @@ -17,19 +16,26 @@ 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 +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 +os.pathsep-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 +For non-\UNIX{} platforms, or when a remote browser is 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. +with the browser, but allow the remote browser to maintain its own +windows on the display. If remote browsers are not available on \UNIX, +the controlling process will launch a new browser and wait. + +The script \program{webbrowser} can be used as a command-line interface +for the module. It accepts an URL as the argument. It accepts the following +optional parameters: \programopt{-n} opens the URL in a new browser window, +if possible; \programopt{-t} opens the URL in a new browser page ("tab"). The +options are, naturally, mutually exclusive. The following exception is defined: @@ -40,15 +46,24 @@ The following exception is defined: 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 + Display \var{url} using the default browser. If \var{new} is 0, the + \var{url} is opened in the same browser window. If \var{new} is 1, + a new browser window is opened if possible. If \var{new} is 2, + a new browser page ("tab") 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} +\begin{funcdesc}{open_new_win}{url} Open \var{url} in a new window of the default browser, if possible, - otherwise, open \var{url} in the only browser window. + otherwise, open \var{url} in the only browser window. Alias + \function{open_new}. +\end{funcdesc} + +\begin{funcdesc}{open_new_tab}{url} + Open \var{url} in a new page ("tab") of the default browser, if possible, + otherwise equivalent to \function{open_new_win}. \end{funcdesc} \begin{funcdesc}{get}{\optional{name}} @@ -67,7 +82,7 @@ The following functions are defined: 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. + argument matching the name of a handler you declare. \end{funcdesc} A number of browser types are predefined. This table gives the type @@ -76,16 +91,24 @@ 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{'mozilla'}{\class{Mozilla('mozilla')}}{} + \lineiii{'firefox'}{\class{Mozilla('mozilla')}}{} + \lineiii{'netscape'}{\class{Mozilla('netscape')}}{} + \lineiii{'galeon'}{\class{Galeon('galeon')}}{} + \lineiii{'epiphany'}{\class{Galeon('epiphany')}}{} + \lineiii{'skipstone'}{\class{GenericBrowser('skipstone \%s \&')}}{} + \lineiii{'konqueror'}{\class{Konqueror()}}{(1)} \lineiii{'kfm'}{\class{Konqueror()}}{(1)} + \lineiii{'mosaic'}{\class{GenericBrowser('mosaic \%s \&')}}{} + \lineiii{'opera'}{\class{Opera()}}{} \lineiii{'grail'}{\class{Grail()}}{} \lineiii{'links'}{\class{GenericBrowser('links \%s')}}{} + \lineiii{'elinks'}{\class{Elinks('elinks')}}{} \lineiii{'lynx'}{\class{GenericBrowser('lynx \%s')}}{} \lineiii{'w3m'}{\class{GenericBrowser('w3m \%s')}}{} \lineiii{'windows-default'}{\class{WindowsDefault}}{(2)} \lineiii{'internet-config'}{\class{InternetConfig}}{(3)} + \lineiii{'macosx'}{\class{MacOSX('default')}}{(4)} \end{tableiii} \noindent @@ -101,13 +124,15 @@ 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}. +Only on Windows platforms. \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. + +\item[(4)] +Only on MacOS X platform. \end{description} @@ -117,12 +142,18 @@ 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. + Display \var{url} using the browser handled by this controller. + If \var{new} is 1, a new browser window is opened if possible. + If \var{new} is 2, a new browser page ("tab") is opened if possible. \end{funcdesc} -\begin{funcdesc}{open_new}{url} +\begin{funcdesc}{open_new_win}{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. + browser window. Alias \function{open_new}. +\end{funcdesc} + +\begin{funcdesc}{open_new_tab}{url} + Open \var{url} in a new page ("tab") of the browser handled by this + controller, if possible, otherwise equivalent to \function{open_new_win}. \end{funcdesc} |