マクロ言語としてのPython

Script Location

OpenOffice.orgで実行するスクリプトは、次の位置に格納することができます。：

OpenOffice.org's user directory

これは、自己記述されたPythonスクリプトのための標準的な場所です。スクリプト・ファイルは、単純に、ファイル・システム内に格納されています。ディレクトリの位置は、使用しているOpenOffice.orgバージョンとOSによって異なります。いくつかの例は、以下の通りです：

OpenOffice 2.x

OpenOffice 3.x

備考: 最後のPythonサブディレクトリが、まず最初に作成される必要があるかもしれません。Pythonは、完全に小文字で記述されていることを確認して下さい。あなたは、深くネストされた任意のサブディレクトリを追加することができます。これらのディレクトリの名前が、UIに反映されます。

例：dynamicDialog.pyファイルは、単純に、上記のディレクトリに配置することができます。その後、Tools/Macros/Runマクロ・ダイアログを開いて、上の図に表示される位置に移動します。RunをクリックしてPythonスクリプトを実行します。それは、押しボタンとラベル・フィールドを持つ他のダイアログを開きます。ボタンをクリックすると、ラベル・フィールド内の数字が大きくなります。ESCを押すと、ダイアログを閉じることができます。

OpenOffice.org's share directory

具体的なOpenOffice.orgインストールのすべてのユーザーに共有されるスクリプトは、共有ディレクトリに保存することができます。OpenOffice.orgに付属する、すべてのデフォルト・スクリプトがここにあります。一般に、このディレクトリは、スクリプトの配布のために使用してはいけません。（後のuno-packageを参照）。

スクリプト・ファイルは、単純に、ファイル・システム内に格納されています。ディレクトリの位置は、（ユーザー・ディレクトリのように）使用しているOpenOffice.orgバージョンとOSによって異なります。いくつかの例を、以下に示します：

OpenOffice 2.x

OpenOffice 3.x

Embedded within an OpenOffice.org's document

OpenOffice.org文書は、別のファイルに含まれているzipファイルです。文書の内のPythonスクリプトは、Scripts/Pythonサブディレクトリに格納されます。

あなたが、文書の中に、記述したpythonスクリプトを入れたい場合、あなたは、まず、（上で言及した）ユーザー・ディレクトリで、スクリプトを開発する必要があります。そして、その次に、最後に、あなたのお気に入りのzipツールで、文書にスクリプトを移動します。しかしながら、あなたが、これまでに行った、すべての結合を、ドキュメント内のスクリプトインスタンスに、再割り当てする必要があることに注意してください。理想的には、あなたは、スクリプトをユーザー・ディレクトリから移動します。そして、文書の機能に関して回帰テストを行います。

スクリプト・ファイルを文書に移動した後、あなたは、META-INF / manifest.xmlファイルに、いくつかの行（太字で表示）を追加する必要があります。：

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd">
<manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
 <manifest:file-entry manifest:media-type="application/vnd.oasis.opendocument.text" manifest:full-path="/"/>
 <manifest:file-entry manifest:media-type="application/vnd.sun.xml.ui.configuration" manifest:full-path="Configurations2/"/>
 <manifest:file-entry manifest:media-type="" manifest:full-path="Pictures/"/>
 <manifest:file-entry manifest:media-type="text/xml" manifest:full-path="content.xml"/>
 <manifest:file-entry :media-type="text/xml" manifest:full-path="styles.xml"/>
 <manifest:file-entry manifest:media-type="text/xml" manifest:full-path="meta.xml"/>
 <manifest:file-entry manifest:media-type="" manifest:full-path="Thumbnails/thumbnail.png"/>
 <manifest:file-entry manifest:media-type="" manifest:full-path="Thumbnails/"/>
 <manifest:file-entry manifest:media-type="text/xml" manifest:full-path="settings.xml"/>
 <manifest:file-entry manifest:media-type="" manifest:full-path="Scripts/python/push_me.py"/>
 <manifest:file-entry manifest:media-type="application/binary" manifest:full-path="Scripts/python/"/>
 <manifest:file-entry manifest:media-type="application/binary" manifest:full-path="Scripts/"/>
</manifest:manifest>

あなたが、あとで文書を開くとき、OpenOffice.orgのUIは、ドキュメント内のスクリプトの内容について警告する必要があります。（これが当てはまらないときは、あなたは、オプションで警告のスイッチを切った、あるいは、あなたは間違った何かを行った）。

