第 4 章 StarSuite API について

StarSuite API とは、StarSuite へのアクセスに使用する汎用プログラミングインターフェースです。 StarSuite ドキュメントの作成、オープン、変更、印刷を行うには、このような StarSuite API を利用します。 またユーザーが定義したマクロやダイアログを使用して、StarSuite の機能を拡張するオプションも用意されています。

StarSuite API の使用は、必ずしも StarSuite Basic に限定されるものではなく、必要であれば Java や C++ などのプログラミング言語から利用することもできます。 そのような場合は、各種プログラミング言語との間のインターフェースとして、Universal Network Objects (UNO) と呼ばれる機能を利用します。

この章では、UNO を併用することで、StarSuite Basic から StarSuite を制御する方法に焦点を当てて説明します。 それにはまず、StarSuite Basic プログラミングの視点から、UNO の主要な概念について理解しておく必要があります。 個々の StarSuite API の使用法に関する詳細については、後半の章で説明します。

Universal Network Objects (UNO)

StarSuite には Universal Network Objects (UNO) という形式のプログラミングインターフェースが用意されています。 これはオブジェクト指向型のプログラミングインターフェースであり、StarSuite の場合、プログラム内から行う Office パッケージへのアクセスのタイプごとに細分化されています。

StarSuite Basic は手続き型のプログラミング言語であるため、UNO の導入に伴い、いくつかの機能が追加されています。

StarSuite Basic でUniversal Network Object を使用するにあたっては、使用するオブジェクトに対応した変数宣言が必要です。 この宣言は Dim 命令で実行します (詳細は第 2 章「StarSuite Basic のプログラミング言語」を参照)。 オブジェクトを宣言する際には、宣言型に Object を指定します。

Dim Obj As Object

たとえば上記のサンプルコードは、Obj という名前のオブジェクトを宣言しています。

新規作成したオブジェクト変数は、使用する前に初期化する必要があります。 このような処理には、createUnoService 関数を使用します。

Obj = createUnoService("com.sun.star.frame.Desktop")

上記のサンプルコードの場合、新規作成したオブジェクトへの参照情報を変数 Obj へ割り当てています。 また com.sun.star.frame.Desktop はいわゆるオブジェクト型に類似したものですが、UNO の用語ではこのようなものを「型」ではなく「サービス」と呼んでいます。 UNO の流儀に従えば、上記の Obj は「com.sun.star.frame.Desktop サービスをサポートしたオブジェクトに対する参照」と表現できます。 つまり StarSuite Basic で使われる「サービス」という用語は、他の言語で言う「型 (タイプ)」 や「クラス」に該当します。

ただし Universal Network Object の持つ大きな特徴として、複数のサービスを同時にサポートできる点があります。 このため UNO のサービスの中には他のサービスをサポートしているものが存在し、1 つのオブジェクトで複数のサービスを扱うケースがあります。 たとえば先のサンプルコードでは com.sun.star.frame.Desktop サービスをサポートしたオブジェクトを作成しましたが、このオブジェクトもその他のサービスとして、ドキュメント読み込み用およびプログラム終了用のサービスをサポートしています。

---

注 –

VBA のオブジェクト構造は、所属するクラスにより定義しますが、StarSuite Basic のオブジェクト構造は、サポートするサービスにより定義します。 VBA のオブジェクトは、常に 1 つのクラスに対して割り当てられます。 これに対して、StarSuite Basic のオブジェクトは複数のサービスをサポートできます。

---

属性とメソッド

StarSuite Basic の各オブジェクトからは、各種の属性とメソッドを呼び出すことができます。

属性

ここで言う 属性 とはオブジェクトのもつ属性と同様のもので、たとえば Document オブジェクトには、Filename や Title などの属性が存在します。

属性は、値を代入することにより設定されます。

Document.Title = "StarSuite 8 Basic Programmer's Guide"
Document.Filename = "progman.sxv"

各属性には、通常の変数と同様に、どのような値を格納できるかを規定するタイプ (型) が存在します。 上記のサンプルコードの Filename および Title 属性は、文字列タイプの一種です。

リアル属性とイミテーション属性

StarSuite Basic の各オブジェクトのもつ属性の大部分は、UNO サービスとして定義されています。 StarSuite Basic の属性には、このような「リアル」な属性以外にも、UNO レベルの 2 つのメソッドから成る属性が存在します。 その一方は、その属性値を取得する際に、もう一方は値を指定する際に使用します (get および set メソッド)。 つまり、このような属性は、これら 2 つのメソッドの「イミテーション」として存在するとも言えます。 たとえば UNO の文字オブジェクトには、該当するキーポイントの取得と変更を行う getPosition と setPosition というメソッドが用意されています。 StarSuite Basic のプログラムでこのような値にアクセスするには、Position 属性を使用できます。 そしてこれらとは独立した形で、オリジナルのメソッドも使用できます (ここでの例の場合は getPosition と setPosition)。

