StarDesktop

com.sun.star.frame.Desktop サービスは、Apache OpenOffice のコアサービスとよく似た機能を備えています。これにより、すべてのドキュメントウィンドウを管理する Apache OpenOffice のフレームオブジェクトを扱うための機能が提供されます。またドキュメントの作成、オープン、インポートをする際にも、このサービスを使用します。
個々のドキュメントオブジェクトの基本機能は、com.sun.star.document.OfficeDocument サービスで提供されます。たとえばこのサービスには、ドキュメントの保存、エクスポート、印刷を行うためのメソッドが用意されています。

com.sun.star.frame.Desktop サービスは、Apache OpenOffice が起動すると自動的に作成されます。Apache OpenOffice Basic では、大域名 StarDesktop を使用して、このサービスを操作できます。

StarDesktop の最も重要なインターフェースは com.sun.star.frame.XComponentLoader です。これは主として、ドキュメントの作成、インポート、オープンの操作を担う loadComponentFromURL メソッドをカバーしています。

StarDesktop というオブジェクト名の起源は、StarOffice 5 の時代にまで遡るもので、当時は StarDesktop という 1 つのアプリケーションにすべてのドキュメントを埋め込む形で処理していました。Apache OpenOffice の現行バージョンでは、この StarDesktop を目に見える形で使用することはありません。ただし、StarDesktop という名称は、アプリケーション全体の基本オブジェクトであることが直感的に分かりやすいため、現在でも Apache OpenOffice のフレームオブジェクトに対して使われています。

StarDesktop オブジェクトは、以前はルートオブジェクトとして適用されていた StarOffice 5 の Application オブジェクトに代わるものです。ただし従来の Application オブジェクトとは異なり、こちらは主として新規ドキュメントのオープン処理を担当しています。従来の Application オブジェクトで使われていた、Apache OpenOffice のオンスクリーン描画コントロール用の機能 (たとえば FullScreen、FunctionBarVisible、Height、Width、Top、Visible など) は、現在では使用されていません。

アクティブドキュメントへアクセスする際に、Word では Application.ActiveDocument を使用し、Excel では Application.ActiveWorkbook を使用するのに対して、Apache OpenOffice の場合は、StarDesktop がこれらの役割を果たします。Apache OpenOffice でアクティブドキュメントオブジェクトへアクセスするには、StarDesktop.CurrentComponent プロパティーまたは ThisComponent を使用します。

ThisComponent

ThisComponent は StarDesktop.CurrentComponent とほぼ同じオブジェクトを返しますが、1 つ大きな利点があります。Basic IDE 内から実行、デバッグ、または調査している場合、StarDesktop は Basic IDE 自体を返します。これはおそらく意図したものとは異なります。ThisComponent は、最後のアクティブなドキュメントを返します。

Apache OpenOffice でのドキュメントに関する基本知識

Apache OpenOffice ドキュメントを操作する際に、Apache OpenOffice の行うドキュメント管理に関する基本的な知識があると有用です。このような知識としては、Apache OpenOffice ドキュメントでのファイル名の扱い方や、ファイル保存時に使用されるフォーマットなどが該当します。

ファイル名の URL 指定

Apache OpenOffice は、個々のプラットフォームに拘束されないアプリケーションとして設計されているため、ファイル名の取り扱いについても、Internet Standard RFC 1738 に準拠した URL 指定法を採用しています (URL 指定はオペレーティングシステムに依存しない)。この規則を使用する標準ファイル名は、最初に接頭辞 file:/// があり、その後にローカルパスが続きます。ファイル名にサブディレクトリを含む場合、ディレクトリ間の区切り記号は、Windows で用いられるバックスラッシュ (日本語フォントでは半角円記号) ではなく、フォワードスラッシュで区切ります。たとえば次のパスは、C ドライブ直下の doc ディレクトリにある test.odt ファイルを示しています。

file:///C:/doc/test.odt

ローカルのファイル名を URL に変換するには、Apache OpenOffice に用意されている ConvertToUrl 関数を使用します。逆に URL をローカルファイル名に変換するには、Apache OpenOffice に用意されている ConvertFromUrl 関数を使用します。

MsgBox ConvertToUrl("C:\doc\test.odt") 
  ' supplies file:///C:/doc/test.odt
MsgBox ConvertFromUrl("file:///C:/doc/test.odt")    
  '  supplies (under Windows) c:\doc\test.odt

このサンプルコードでは、ローカルのファイル名を URL に変換して、メッセージボックスに表示しています。その次に、URL をローカルファイル名に変換して、メッセージボックスに表示しています。

