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.
  12
  13 Under \UNIX, graphical browsers are preferred under X11, but text-mode
  14 browser will be used if graphical browsers are not available or an X11
  15 display isn't available.  If text-mode browsers are used, the calling
  16 process will block until the user exits the browser.
  17
  18 For non-\UNIX{} platforms, or when X11 browsers are available on
  19 \UNIX, the controlling process will not wait for the user to finish
  20 with the browser, but allow the browser to maintain its own window on
  21 the display.
  22
  23 The following exception is defined:
  24
  25 \begin{excdesc}{Error}
  26   Exception raised when a browser control error occurs.
  27 \end{excdesc}
  28
  29 The following functions are defined:
  30
  31 \begin{funcdesc}{open}{url\optional{, new}}
  32   Display \var{url} using the default browser.  If \var{new} is true,
  33   a new browser window is opened if possible.
  34 \end{funcdesc}
  35
  36 \begin{funcdesc}{open_new}{url}
  37   Open \var{url} in a new window of the default browser, if possible,
  38   otherwise, open \var{url} in the only browser window.
  39 \end{funcdesc}
  40
  41 \begin{funcdesc}{get}{\optional{name}}
  42   Return a controller object for the browser type \var{name}.
  43 \end{funcdesc}
  44
  45 \begin{funcdesc}{register}{name, constructor\optional{, controller}}
  46   Register the browser type \var{name}.  Once a browser type is
  47   registered, the \function{get()} function can return a controller
  48   for that browser type.  If \var{instance} is not provided, or is
  49   \code{None}, \var{constructor} will be called without parameters to
  50   create an instance when needed.  If \var{instance} is provided,
  51   \var{constructor} will never be called, and may be \code{None}.
  52 \end{funcdesc}
  53
  54 Several browser types are defined.  This table gives the type names
  55 that may be passed to the \function{get()} function and the names of
  56 the implementation classes, all defined in this module.
  57
  58 \begin{tableiii}{l|l|c}{code}{Type Name}{Class Name}{Notes}
  59   \lineiii{'netscape'}{\class{Netscape}}{}
  60   \lineiii{'kfm'}{\class{Konquerer}}{(1)}
  61   \lineiii{'grail'}{\class{Grail}}{}
  62   \lineiii{'windows-default'}{\class{WindowsDefault}}{(2)}
  63   \lineiii{'internet-config'}{\class{InternetConfig}}{(3)}
  64   \lineiii{'command-line'}{\class{CommandLineBrowser}}{}
  65 \end{tableiii}
  66
  67 \noindent
  68 Notes:
  69
  70 \begin{description}
  71 \item[(1)]
  72 ``Konquerer'' is the file manager for the KDE desktop environment, and
  73 only makes sense to use if KDE is running.
  74
  75 \item[(2)]
  76 Only on Windows platforms; requires the common
  77 extension modules \module{win32api} and \module{win32con}.
  78
  79 \item[(3)]
  80 Only on MacOS platforms; requires the standard MacPython \module{ic}
  81 module, described in the \citetitle[../mac/module-ic.html]{Macintosh
  82 Library Modules} manual.
  83 \end{description}
  84
  85
  86 \subsection{Browser Controller Objects \label{browser-controllers}}
  87
  88 Browser controllers provide two methods which parallel two of the
  89 module-level convenience functions:
  90
  91 \begin{funcdesc}{open}{url\optional{, new}}
  92   Display \var{url} using the browser handled by this controller.  If
  93   \var{new} is true, a new browser window is opened if possible.
  94 \end{funcdesc}
  95
  96 \begin{funcdesc}{open_new}{url}
  97   Open \var{url} in a new window of the browser handled by this
  98   controller, if possible, otherwise, open \var{url} in the only
  99   browser window.
 100 \end{funcdesc}