メソッド

メソッドとは、特定のオブジェクトを指定して実行する、一種の関数と見なすことができます。 たとえば先に説明した Document オブジェクトには、Save というメソッドが存在し、これは以下のような形式で使用します。

Document.Save()

このようなメソッドを使用する際には、関数を呼び出す場合と同様に、パラメータの指定および戻り値の取得が行えます。 実際そのようなメソッドの呼び出しは、通常の関数と同様の形式で行えます。 以下のサンプルコードは、このようなメソッド指定の例です。

Ok = Document.Save(True)

この場合は、ドキュメントオブジェクトの Save メソッドを呼び出す際に、パラメータとして True を指定しています。 この Save メソッドによる処理が終了すると、その戻り値が変数 Ok に格納されます。

モジュール、サービス、インターフェース

StarSuite には数百のサービスが提供されています。 このような膨大な数のサービスを整理するため、これらはモジュールという形にまとめられています。 単に機能面で見た場合、StarSuite Basic のモジュールには、それ以上の意味は特にありません。 ただし、サービス名を指定する際には、該当するモジュール名も含める必要があります。 完全な形のサービス名は、StarSuite のサービスであることを示す com.sun.star に続けて、frame などのモジュール名の指定が入り、最後に Desktop などの実際のサービス名が続きます。 つまりこの場合の完全な名前は、以下のようになります。

com.sun.star.frame.Desktop

そして UNO の場合、モジュール名とサービス名の項目に加えて「インターフェース」の項目が続きます。 このような項目は Java プログラミングではお馴染みのものですが、通常の Basic プログラミングで使われるものではありません。

各インターフェースは、複数のメソッドを組み合わせて使用します。 厳密には、UNO のサービスはメソッドではなくインターフェースをサポートし、これらのインターフェースが各種のメソッドを提供していると表現できます。 つまりメソッドは、インターフェース内のサービスに対して (組み合せとして) 割り当てられているのです。 Java や C++ などでプログラミングを行う場合、メソッドを要求するときにインターフェースが必要となるため、このような関係に注意を特に払う必要があります。 ただし StarSuite Basic では、このような関係は適用されません。 この場合メソッドの呼び出しは、該当オブジェクトから直接行います。

ただし、各サービスごとに複数のインターフェースが使用されるため、各種のインターフェースに割り当てられているメソッドの関係を把握しておくと、API の扱い方を理解する助けになります。 これは、ある 1 つのインターフェースに関する知識があれば、複数のサービスでその知識を生かせるためです。

複数のサービスで使用される主要なインターフェースのうち、使用頻度の高いものについては、本章の最後で再度説明します。

UNO の関連ツール

UNO で使われるオブジェクトやサービスに関しては、何がどの属性、メソッド、インターフェースをサポートしているのかという点と、それをどのように確認するかという問題が残っています。 オブジェクトに関する情報については、このマニュアル以外にも、supportsService メソッドおよびデバッグ用の各種メソッドのほか、『開発ガイド』および『API reference』を参照してください。

supportsService メソッド

UNO オブジェクトの多くが supportsService メソッドをサポートしており、このメソッドを使用することで、個々のオブジェクトが特定のサービスをサポートしているかを確認できます。 このメソッドは、以下のような形式で使用します。

Ok = TextElement.supportsService("com.sun.star.text.Paragraph")

この場合は、TextElement オブジェクトが com.sun.star.text.Paragraph サービスをサポートしているかを確認しています。

デバッグの属性

StarSuite Basic では、各 UNO オブジェクトごとに使用可能な属性、メソッド、インターフェースに関する情報が、あらかじめ登録されています。 このような情報は属性として取得可能で、該当項目が一覧形式で表示されます。 これに該当するのは、以下の属性です。

DBG_properties - オブジェクトの全属性を文字列で返します。

DBG_methods - オブジェクトの全メソッドを文字列で返します。

DBG_supportetInterfaces - オブジェクトの全インターフェースを文字列で返します。

以下のサンプルコードは、DBG_properties と DBG_methods の使用例です。 ここでは、まず com.sun.star.frame.Desktop サービスを作成してから、そのサポートする属性とメソッドをメッセージボックスに表示させます。

Dim Obj As Object
Obj = createUnoService("com.sun.star.frame.Desktop")