Internet Standard RFC 1738 をベースにしたため、ファイル名に 0-9、a-z、A-Z の文字を使用できます。URL でこれ以外の文字を使用する場合は、エスケープ処理をする必要があります。この処理は、エスケープする文字を Unicode の UTF-8 エンコーディング内の該当 16 進値に変換して、パーセント記号を前に付けることで行います。たとえば、ローカルファイル名に半角スペース記号が含まれている場合、URL 内で半角スペース記号は %20 と表記します。

XML ファイルフォーマット

Apache OpenOffice は、XML ベースのファイルフォーマットを使用します。XML を使用しているので、ファイルを他のプログラムで開いて編集できます。

ファイルの圧縮

XML は通常のテキストファイルをベースとしているので、一般に最終的なファイルサイズは非常に大きくなります。このため、Apache OpenOffice では、ファイルを ZIP 形式で圧縮して保存するようにしています。ただし、storeAsURL メソッドのオプションを使用すると、XML ファイル形式で直接保存することができます。詳細は、「storeAsURL メソッドオプション」を参照してください。

ドキュメントの作成、オープン、インポート

ドキュメントのオープン、インポート、作成は、次のメソッドを使用して行います。

StarDesktop.loadComponentFromURL(URL, Frame, SearchFlags, FileProperties)

ここで、loadComponentFromURL の第 1 パラメータには、対象とするファイルの URL を指定します。

loadComponentFromURL の第 2 パラメータには、管理用に Apache OpenOffice が内部的に作成するウィンドウのフレームオブジェクト名を指定します。通常ここには事前定義されている _blank という名前を使用しますが、この場合 Apache OpenOffice は新規ウィンドウを作成します。その他にも、_hidden という名前も指定できます。この場合は該当ドキュメントを読み込んで非表示状態にします。

実際、Apache OpenOffice ドキュメントを開くのに必要なのは上記 2 つのパラメータだけで、残り 2 つのパラメータは単なるプレースホルダ (ダミー値) として指定するだけです。

Dim Doc As Object
Dim Url As String
Dim Dummy() 'It is an (empty) array of PropertyValues
 
Url = "file:///C:/test.odt"
 
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy)

上記のサンプルコードでは、text.odt ファイルを開いて、新規ウィンドウとして表示しています。

Apache OpenOffice Basic では、ここで説明した方式により任意の数のドキュメントを開くことができ、これらのドキュメントオブジェクトを操作することにより各ドキュメントを編集することもできます。

StarDesktop.loadComponentFromURL は、Apache OpenOffice API の従来バージョンにあった Documents.Add および Documents.Open メソッドに代わるものです。

ドキュメントウィンドウの内容の書き換え

パラメータ Frame の値として、事前定義された _blank および _hidden という名前を指定すると、Apache OpenOffice は loadComponentFromURL の呼び出し時に新規ウィンドウを作成します。ただし状況によっては、既存ウィンドウの内容を書き換える方が便利な場合もあります。このような処理を行うには、ウィンドウのフレームオブジェクトに明示的な名前が付いている必要があります。ただし、この名前の先頭には下線記号は使えないので注意が必要です。また、該当するフレームワークが存在しない場合、これを作成するにはパラメータ SearchFlags を指定する必要があります。パラメータ SearchFlags には、次の定数値を指定できます。

SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
              com.sun.star.frame.FrameSearchFlag.ALL

次のサンプルコードは、フレームパラメータと SearchFlags を使って、オープン済みのウィンドウを書き換える方法を示しています。

Dim Doc As Object
Dim Dummy() 
Dim Url As String
Dim SearchFlags As Long
 
SearchFlags = com.sun.star.frame.FrameSearchFlag.CREATE + _
              com.sun.star.frame.FrameSearchFlag.ALL
Url = "file:///C:/test.odt"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", SearchFlags, Dummy)
MsgBox "Press OK to display the second document."
 
Url = "file:///C:/test2.odt"
Doc = StarDesktop.loadComponentFromURL(Url, "MyFrame", _
      SearchFlags, Dummy)

この例ではまず最初に、フレーム名を MyFrame とした新規ウィンドウの中に、test.odt という名前のファイルを開いています。そしてメッセージボックスで操作の確認をしてから、ウィンドウの内容を test2.odt というファイルに書き換えています。

loadComponentFromURL メソッドのオプション

loadComponentFromURL 関数の 4 番目のパラメータは、PropertyValue データフィールドです。このパラメータは、ドキュメントのオープンと作成に対するさまざまなオプションを Apache OpenOffice に提供します。このデータフィールドについては、個々のオプションごとに PropertyValue 構造体を用意して、オプション名を示す文字列や必要な設定値を格納する必要があります。

loadComponentFromURL には次のオプションを指定できます。