例：それが、どのように動作するか確かめるために、ファイルをダウンロードします。：Push me python4.odt 。文書は、押しボタンと複数の行の編集コントロールが含まれています。ボタンを押すと、現在のタイム・スタンプで、新しい行を、複数行の編集コントロールに追加します。

Embedded within a uno-package in OpenOffice.org's user directory (read only)

多くの場合、文書内のスクリプトを配布することは、あなたが望むものではありません。（例えば、あなたが、アプリケーションそのものを修正したい、あるいは、あなたが、複数の文書で、同じスクリプトを使用したい場合）。その代わりに、あなたは、単純に、uno-package内に、スクリプトを配置することができます。

uno-packageは、zipファイルです。その名前は、.pkgで終わる必要があります。それ以外の場合には、それは、動作しません。あなたが、サブディレクトリを定義する必要があるファイル（必須！）は、スクリプトが含まれています。たとえば、サンプルpyhello2.uno.pkgは、次のファイル構造を持っています。

META-INF/
META-INF/manifest.xml
package/
package/hallo.py

hallo.pyには、スクリプトが含まれています。どのようにスクリプトを記述するかを、以下に示します。しかしながら、unoパッケージ内にスクリプトを作成するための操作のために、あなたは、いくつかのダミー・コードを追加する必要があります。

# ... here is the python script code
 
# this must be added to every script file (the
# name org.openoffice.script.DummyImplementationForPythonScripts should be changed to something
# different (must be unique within an office installation !)
# --- faked component, dummy to allow registration with unopkg, no functionality expected

# これは、すべてのスクリプトファイルに、追加する必要があります。
# org.openoffice.script.DummyImplementationForPythonScriptsという名前を別のものに変更する必要があります。
#　オフィス・インストール内で、一意である必要があります！）
#　（偽のコンポーネント、nopkgで登録を可能にするためにダミー、期待される機能は、存在しない


import unohelper
g_ImplementationHelper = unohelper.ImplementationHelper()
g_ImplementationHelper.addImplementation( \
        None,"org.openoffice.script.DummyImplementationForPythonScripts", \
    ("org.openoffice.script.DummyServiceForPythonScripts",),)

既定では、すべての.pyファイルは、UNOコンポーネントとして判断されます。.pyファイル内で、上記の行がないと、配布の間にエラーが発生します。

ディレクトリ名（ここではパッケージ）は自由に選択できます。Pythonスクリプトを持つuno-packageには、自由に選ばれたディレクトリ名を指定する必要がある、META-INF/manifest.xmlが含まれている必要があります。

<?xml version="1.0" encoding="UTF-8"?>
<!DOCTYPE manifest:manifest PUBLIC "-//OpenOffice.org//DTD Manifest 1.0//EN" "Manifest.dtd">
<manifest:manifest xmlns:manifest="http://openoffice.org/2001/manifest">
<manifest:file-entry manifest:media-type="application/vnd.sun.star.framework-script" manifest:full-path="package"/>
</manifest:manifest>

すべてのユーザーは、パッケージ・マネージャーによってパッケージを追加することができます（Tools/Packageマネージャー）。

備考: パッケージ内のコンテンツは、開発の仕組みではなく、本当に、純粋な配布であり、読み取り専用で設計されています。これは、なぜ、パッケージのスクリプトが、Tools/Macros/Organize macros/Pythonダイアログを表示できないかの理由かもしれません。OpenOffice.orgの共有ディレクトリのuno-packageに埋め込む（読取専用）

パッケージは、管理者によって、完全なOpenOffice.orgインストールに追加されている場合があります。 そのため、すべてのユーザーは、パッケージ内にあるマクロを実行することができます。これは、unopkgツールを使って行うことができます。

Script coding

OpenOffice.orgのスクリプト・フレームワーク内のPythonスクリプトは、.pyファイル内の関数（defキーワードによって導入される）です。Tools/Macros/Runマクロ・ダイアログを使用して実行するには、スクリプトには、空の引数リストが必要です。典型的なイベント・リスナーのため、関数は、正確に1つの引数（イベント）を持っている必要があります。一般に、引数の数は、関数が使われるコンテクストによってきまります。現在、.pyファイルは、unixの改行を使用する必要があります。これは、今後、変更される可能性があります。

