\section{\module{webbrowser} ---
便利なウェブブラウザコントローラー}

\declaremodule{standard}{webbrowser}
\modulesynopsis{
ウェウブブラウザーのための使い易いコントローラー}
\moduleauthor{Fred L. Drake, Jr.}{fdrake@acm.org}
\sectionauthor{Fred L. Drake, Jr.}{fdrake@acm.org}

\module{webbrowser}モジュールにはウェブベースのドキュメントを表示するた
めの、とてもハイレベルなインターフェースが定義されています。たいていの
環境では、このモジュールの\function{open()}を呼び出すだけで正しく動作し
ます。

\UNIX{}では、X11上でグラフィカルなブラウザが選択されますが、グラフィカルなブ
ラウザが利用できなかったり、X11が利用できない場合はテキストモードのブラウザ
が使われます。
もしテキストモードのブラウザが使われたら、ユーザがブラウザから抜け出すまでプ
ロセスの呼び出しはブロックされます。

環境変数\envvar{BROWSER}が存在するならプラットフォームのデフォ
ルトであるブラウザのリストをオーバーライドし、os.pathsepで区切られたリストの順に
ブラウザの起動を試みます。
リストの中の値に\code{\%s}が含まれていたら、テキストモードのブラウザのコマン
ドラインとして\code{\%s}の代わりにURLが引数として解釈されます；
もし\code{\%s}が含まれなければ、起動するブラウザの名前として単純に解釈されま
す。

非\UNIX{}プラットフォームあるいは\UNIX{}上でリモートブラウザが利用可能な場合、制
御プロセスはユーザがブラウザを終了するのを待ちませんが、ディスプレイにブラウ
ザのウィンドウを表示させたままにします。\UNIX{}上でリモートブラウザが利用可能
でない場合、制御プロセスは新しいブラウザを立ち上げ、待ちます。

\program{webbrowser} スクリプトをこのモジュールのコマンドラインインタフェースとして
使うことができます。スクリプトは引数に一つの URL を受け付けます。また次のオプション
引数を受け付けます。 \programopt{-n} により可能ならば新しいブラウザウィンドウで
指定された URL を開きます。一方、\programopt{-t} では新しいブラウザのページ(「タブ」)
で開きます。当然ながらこれらのオプションは排他的です。

以下の例外が定義されています：

\begin{excdesc}{Error}
ブラウザのコントロールエラーが起こると発生する例外。
\end{excdesc}

以下の関数が定義されています：

\begin{funcdesc}{open}{url\optional{, new=0\optional{, autoraise=1}}}
デフォルトのブラウザで\var{url}を表示します。
\var{new}が 0 なら、\var{url}はブラウザの今までと同じウィンドウで開きます。
\var{new}が 1 なら、可能であればブラウザの新しいウィンドウが開きます。
\var{new}が 2 なら、可能であればブラウザの新しいタブが開きます。
\var{autoraise}がtrueなら、可能であればウィンドウが前面に表示されます（多く
のウィンドウマネージャではこの変数の設定に関わらず、前面に表示されます）。
\versionchanged[\var{new} を 2 にもできるようになりました]{2.5}
\end{funcdesc}

\begin{funcdesc}{open_new}{url}
可能であれば、デフォルトブラウザの新しいウィンドウで\var{url}を開きますが、
そうでない場合はブラウザのただ１つのウィンドウで\var{url}を開きます。
\end{funcdesc}

\begin{funcdesc}{open_new_tab}{url}
可能であれば、デフォルトブラウザの新しいページ(「タブ」)で\var{url}を開きますが、
そうでない場合は\function{open_new}と同様に振る舞います。
\versionadded{2.5}
\end{funcdesc}

\begin{funcdesc}{get}{\optional{name}}
ブラウザの種類\var{name}のコントローラーオブジェクトを返します。
もし\var{name}が空文字列なら、呼び出した環境に適したデフォルトブラウザのコン
トローラーを返します。
\end{funcdesc}