AsTemplate (Boolean): これが True の場合、指定 URL からドキュメントを読み込み、新規の無題ドキュメントとして表示します。False の場合は、テンプレートファイルを編集モードで読み込みます。
CharacterSet (String): ドキュメントの基になっている文字セットを定義します。
FilterName (String): loadComponentFromURL 関数用の特殊なフィルタを指定します。指定可能なフィルタ名は、ファイル \share\config\registry\instance\org\openoffice\office\TypeDetection.xml で定義されています。
FilterOptions (String): フィルタ用の追加オプションを定義します。
JumpMark (String): ドキュメントのオープン後に、JumpMark の指定位置にジャンプします。
Password (String): 保護されたファイルのパスワードを転送します。
ReadOnly (Boolean): 読み取り専用のドキュメントを読み込みます。

次のサンプルコードは、FilterName オプションを使用して、コンマ区切りのテキストファイルを Apache OpenOffice Calc で開く方法を示しています。

Dim Doc As Object
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue
Dim Url As String
 
Url = "file:///C:/csv.doc"
FileProperties(0).Name = "FilterName"
FileProperties(0).Value ="scalc: Text - txt - csv ({{OOo}} Calc)"
 
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, FileProperties())

この場合の FileProperties データフィールドは 1 つの値しか使っていませんが、これは指定するオプションが 1 つだけだからです。Filtername プロパティーは、Apache OpenOffice が Apache OpenOffice Calc テキストフィルタを使用してファイルを開くかどうかを指定しています。

新規ドキュメントの作成

URL 指定されたものがテンプレートであった場合、Apache OpenOffice は自動的に新規ドキュメントを作成します。

このような場合に空白ドキュメントが必要であれば、次のような形式で URL に private:factory と指定します。

Dim Dummy() 
Dim Url As String
Dim Doc As Object
 
Url = "private:factory/swriter"
Doc = StarDesktop.loadComponentFromURL(Url, "_blank", 0, Dummy())

上記のサンプルコードを実行すると、Apache OpenOffice Writer の空白ドキュメントが作成されます。

ドキュメントオブジェクト

前節で説明した loadComponentFromURL 関数は、戻り値としてドキュメントオブジェクトを返します。そのサポートする com.sun.star.document.OfficeDocument サービスは、次の 2 つの主要なインターフェースを提供しています。

com.sun.star.frame.XStorable インターフェースは、ドキュメントの保存を担当します。
com.sun.star.view.XPrintable インターフェースは、ドキュメント印刷用のメソッドを含みます。

ドキュメントの保存とエクスポート

Apache OpenOffice ドキュメントの保存処理は、ドキュメントオブジェクトを通じて直接実行されます。このような処理を行うには、com.sun.star.frame.XStorable インターフェースの store メソッドを、次のような形で使用します。

Doc.store()

このメソッドは、ドキュメントへのメモリ割り当てがすでに終了している場合にのみ機能します。ただしこの条件は、新規ドキュメントの場合には該当しません。そのような場合は、storeAsURL メソッドを使用します。このメソッドは com.sun.star.frame.XStorable でも定義されており、次のようにドキュメントの保存位置を指定する際に使用できます。

Dim URL As String
Dim Dummy()
 
Url = "file:///C:/test3.odt"
Doc.storeAsURL(URL, Dummy())

これらのメソッドの他に com.sun.star.frame.XStorable には、ドキュメントの保存に関するいくつかのサポート用メソッドが用意されています。以下にその属性を示します。

hasLocation(): ドキュメントに既に URL が割り当てられているかどうかを指定します。
isReadonly(): ドキュメントが読み取り専用であるかを指定します。
isModified(): 前回保存時からドキュメントが変更されているかを指定します。

ドキュメント保存用のプログラムコードを作成する際には、これらのオプションを利用することで、変更箇所があるドキュメントのみ保存処理を進めたり、名前が指定されていない場合のみファイル名の指定を要求するなどの機能を組み込むことができます。

If (Doc.isModified) Then
  If (Doc.hasLocation And (Not Doc.isReadOnly)) Then
    Doc.store()
  Else
    Doc.storeAsURL(URL, Dummy())
  End If
End If

上記のサンプルコードでは、まず最初に、前回保存時からドキュメントが変更されているかを確認しています。そして変更箇所がある場合のみ、残りの保存処理を継続します。次に、ドキュメントの URL 指定の有無と、読み取り専用でないことを確認し、双方の条件を満たしている場合のみ、既存の URL に対してドキュメントを保存します。URL 指定が完了していない場合、あるいは読み取り専用で開かれている場合は、URL を新規指定して保存する処理を行います。

storeAsURL メソッドのオプション

