IDL Reference を理解する

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

マクロを書くには OpenOffice.org SDK (sdk/docs/common/ref 以下) にも含まれている IDL Reference を理解する必要があります。UNO IDL で定義されたものは OOo の API となっているため API Reference と呼ばれることもあります。

このリファレンスは IDL ファイルから OOo SDK に含まれている autodoc プログラムで自動的に作られます。内容は主に IDL ファイル内の定義および説明などのコメントです。

UNO はコンポーネントの集合体であり類似したコンポーネントはモジュールとしてまとめられています。そのため階層構造を形成しています。

com.sun.star モジュール以下には多数のサブモジュールがあり IDL を参照するときには主にこのモジュールが基点となります。誰かが定義した IDL ではまた別のモジュールにあるかもしれません。com.sun.star が長いので css と略されることがあります。

例えば com.sun.star.awt モジュールを見ると様々な要素があります。

  • Nested Modules サブモジュールです
  • Services プロパティーやインターフェースをまとめたコンポーネントを実装するときに雛形。実際にそのサービスが実装されているとは限りません
  • Interfaces メソッドの集合体。Attribute を定義していることもあります
  • Structs 構造体。特定の系統に関する値を保持するフィールドを複数もちます
  • Enums 列挙型。C++ レベルでは要素ごとに値が振られることがあるが、正しく利用するには言語で提供されている方法に沿ったもので行います
  • Exceptions 例外。特定の例外を送出、判定するときに利用します
  • Constants groups 定数。プロパティやフィールド、メソッドの引数で決まった値を指定するときに利用します。列挙型とは異なり値は個々に決められています。

Nested Modules

awt も star のサブモジュールなわけです。

Service

css.awt.UnoControlRoadmapModel サービスをみてみるといくつか項目がありますがこれらは以下の通りです。

  • Included Services このサービスの内容全てを含みます。このサービスを雛形として実装するコンポーネントではインクルードしているサービスの全てを実装します。
  • Exported Interfaces サービスはこのインターフェースを実装します。インターフェースはインクルードされているサービスによっても実装されていることを忘れてはいけません。インクルードされているサービスも参照してください。
  • Properties このサービスはこれらのプロパティを持ちます。

また、UnoControlRoadmapModel のタイトルの前には unpublished となっておりこれはこの要素が変更される可能性があることを示しています。published なものでは表記は省略されます。

プロパティの Graphic には [Optional] という指定があります。これはこのプロパティをサポートしなくてもよいことを示します。この Optional 指定はプロパティ問わずサービス、インターフェースにも適用されることがあります。

サービスの定義には実際にコンポーネントを作成するときに雛形として利用される以外にプロパティ値を定義するためだけに書かれたものもあります。代表的なものは css.document.MediaDescriptor サービスです。このサービスはコンポーネントとして実装されることはなく、ファイルを開いたりするときに利用される css.frame.XComponentLoader インターフェースの loadComponentFromURL メソッドの引数でオプションを指定するときに値名と型を指定するために定義されています。

Interface

インターフェースはメソッドの集合を定義します。そのインターフェースを実装するコンポーネントはそのインターフェースに含まれるメソッド全てを実装します。
また、インターフェースはほかのインターフェースを継承して拡張できます。実際に全てのインターフェースは css.lang.XInterface から派生しています (もちろん基礎となる XInterface は派生していないので全てではない)。

たとえばファイルを操作するときに利用する css.ucb.XSimpleFileAccess3 インターフェースは XSimpleFileAccess2 を継承しているがそのインターフェースは XSimpleFileAccess から派生しています。

また、全てのインターフェース名は X から始まります。

Method

メソッドの定義は大抵以下のように書かれています。これは css.container.XIndexContainer インターフェースの insertByIndex メソッドです。

void (<- 返り値の型。ない場合には void
insertByIndex( [in] long Index, (<- 引数のモード、型
               [in] any  Element )
raises( ::com::sun::star::lang::IllegalArgumentException, (<- 送出される可能性のある例外
        ::com::sun::star::lang::IndexOutOfBoundsException,
        ::com::sun::star::lang::WrappedTargetException );

最初は返り値の型が書かれています。これは全て UNO の型の1つをとります。

引数がある場合には引数ごとにモード、型、引数名が記載されます。モードには [in]、[out]、[inout] の三種類があります。[in] ではその引数から値が読み込まれることを示し、[out] では与えた引数に対応する値が書き換えられます。[inout] では読み込み、代入の両方が行われます。[out] をサポートしていない言語ではブリッジがほかの方法を用意して [out] 引数から得られる値を取得する方法を提供します。

例外処理が必要な場合には該当する例外に対応した処理を行います。

メソッドの返り値の前に [oneway] と書かれていることがあります。これはそのメソッドを呼び出した場合に処理が非同期的に行われることを示します。この指定のあるメソッドは値を返すことはありません。

ベースインターフェース

Structs

よく利用される構造体に css.beans.PropertyValue があります。Name および Value フィールドを組み合わせてメソッドに多様なオプション引数を渡すときによく利用されます。Hash や dictionary のような形です。

Enum

列挙型の値はある値がいくつかの値のうちの1つである必要があるときにそれを指定するために利用されます。

css.awt.FontSlant では文字の斜体の指定を行う値を定義しています。そのフォントの太さや傾斜具合などの情報を示すときにも利用されますが文字に斜体指定を行うときにも利用されます。

Exception

全ての例外は css.uno.Exception からの派生です。そのためクラスの概念のある言語で例外処理を行う際にまとめて1つの例外トラップにするにはこのベースの例外を指定することができます。

特殊な例外はもう一つあり css.uno.RuntimeException です。この例外は全てのメソッドが送出する可能性があります。この例外はその処理を停止するためのものですが、それが送出されたときにはどこかでトラップしなければ OOo が不意にクラッシュすることになります。

Constants Group

css.awt.FontWeight の定数は文字の太さを定義しています。文字の太さはある程度変更できるため一定の値をとらずある範囲の値になります。ですが一部の値をたとえば BOLD として利用するために定数として定義されています。文字の太さを指定するときにはこれを利用します。もちろんフォントがサポートしていない場合にはその太さになりませんが。

deprecated

deprecated の指定のあるコンポーネントやインターフェース、メソッドは利用しないで下さい。実装はすでになくなっていたり将来なくなる可能性があります。

IDL を定義する

ここでは UNO IDL を理解することを念頭に置いているため IDL を自分で書くことについて詳しく書くことは控えますが、自分で新しく実装済みでないインターフェースや構造体その他を利用したい場合には自分で定義することもできます。