\begin{funcdesc}{register}{name, constructor\optional{, instance}}
ブラウザの種類\var{name}を登録します。
ブラウザの種類が登録されたら、\function{get()}でそのブラウザのコントローラー
を呼び出すことができます。
\var{instance}が指定されなかったり、\code{None}なら、インスタンスが必要な時
には\var{constructor}がパラメータなしに呼び出されて作られます。
\var{instance}が指定されたら、\var{constructor}は呼び出されないので、
\code{None}でかまいません。

この登録は、変数\envvar{BROWSER}を設定するか、\function{get}を空文字列でな
く、宣言したハンドラの名前と一致する引数とともに呼び出すときだけ、役に立ちま
す。
\end{funcdesc}

いくつかの種類のブラウザがあらかじめ定義されています。
このモジュールで定義されている、関数\function{get()}に与えるブラウザの名前
と、それぞれのコントローラークラスのインスタンスを以下の表に示します。

\begin{tableiii}{l|l|c}{code}{Type Name}{Class Name}{Notes}
  \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{BackgroundBrowser('skipstone')}}{}
  \lineiii{'kfmclient'}{\class{Konqueror()}}{(1)}
  \lineiii{'konqueror'}{\class{Konqueror()}}{(1)}
  \lineiii{'kfm'}{\class{Konqueror()}}{(1)}
  \lineiii{'mosaic'}{\class{BackgroundBrowser('mosaic')}}{}
  \lineiii{'opera'}{\class{Opera()}}{}
  \lineiii{'grail'}{\class{Grail()}}{}
  \lineiii{'links'}{\class{GenericBrowser('links')}}{}
  \lineiii{'elinks'}{\class{Elinks('elinks')}}{}
  \lineiii{'lynx'}{\class{GenericBrowser('lynx')}}{}
  \lineiii{'w3m'}{\class{GenericBrowser('w3m')}}{}
  \lineiii{'windows-default'}{\class{WindowsDefault}}{(2)}
  \lineiii{'internet-config'}{\class{InternetConfig}}{(3)}
  \lineiii{'macosx'}{\class{MacOSX('default')}}{(4)}
\end{tableiii}

\noindent
Notes:

\begin{description}
\item[(1)]
``Konqueror''は\UNIX{}のKDEデスクトップ環境のファイルマネージャで、KDEが動作
している時にだけ意味を持ちます。
何か信頼できる方法でKDEを検出するのがいいでしょう；変数\envvar{KDEDIR}では十
分ではありません。
また、KDE 2で\program{konqueror}コマンドを使うときにも、``kfm''が使われます 
--- Konquerorを動作させるのに最も良い方法が実装によって選択されます。

\item[(2)]
Windowsプラットフォームのみ。

\item[(3)]
MacOSプラットフォームのみ；\citetitle[../mac/module-ic.html]{Macintosh
Library Modules}マニュアルに解説されている標準MacPythonモジュール\module{ic}
を必要とします。

\item[(4)]
MacOS X プラットフォームのみ。
\end{description}

簡単な例を示します。

\begin{verbatim}
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)
\end{verbatim}


\subsection{ブラウザコントローラーオブジェクト \label{browser-controllers}}

ブラウザコントローラーには２つのメソッドが定義されていて、モジュールレベルの
便利な２つの関数に相当します：

\begin{funcdesc}{open}{url\optional{, new\optional{, autoraise=1}}}
このコントローラーでハンドルされたブラウザで\var{url}を表示します。
\var{new}が 1 なら、可能であればブラウザの新しいウィンドウが開きます。
\var{new}が 2 なら、可能であればブラウザの新しいページ(「タブ」)が開きます。
\end{funcdesc}

\begin{funcdesc}{open_new}{url}
可能であれば、このコントローラーでハンドルされたブラウザの新しいウィンドウで
\var{url}を開きますが、そうでない場合はブラウザのただ１つのウィンドウで
\var{url}を開きます。\function{open_new} の別名。
\end{funcdesc}

\begin{funcdesc}{open_new_tab}{url}
可能であれば、このコントローラーでハンドルされたブラウザの新しいページ(「タブ」)で
\var{url}を開きますが、そうでない場合は \function{open_new} と同じです。
\versionadded{2.5}
\end{funcdesc}