loadComponentFromURL メソッドと同様に、storeAsURL メソッドも、PropertyValue データフィールドを使ったいくつかのオプションを指定できます。これらのオプションは、Apache OpenOffice によるドキュメント保存に関する指定を行います。storeAsURL メソッドで指定できるのは、次のオプションです。

CharacterSet (String): ドキュメントの基になっている文字セットを定義します。
FilterName (String): loadComponentFromURL 関数用の特殊なフィルタを指定します。指定可能なフィルタ名は、ファイル \share\config\registry\instance\org\openoffice\office\TypeDetection.xml で定義されています。
FilterOptions (String): フィルタ用の追加オプションを定義します。
Overwrite (Boolean): 既存ファイルを警告なしで上書きするかを指定します。
Password (String): 保護されたファイルのパスワードを転送します。
Unpacked (Boolean): ドキュメントを (圧縮しないで) サブディレクトリに保存します。

次のサンプルコードは、storeAsURL での Overwrite オプションの使用例です。

Dim Doc As Object
Dim FileProperties(0) As New com.sun.star.beans.PropertyValue
Dim Url As String
' ... Initialize Doc 
 
Url = "file:///c:/test3.odt"
FileProperties(0).Name = "Overwrite"
FileProperties(0).Value = True
Doc.storeAsURL(sUrl, mFileProperties())

このサンプルコードでは、同名のファイルが存在した場合、指定ファイル名で Doc を保存します。

ドキュメントの印刷

ドキュメントの保存と同様に、ドキュメントの印刷も該当オブジェクトから直接行えます。このような操作には、com.sun.star.view.Xprintable インターフェースの Print メソッドを使用します。次のサンプルコードは、print メソッドを呼び出す際の基本パターンです。

Dim Dummy()
 
Doc.print(Dummy())

loadComponentFromURL メソッドの場合と同様に、パラメータの Dummy には PropertyValue データフィールドを使用し、この値を通じて Apache OpenOffice の印刷オプションを指定します。

print メソッドのオプション

print メソッドのパラメータは、PropertyValue データフィールドの形で与えますが、その値には Apache OpenOffice の印刷用ダイアログの項目に対応した内容を指定します。

CopyCount (Integer): 印刷する部数を指定します。
FileName (String): 指定したファイルのドキュメントを印刷します。
Collate (Boolean): 複数部数の印刷でページの丁合をとるよう、プリンタに指示します。
Sort (Boolean): 複数の部数を印刷するときに (CopyCount > 1)、ページをソートします。
Pages (String): 印刷するページを指定します (表記規則は印刷用ダイアログのものと同じ)。

次のサンプルコードでは、Pages オプションを使って特定ページのみを印刷します。

Dim Doc As Object
Dim PrintProperties(0) As New com.sun.star.beans.PropertyValue
 
PrintProperties(0).Name="Pages"
PrintProperties(0).Value="1-3; 7; 9"
Doc.print(PrintProperties())

プリンタの選択と設定

プリンタの選択には、com.sun.star.view.XPrintable インターフェースの Printer プロパティーを使用します。このプロパティーには、PropertyValue データフィールドを使って、次の内容を設定します。

Name (String): プリンタの名前を指定します。
PaperOrientation (Enum): 用紙の向きを指定します (com.sun.star.view.PaperOrientation.PORTRAIT は縦、com.sun.star.view.PaperOrientation.LANDSCAPE は横)。
PaperFormat (Enum): 用紙の形式を指定します (たとえば、com.sun.star.view.PaperFormat.A4 は DIN A4、com.sun.star.view.PaperFormat.Letter は US レター)。
PaperSize (Size): 用紙サイズを 100 分の 1 ミリ単位で指定します。

次のサンプルコードでは、Printer プロパティーを使ってプリンタを選択し、用紙サイズを設定します。

Dim Doc As Object
Dim PrinterProperties(1) As New com.sun.star.beans.PropertyValue
Dim PaperSize As New com.sun.star.awt.Size
 
PaperSize.Width = 20000   ' corresponds to 20 cm
PaperSize.Height = 20000   ' corresponds to 20 cm
PrinterProperties (0).Name="Name"
PrinterProperties (0).Value="My HP Laserjet"
PrinterProperties (1).Name="PaperSize"
PrinterProperties (1).Value=PaperSize
Doc.Printer = PrinterProperties()

ここでは、PaperSize という名前で com.sun.star.awt.Size 型のオブジェクトを作成します。用紙サイズの指定には、このタイプのオブジェクトが必要です。さらに、PrinterProperties という名前の 2 つの PropertyValue エントリに対するデータフィールドを作成します。このデータフィールドには、初期化もかねて Printer プロパティーに渡す値を代入します。なお UNO では、プリンタはリアル属性ではなくイミテーション属性として扱われます。

Content on this page is licensed under the Public Documentation License (PDL).