--- /dev/null Thu Jan 01 00:00:00 1970 +0000
+++ b/symbian-qemu-0.9.1-12/python-2.6.1/Doc/library/webbrowser.rst Fri Jul 31 15:01:17 2009 +0100
@@ -0,0 +1,199 @@
+
+:mod:`webbrowser` --- Convenient Web-browser controller
+=======================================================
+
+.. module:: webbrowser
+ :synopsis: Easy-to-use controller for Web browsers.
+.. moduleauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+.. sectionauthor:: Fred L. Drake, Jr. <fdrake@acm.org>
+
+
+The :mod:`webbrowser` module provides a high-level interface to allow displaying
+Web-based documents to users. Under most circumstances, simply calling the
+:func:`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 display isn't
+available. If text-mode browsers are used, the calling process will block until
+the user exits the browser.
+
+If the environment variable :envvar:`BROWSER` exists, it is interpreted to
+override the platform default list of browsers, as a os.pathsep-separated list
+of browsers to try in order. When the value of a list part contains the string
+``%s``, then it is interpreted as a literal browser command line to be used
+with the argument URL substituted for ``%s``; if the part does not contain
+``%s``, it is simply interpreted as the name of the browser to launch.
+
+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 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: :option:`-n` opens the URL in a new browser window, if possible;
+:option:`-t` opens the URL in a new browser page ("tab"). The options are,
+naturally, mutually exclusive.
+
+The following exception is defined:
+
+
+.. exception:: Error
+
+ Exception raised when a browser control error occurs.
+
+The following functions are defined:
+
+
+.. function:: open(url[, new=0[, autoraise=1]])
+
+ Display *url* using the default browser. If *new* is 0, the *url* is opened in
+ the same browser window if possible. If *new* is 1, a new browser window is
+ opened if possible. If *new* is 2, a new browser page ("tab") is opened if
+ possible. If *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).
+
+ .. versionchanged:: 2.5
+ *new* can now be 2.
+
+
+.. function:: open_new(url)
+
+ Open *url* in a new window of the default browser, if possible, otherwise, open
+ *url* in the only browser window.
+
+
+.. function:: open_new_tab(url)
+
+ Open *url* in a new page ("tab") of the default browser, if possible, otherwise
+ equivalent to :func:`open_new`.
+
+ .. versionadded:: 2.5
+
+
+.. function:: get([name])
+
+ Return a controller object for the browser type *name*. If *name* is empty,
+ return a controller for a default browser appropriate to the caller's
+ environment.
+
+
+.. function:: register(name, constructor[, instance])
+
+ Register the browser type *name*. Once a browser type is registered, the
+ :func:`get` function can return a controller for that browser type. If
+ *instance* is not provided, or is ``None``, *constructor* will be called without
+ parameters to create an instance when needed. If *instance* is provided,
+ *constructor* will never be called, and may be ``None``.
+
+ This entry point is only useful if you plan to either set the :envvar:`BROWSER`
+ variable or call :func:`get` with a nonempty argument matching the name of a
+ handler you declare.
+
+A number of browser types are predefined. This table gives the type names that
+may be passed to the :func:`get` function and the corresponding instantiations
+for the controller classes, all defined in this module.
+
++-----------------------+-----------------------------------------+-------+
+| Type Name | Class Name | Notes |
++=======================+=========================================+=======+
+| ``'mozilla'`` | :class:`Mozilla('mozilla')` | |
++-----------------------+-----------------------------------------+-------+
+| ``'firefox'`` | :class:`Mozilla('mozilla')` | |
++-----------------------+-----------------------------------------+-------+
+| ``'netscape'`` | :class:`Mozilla('netscape')` | |
++-----------------------+-----------------------------------------+-------+
+| ``'galeon'`` | :class:`Galeon('galeon')` | |
++-----------------------+-----------------------------------------+-------+
+| ``'epiphany'`` | :class:`Galeon('epiphany')` | |
++-----------------------+-----------------------------------------+-------+
+| ``'skipstone'`` | :class:`BackgroundBrowser('skipstone')` | |
++-----------------------+-----------------------------------------+-------+
+| ``'kfmclient'`` | :class:`Konqueror()` | \(1) |
++-----------------------+-----------------------------------------+-------+
+| ``'konqueror'`` | :class:`Konqueror()` | \(1) |
++-----------------------+-----------------------------------------+-------+
+| ``'kfm'`` | :class:`Konqueror()` | \(1) |
++-----------------------+-----------------------------------------+-------+
+| ``'mosaic'`` | :class:`BackgroundBrowser('mosaic')` | |
++-----------------------+-----------------------------------------+-------+
+| ``'opera'`` | :class:`Opera()` | |
++-----------------------+-----------------------------------------+-------+
+| ``'grail'`` | :class:`Grail()` | |
++-----------------------+-----------------------------------------+-------+
+| ``'links'`` | :class:`GenericBrowser('links')` | |
++-----------------------+-----------------------------------------+-------+
+| ``'elinks'`` | :class:`Elinks('elinks')` | |
++-----------------------+-----------------------------------------+-------+
+| ``'lynx'`` | :class:`GenericBrowser('lynx')` | |
++-----------------------+-----------------------------------------+-------+
+| ``'w3m'`` | :class:`GenericBrowser('w3m')` | |
++-----------------------+-----------------------------------------+-------+
+| ``'windows-default'`` | :class:`WindowsDefault` | \(2) |
++-----------------------+-----------------------------------------+-------+
+| ``'internet-config'`` | :class:`InternetConfig` | \(3) |
++-----------------------+-----------------------------------------+-------+
+| ``'macosx'`` | :class:`MacOSX('default')` | \(4) |
++-----------------------+-----------------------------------------+-------+
+
+Notes:
+
+(1)
+ "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. Note also that
+ the name "kfm" is used even when using the :program:`konqueror` command with KDE
+ 2 --- the implementation selects the best strategy for running Konqueror.
+
+(2)
+ Only on Windows platforms.
+
+(3)
+ Only on Mac OS platforms; requires the standard MacPython :mod:`ic` module.
+
+(4)
+ Only on Mac OS X platform.
+
+Here are some simple examples::
+
+ url = 'http://www.python.org'
+
+ # Open URL in a new tab, if a browser window is already open.
+ webbrowser.open_new_tab(url + '/doc')
+
+ # Open URL in new window, raising the window if possible.
+ webbrowser.open_new(url)
+
+
+.. _browser-controllers:
+
+Browser Controller Objects
+--------------------------
+
+Browser controllers provide two methods which parallel two of the module-level
+convenience functions:
+
+
+.. method:: controller.open(url[, new[, autoraise=1]])
+
+ Display *url* using the browser handled by this controller. If *new* is 1, a new
+ browser window is opened if possible. If *new* is 2, a new browser page ("tab")
+ is opened if possible.
+
+
+.. method:: controller.open_new(url)
+
+ Open *url* in a new window of the browser handled by this controller, if
+ possible, otherwise, open *url* in the only browser window. Alias
+ :func:`open_new`.
+
+
+.. method:: controller.open_new_tab(url)
+
+ Open *url* in a new page ("tab") of the browser handled by this controller, if
+ possible, otherwise equivalent to :func:`open_new`.
+
+ .. versionadded:: 2.5
+