Doc/lib/libwebbrowser.tex

   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
   9 The \module{webbrowser} module provides a very high-level interface to
  10 allow displaying Web-based documents to users.  The controller objects
  11 are easy to use and are platform-independent.  Under most
  12 circumstances, simply calling the \function{open()} function from this
  13 module will do the right thing.
  14
  15 Under \UNIX, graphical browsers are preferred under X11, but text-mode
  16 browsers will be used if graphical browsers are not available or an X11
  17 display isn't available.  If text-mode browsers are used, the calling
  18 process will block until the user exits the browser.
  19
  20 Under \UNIX, if the environment variable \envvar{BROWSER} exists, it
  21 is interpreted to override the platform default list of browsers, as a
  22 colon-separated list of browsers to try in order.  When the value of
  23 a list part contains the string \code{\%s}, then it is interpreted as
  24 a literal browser command line to be used with the argument URL
  25 substituted for the \code{\%s}; if the part does not contain
  26 \code{\%s}, it is simply interpreted as the name of the browser to
  27 launch.
  28
  29 For non-\UNIX{} platforms, or when X11 browsers are available on
  30 \UNIX, the controlling process will not wait for the user to finish
  31 with the browser, but allow the browser to maintain its own window on
  32 the display.
  33
  34 The following exception is defined:
  35
  36 \begin{excdesc}{Error}
  37   Exception raised when a browser control error occurs.
  38 \end{excdesc}
  39
  40 The following functions are defined:
  41
  42 \begin{funcdesc}{open}{url\optional{, new=0}\optional{, autoraise=1}}
  43   Display \var{url} using the default browser.  If \var{new} is true,
  44   a new browser window is opened if possible.  If \var{autoraise} is
  45   true, the window is raised if possible (note that under many window
  46   managers this will occur regardless of the setting of this variable).
  47 \end{funcdesc}
  48
  49 \begin{funcdesc}{open_new}{url}
  50   Open \var{url} in a new window of the default browser, if possible,
  51   otherwise, open \var{url} in the only browser window.  (This entry
  52   point is deprecated and may be removed in 2.1.)
  53 \end{funcdesc}
  54
  55 \begin{funcdesc}{get}{\optional{name}}
  56   Return a controller object for the browser type \var{name}.  If
  57   \var{name} is empty, return a controller for a default browser
  58   appropriate to the caller's environment.
  59 \end{funcdesc}
  60
  61 \begin{funcdesc}{register}{name, constructor\optional{, instance}}
  62   Register the browser type \var{name}.  Once a browser type is
  63   registered, the \function{get()} function can return a controller
  64   for that browser type.  If \var{instance} is not provided, or is
  65   \code{None}, \var{constructor} will be called without parameters to
  66   create an instance when needed.  If \var{instance} is provided,
  67   \var{constructor} will never be called, and may be \code{None}.
  68
  69   This entry point is only useful if you plan to either set the
  70   \envvar{BROWSER} variable or call \function{get} with a nonempty
  71   argument matching the name of a handler you declare.
  72 \end{funcdesc}
  73
  74 A number of browser types are predefined.  This table gives the type
  75 names that may be passed to the \function{get()} function and the
  76 corresponding instantiations for the controller classes, all defined
  77 in this module.
  78
  79 \begin{tableiii}{l|l|c}{code}{Type Name}{Class Name}{Notes}
  80   \lineiii{'mozilla'}{\class{Netscape('mozilla')}}{}
  81   \lineiii{'netscape'}{\class{Netscape('netscape')}}{}
  82   \lineiii{'mosaic'}{\class{GenericBrowser('mosaic \%s \&')}}{}
  83   \lineiii{'kfm'}{\class{Konqueror()}}{(1)}
  84   \lineiii{'grail'}{\class{Grail()}}{}
  85   \lineiii{'links'}{\class{GenericBrowser('links \%s')}}{}
  86   \lineiii{'lynx'}{\class{GenericBrowser('lynx \%s')}}{}
  87   \lineiii{'w3m'}{\class{GenericBrowser('w3m \%s')}}{}
  88   \lineiii{'windows-default'}{\class{WindowsDefault}}{(2)}
  89   \lineiii{'internet-config'}{\class{InternetConfig}}{(3)}
  90 \end{tableiii}
  91
  92 \noindent
  93 Notes:
  94
  95 \begin{description}
  96 \item[(1)]
  97 ``Konqueror'' is the file manager for the KDE desktop environment for
  98 UNIX, and only makes sense to use if KDE is running.  Some way of
  99 reliably detecting KDE would be nice; the \envvar{KDEDIR} variable is
 100 not sufficient.  Note also that the name ``kfm'' is used even when
 101 using the \program{konqueror} command with KDE 2 --- the
 102 implementation selects the best strategy for running Konqueror.
 103
 104 \item[(2)]
 105 Only on Windows platforms; requires the common
 106 extension modules \module{win32api} and \module{win32con}.
 107
 108 \item[(3)]
 109 Only on MacOS platforms; requires the standard MacPython \module{ic}
 110 module, described in the \citetitle[../mac/module-ic.html]{Macintosh
 111 Library Modules} manual.
 112 \end{description}
 113
 114
 115 \subsection{Browser Controller Objects \label{browser-controllers}}
 116
 117 Browser controllers provide two methods which parallel two of the
 118 module-level convenience functions:
 119
 120 \begin{funcdesc}{open}{url\optional{, new}}
 121   Display \var{url} using the browser handled by this controller.  If
 122   \var{new} is true, a new browser window is opened if possible.
 123 \end{funcdesc}
 124
 125 \begin{funcdesc}{open_new}{url}
 126   Open \var{url} in a new window of the browser handled by this
 127   controller, if possible, otherwise, open \var{url} in the only
 128   browser window.  (This method is deprecated and may be removed in
 129   2.1.)
 130 \end{funcdesc}