Expose the autoraise capability. Improve the documentation.

Doc/lib/libwebbrowser.tex

@@ -8,7 +8,9 @@
 
 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.
+are easy to use and are platform-independent.  Under most
+circumstances, simply calling the \function{open()} function from this
+module will do the right thing.
 
 Under \UNIX, graphical browsers are preferred under X11, but text-mode
 browsers will be used if graphical browsers are not available or an X11
@@ -16,11 +18,11 @@ 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
-is interpreted to override the platform default browser, as a
+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
 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,
+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.
 
@@ -37,9 +39,11 @@ The following exception is defined:
 
 The following functions are defined:
 
-\begin{funcdesc}{open}{url\optional{, new}}
+\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.
+  a new browser window 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}
@@ -67,19 +71,20 @@ The following functions are defined:
   argument matching the name of a handler you declare.  
 \end{funcdesc}
 
-Several browser types are defined.  This table gives the type names
+A number of browser types are predefined.  This table gives the type
-that may be passed to the \function{get()} function and the names of
+names that may be passed to the \function{get()} function and the
-the implementation classes, all defined in this module.
+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{Mozilla}}{}
+  \lineiii{'mozilla'}{\class{Netscape('mozilla')}}{}
-  \lineiii{'netscape'}{\class{Netscape}}{}
+  \lineiii{'netscape'}{\class{Netscape('netscape')}}{}
-  \lineiii{'mosaic'}{\class{Mosaic}}{}
+  \lineiii{'mosaic'}{\class{GenericBrowser('mosaic \%s &')}}{}
-  \lineiii{'kfm'}{\class{Konquerer}}{(1)}
+  \lineiii{'kfm'}{\class{Konqueror()}}{(1)}
-  \lineiii{'grail'}{\class{Grail}}{}
+  \lineiii{'grail'}{\class{Grail()}}{}
-  \lineiii{'links'}{\class{links}}{}
+  \lineiii{'links'}{\class{GenericBrowser('links \%s')}}{}
-  \lineiii{'lynx'}{\class{Lynx}}{}
+  \lineiii{'lynx'}{\class{GenericBrowser('lynx \%s')}}{}
-  \lineiii{'w3m'}{\class{w3m}}{}
+  \lineiii{'w3m'}{\class{GenericBrowser('w3m \%s')}}{}
   \lineiii{'windows-default'}{\class{WindowsDefault}}{(2)}
   \lineiii{'internet-config'}{\class{InternetConfig}}{(3)}
 \end{tableiii}
@@ -89,7 +94,7 @@ Notes:
 
 \begin{description}
 \item[(1)]
-``Konquerer'' is the file manager for the KDE desktop environment for
+``Konqueror'' is the file manager for the KDE desktop environment for
 UNIX, and only makes sense to use if KDE is running.  Some way of
 reliably detecting KDE would be nice; the \envvar{KDEDIR} variable is
 not sufficient.

Lib/webbrowser.py

@@ -34,8 +34,8 @@ def get(using=None):
 
 # Please note: the following definition hides a builtin function.
 
-def open(url, new=0):
+def open(url, new=0, autoraise=1):
-    get().open(url, new)
+    get().open(url, new, autoraise)
 
 def open_new(url):	# Marked deprecated.  May be removed in 2.1.
     get().open(url, 1)
@@ -99,13 +99,11 @@ if os.environ.get("TERM") or os.environ.get("DISPLAY"):
         if _iscommand("netscape") or _iscommand("mozilla"):
             class Netscape:
                 "Launcher class for Netscape browsers."
-                autoRaise = 1
-
                 def __init__(self, name):
                     self.name = name
 
-                def _remote(self, action):
+                def _remote(self, action, autoraise):
-                    raise_opt = ("-noraise", "-raise")[self.autoRaise]
+                    raise_opt = ("-noraise", "-raise")[autoraise]
                     cmd = "%s %s -remote '%s' >/dev/null 2>&1" % (self.name, raise_opt, action)
                     rc = os.system(cmd)
                     if rc:
@@ -115,11 +113,11 @@ if os.environ.get("TERM") or os.environ.get("DISPLAY"):
                         rc = os.system(cmd)
                     return not rc
 
-                def open(self, url, new=0):
+                def open(self, url, new=0, autoraise=1):
                     if new:
-                        self._remote("openURL(%s, new-window)" % url)
+                        self._remote("openURL(%s, new-window)"%url, autoraise)
                     else:
-                        self._remote("openURL(%s)" % url)
+                        self._remote("openURL(%s)" % url, autoraise)
 
                 # Deprecated.  May be removed in 2.1.
                 def open_new(self, url):
@@ -159,7 +157,6 @@ if os.environ.get("TERM") or os.environ.get("DISPLAY"):
 
                 # Deprecated.  May be removed in 2.1.
                 open_new = open
-                    
 
             register("kfm", Konqueror, None)