MsgBox Obj.DBG_Propierties
MsgBox Obj.DBG_methods

DBG_properties を使用する場合、戻り値として返される属性の中には、単に分類上の都合で該当サービスで使用可能とされているだけの属性もあるので注意が必要です。 つまり、これらの属性が実際に該当サービスで使用できるかについては、保証されていません。 そのため、このような属性を利用する際には、IsEmpty 関数を使って利用できるかを確認する必要があります。

API Reference

使用可能なサービスおよび、該当するインターフェース、メソッド、属性に関するより詳細な情報は、StarSuite API の『API reference』に収録されています。 入手先は、www.openoffice.org の以下のアドレスです。

http://api.openoffice.org/docs/common/ref/com/sun/star/module-ix.html

主なインターフェースの概要

StarSuite のインターフェースの中には、StarSuite API の各所で使用されるものが存在します。 これらは、各種の処理に利用可能な抽象的タスクを実行する一連のメソッドを規定しています。 ここではこのようなインターフェースのうち、使用頻度の高いものについて、その概要を説明します。

オブジェクトの出所については、このマニュアルの後半で説明します。 ここでは単に、StarSuite API が主要なインターフェースを提供するオブジェクトについて、その抽象的な機能のいくつかを簡単に説明するにとどめておきます。

コンテキスト依存型オブジェクトの作成

StarSuite API でオブジェクトを作成するには、2 通りの方法が存在します。 その 1 つは、この章の初めに説明した createUnoService 関数を使用する方法です。 createUnoService 関数は、広域的に使用可能なオブジェクトを作成します。 このようなオブジェクトやサービスは、コンテキスト非依存型サービス とも呼びます。

このようなコンテキスト非依存型サービスに対するものとして、コンテキスト依存型サービス も存在し、この場合のオブジェクトは他のオブジェクトと併用することでのみ使用できます。 たとえば、ある表計算ドキュメントに配置された図形描画オブジェクトは、このドキュメントと共存することにより存在できます。

com.sun.star.lang.XMultiServiceFactory Interface

通常、コンテキスト依存型のオブジェクトを作成するには、そのオブジェクトの依存相手のオブジェクトメソッドを使用します。 createInstance メソッドは、XMultiServiceFactory インターフェースで規定されているもので、主としてドキュメントオブジェクトに対して使用します。

たとえば、先に説明した図形描画オブジェクトを作成するには、以下のサンプルコードのように、オブジェクトとして表計算ドキュメントを使用します。

Dim RectangleShape As Object

RectangleShape = _
   Spreadsheet.createInstance("com.sun.star.drawing.RectangleShape")

同様に、文書ドキュメントの段落テンプレートは、以下のサンプルコードのようにして作成します。

Dim Style as Object 
Style = Textdocument.createInstance("com.sun.star.style.ParagraphStyle")

下位オブジェクトへの名前付きアクセス

下位オブジェクトを持つオブジェクトで自然言語名によるアクセスが可能なものに対しては、XNameAccess および XNameContainer インターフェースを使用します。

このうち XNamedAccess は個々のオブジェクトに対するアクセスを行い、XNameContainer は各要素の挿入、変更、削除を行います。

com.sun.star.container.XNameAccess インターフェース

ここでは XNameAccess の使用例として、表計算ドキュメントの表 (シート) オブジェクトを扱う場合を取り上げます。 このオブジェクトは表計算ドキュメント内のすべてのページをまとめたものとして扱われます。 そのため各ページへのアクセスには、XNameAccess の getByName メソッドを使用します。

Dim Sheets As Object
Dim Sheet As Object

Sheets = Spreadsheet.Sheets
Sheet = Sheets.getByName("Sheet1")

すべての要素の名前を取得するには、getElementNames メソッドを使用します。 これを実行すると、該当する名前を収めたデータフィールド (配列) が返されます。 以下のサンプルコードは、ループを使用して表計算ドキュメント内のすべての要素名を取得し、表示します。

Dim Sheets As Object
Dim SheetNames
Dim I As Integer

Sheets = Spreadsheet.Sheets
SheetNames = Sheets.getElementNames

For I=LBound(SheetNames) To UBound(SheetNames)
   MsgBox SheetNames(I)
Next I

基本オブジェクト内に該当する名前の下位オブジェクトが存在するかを確認するには、XNameAccess インターフェースの hasByName メソッドを使用します。 以下のサンプルコードは、Spreadsheet オブジェクトに Sheet1 という名前のページがあるかを確認して、その結果をメッセージボックスに表示します。

Dim Sheets As Object