一つの.pyファイルに、任意の数の関数定義が含まれている場合があります。既定では、すべての関数定義は、エクスポートされます（=マクロの選択範囲ダイアログに表示される）。これは、面倒になるかもしれないので、エクスポートは、関数定義のタプルのg_exportedScriptsという名前のグローバル変数を持つことによって、より小さな関数群に制限することができます。

現在の統合レベルでは、.pyファイルは、Python PYTHONPATH内にある、Pythonモジュールを一つだけインポートすることができます。既定では、これは、その標準ライブラリとunoブリッジ・ファイルを持つ、Pythonランタイムです。これは、Pythonマクロが、他のPythonマクロ・ファイルを参照できないことを示しています。この制限は、今後、変更される可能性がありますが、現在は、存在します。もちろん、Pythonマクロは、どんなモジュールのPYTHONPATHの場所にも、インポートできます。;しかし、あなたは、あなた自身で行う必要があり、そして、結果は、移植できません。（読者の疑問：pythonloaderは、自動的に、OOoスクリプト・ディレクトリを、PYTHONPATHに添付することができませんでしたか？）

モジュール内でソース・コードを実行する前に、グローバル変数のXSCRIPTCONTEXTは、モジュール内に、グローバル変数として挿入されます。（また、この変数が存在します。例えば、javascriptとbeanshellのため、それは、一貫性の理由から、ここに提供されています）。それは、3つのメンバーを持っています （Document,DesktopとComponentContext）。

関数のコメント（導入され、3で終わる）は、マクロの選択ダイアログの説明として表示されます。

コンパイルされたPythonスクリプト・ファイルは、sys.modulesに追加されません。同じモジュールの複数のインスタンスが、同時に存在することがあります。

例：

# HelloWorld python script for the scripting framework
#　スクリプト・フレームワークのためのHelloWorld Pythonスクリプト

 #  Prints the string 'Hello World(in Python)' into the current document
def HelloWorldPython( ):
    """文字列 'Hello World（Pythonで）'を現在のドキュメントに出力します。"""
    #get the doc from the scripting context which is made available to all scripts
    # すべてのスクリプトを利用可能にする、スクリプト・コンテキストからドキュメントを取得する。
    model = XSCRIPTCONTEXT.getDocument()
    text = model.Text
    cursor = text.createTextCursor()
    text.insertString( cursor, "Hello World(in Python)", 0 )

Error handling and debugging

コンパイル中やスクリプトの実行中にエラーが発生した場合、可能であれば、スクリプト・フレームワークの例外として扱います。一般的には、スクリプト・フレームワークは、ポップアップ・ボックスを開きます。そして、投げられた例外のメッセージを表示します。

しかしながら、時には、これは不可能です。そして、エラーは、暗黙のうちに無視されます。

ユーザーは、以下の時、これらのエラーを理解します。

• 彼のPythonスクリプト・ファイルは、あると期待される場所に表示されません。
• スクリプト・ファイルの名前が、表示されます。しかし、それは、スクリプトは含まれていません。
• スクリプトの一部だけが、実行されます。

あなたは、OpenOffice.org 3/Basis/program/pythonscript.pyファイルで、いくつかのフラグを変更することによって、これらの問題を知ることができます。

# Configuration ----------------------------------------------------
LogLevel.use = LogLevel.NONE                # alternavly use LogLevel.ERROR or LogLevel.DEBUG
                                                                                        # 代わりに、LogLevel.ERRORやLogLevel.DEBUGを使用します。
LOG_STDOUT = False                          # True, writes to stdout
                                                                                        # Trueは、標準出力に書き込みます
                                            # False, writes to user/Scripts/python/log.txt
                                            # Falseは、user/Scripts/python/log.txtに記述します
ENABLE_EDIT_DIALOG=False                    # offers a minimal editor for editing
                                                                                        # 編集のための最低限のエディタを提供します。

Pythonデバッガの添付は、現在サポートされません。

Credits

スクリプト・フレームワークのPython結合は、Joerg Budischewskiによって、彼の余暇に開発され、保守されています。彼の素晴らしいサポートとこのバインディングを可能にしたフレームワークへの彼のコードの追加のために、Sunから、Tomas O'Connorへ極めて多くの感謝をします。バインディングの質問については、api@openoffice.apache.orgに投稿してください。