Sheets = Spreadsheet.Sheets
If Sheets.HasByName("Sheet1") Then
   MsgBox " Sheet1 available"
Else
   MsgBox "Sheet1 not available"
End If

com.sun.star.container.XNameContainer インターフェース

基本オブジェクトの下位にある要素に対する挿入、変更、削除を行うには、XNameContainer インターフェースを使用します。 ここでは、insertByName、removeByName、replaceByName の各メソッドを使用できます。

これらは通常、以下のサンプルコードのように使用します。 この場合は、文書ドキュメントの StyleFamilies オブジェクトを使用して、ドキュメントの段落テンプレート (ParagraphStyles) に対する操作を行なっています。

Dim StyleFamilies As Objects
Dim ParagraphStyles As Objects
Dim NewStyle As Object   

StyleFamilies = Textdoc.StyleFamilies
ParagraphStyles = StyleFamilies.getByName("ParagraphStyles")

ParagraphStyles.insertByName("NewStyle", NewStyle)      
ParagraphStyles.replaceByName("ChangingStyle", NewStyle)   
ParagraphStyles.removeByName("OldStyle")            

ここで insertByName の行は、 NewStyle というスタイルを「NewStyle」という名前でオブジェクト ParagraphStyles に挿入しています。 その次の replaceByName の行は、ChangingStyle で指定するオブジェクトを、NewStyle に変更しています。 最後に、removeByName の行は、OldStyle で指定するオブジェクトを、ParagraphStyles から削除しています。

インデックス方式による下位オブジェクトへのアクセス

下位オブジェクトを持つオブジェクトでインデックスによるアクセスが可能なものに対しては、XIndexAccess および XIndexContainer インターフェースを使用します。

XIndexAccess には、個々のオブジェクトへアクセスするためのメソッドが用意されています。 XIndexContainer には、要素を挿入したり削除するためのメソッドが用意されています。

com.sun.star.container.XIndexAccess インターフェース

XIndexAccess を用いて下位オブジェクトへアクセスするには、getByIndex および getCount メソッドを使用します。 このうち getByIndex は、指定したインデックスに該当するオブジェクトを返します。 同様に getCount は、使用可能なオブジェクト数を返します。

Dim Sheets As Object
Dim Sheet As Object
Dim I As Integer

Sheets = Spreadsheet.Sheets

For I = 0 to Sheets.getCount() - 1
   Sheet = Sheets.getByIndex(I)
   ' Editing sheet
Next I

このサンプルコードでは、ループを使用して個々の表 (シート) 要素にアクセスし、各要素をオブジェクト変数 Sheet に取得しています。 getCount は正味の要素数を返すため、インデックスによるアクセスを行う場合、その扱いには注意が必要です。 これは、getByIndex に指定するインデックスは、0 から始まるものとして処理されるためです。 このため、ループカウンタの指定は 0 から getCount()-1 などのように記述する必要があります。

com.sun.star.container.XIndexContainer インターフェース

XIndexContainer インターフェースには、insertByIndex および removeByIndex というメソッドが用意されています。 これらに指定するパラメータは、XNameContainer の該当するメソッドと同様の構成になっています。

下位オブジェクトへの反復アクセス

インスタンスによっては、名前やインデックスではアクセスできない下位オブジェクトを持つオブジェクトが存在します。 このような場合は、XEnumeration および XenumerationAccess インターフェースを使用します。 これらを用いると、直接アドレスを指定することなく、各オブジェクトに存在するすべての下位要素にアクセスできます。

com.sun.star.container.XEnumeration および XenumerationAccess インターフェース

基本オブジェクトには XEnumerationAccess インターフェースが用意されていますが、このインターフェースからは createEnumeration メソッドのみが使用できます。 これを使用して得られる補助オブジェクトには、hasMoreElements と nextElement メソッドを持つ XEnumeration インターフェースが用意されています。 下位オブジェクトのアクセスには、これらのメソッドを使用します。

以下のサンプルコードは、文書ドキュメント上のすべての段落にアクセスします。

Dim ParagraphEnumeration As Object
Dim Paragraph As Object

ParagraphEnumeration = Textdoc.Text.createEnumeration

While ParagraphEnumeration.hasMoreElements()
   Paragraph = ParagraphElements.nextElement()
Wend

上記のサンプルコードでは、最初に ParagraphEnumeration という名前で補助オブジェクトを作成しています。 そしてループに入り、この補助オブジェクトを用いて、文章中の各段落に順次アクセスします。 テキストの末尾に到達すると hasMoreElements メソッドは False 値を返すため、これをループの終了条件に利用します。