Home > コンピュータ > LibreOffice > マクロ

OpenOffice.org Basicのドキュメント

新規作成日 2017-12-05
最終更新日

Wikiに存在するOpenOffice.org Basicのドキュメントの和訳です

OpenOffice.org Basic

原文「OpenOffice.org Basic

OpenOffice.org Basicは、オフィス・アプリケーションの内からOpenOffice.org APIへのアクセスを提供します。UNOオブジェクトをBasicオブジェクトのように見せることによって、インターフェイスの複雑さを隠して、プロパティの使い方を簡素化します。それは、UNOのために、便利なRuntime Library (RTL)関数と特別なBasicプロパティを提供します。その上さらに、基本的な手順は、簡単に、メニュー、ツールバー・アイコンとGUIイベント・ハンドラのような、GUI要素にフックします。

この章では、OpenOffice.org Basicスクリプト言語を使用して、UNOに、どのようにアクセスするかを説明します。次の項目では、OpenOffice.org Basicは、Basicと呼ばれます。

UNO Objectの操作

原文「Handling UNO Objects

UNOオブジェクトは、それらのインターフェイス・メソッドとプロパティを通して使用されます。Basicは、UNOインターフェイスとプロパティをBasicオブジェクト・メソッドとプロパティにマッピングすることで、これを単純化します。

まず、Basicでは、メソッドを呼び出すとき、オブジェクトがサポートする他のインターフェイスの間で、識別する必要はありません。次に示す図は、3つのインターフェイスをサポートする、UNOサービスの例を示しています。:

Basicの非表示のインターフェイス

Basicの非表示のインターフェイス

JavaとC++では、そのメソッドの1つを呼び出す前に、それぞれのインターフェイスに、参照を取得する必要があります。Basicでは、前もって、適切なインターフェイスを問い合わせることなく、それぞれのサポートされたインターフェイスのすべてのメソッドは、オブジェクトで、直接呼び出すことができます。'.' 演算子は使用されます。:

  ' Basic
  oExample = getExampleObjectFromSomewhere()
  oExample.doNothing()		' Calls method doNothing of XFoo1
					' メソッド、XFoo1のdoNothingを呼び出します
  oExample.doSomething()		' Calls method doSomething of XFoo2
					' メソッド、XFoo2のdoSomethingを呼び出します
  oExample.doSomethingElse(42)	' Calls method doSomethingElse of XFoo2
					' メソッド、XFoo2のdoSomethingElseを呼び出します

さらに、OpenOffice.org Basicは、このパターンに準拠する場合、Basicオブジェクト・プロパティとして、UNOオブジェクトのgetとsetメソッドの対を解釈します。:

このパターンでは、OpenOffice.org Basicは、SomePropertyという名前のSomeType型のプロパティを提供します。この機能は、com.sun.star.beans.Introspectionサービスに基づいています。詳細については、UNOリフレクションAPIを参照してください。

getとsetメソッドは、常に、直接、使用することができます。上のメソッドgetIt()とsetIt()やBasicプロパティを読み込みと書き込みの例のサービスで、それは、使用されます。:

  Dim x as Integer
  x = oExample.getIt() ' Calls getIt method of XFoo3
				' XFoo3のgetItメソッドを呼び出します
 
  ' is the same as
  '以下と同じです
 
  x = oExample.It ' Read property It represented by XFoo3
			' それが、XFoo3によって表すプロパティを読み込みます
 
  oExample.setIt( x ) ' Calls setIt method of XFoo3
				' XFoo3のsetItメソッドを呼び出します
 
  ' is the same as
  '以下と同じです
 
  oExample.It = x ' Modify property It represented by XFoo3
			' それが、XFoo3によって表すプロパティを修正します。

getメソッドだけがあり関連するsetメソッドがない場合、プロパティは、読み取り専用と考えられます。

  Dim x as Integer, y as Integer
  x = oExample.getMore() ' Calls getMore method of XFoo1
				'XFoo1のgetMoreメソッドを呼び出します
  y = oExample.getLess() ' Calls getLess method of XFoo1
				'XFoo1のgetLessメソッドを呼び出します
 
  ' is the same as
 '以下と同じです
 
  x = oExample.More ' Read property More represented by XFoo1
			  'XFoo1によってMoreが表現するプロパティが読み込まれます
  y = oExample.Less ' Read property Less represented by XFoo1
			'XFoo1によってLessが表現するプロパティが読み込まれます
 
  ' but
  '
 
  oExample.More = x ' Runtime error "Property is read only"
			  '実行時エラー "プロパティは読み取り専用です"
  oExample.Less = y ' Runtime error "Property is read only"
			'実行時エラー "プロパティは読み取り専用です"

com.sun.star.beans.XPropertySetを通してオブジェクトが提供するプロパティは、. 演算子を通して利用できます。 また、com.sun.star.beans.XPropertySetのメソッドが、使用することができます。 次の例のオブジェクトoExample2は、3つの整数プロパティ、Value1、Value2とValue3を持っています。:

  Dim x as Integer, y as Integer, z as Integer
  x = oExample2.Value1
  y = oExample2.Value2
  z = oExample2.Value3
 
  ' is the same as
  ' 以下と同じです
 
  x = oExample2.getPropertyValue( "Value1" )
  y = oExample2.getPropertyValue( "Value2" )
  z = oExample2.getPropertyValue( "Value3" )
 
  ' and
 
  oExample2.Value1 = x
  oExample2.Value2 = y
  oExample2.Value3 = z
 
  ' is the same as
  ' 以下と同じです
 
  oExample2.setPropertyValue( "Value1", x )
  oExample2.setPropertyValue( "Value2", y )
  oExample2.setPropertyValue( "Value3", z )

Basicは、. 演算子を通じてコレクションの要素の名前の提供するために、com.sun.star.container.XNameAccessを使用します。 しかしながら、XNameAccessは、読み込みアクセスだけを提供しています。コレクションが、com.sun.star.container.XNameReplacecom.sun.star.container.XNameContainerを通じて、書き込みアクセスを提供する場合、 明確に、適切なメソッドを使用します。:

  ' oNameAccessible is an object that supports XNameAccess
  ' including the names "Value1", "Value2"
  ' oNameAccessibleは、"Value1"、"Value2"の名前が含まれているXNameAccessをサポートするオブジェクトです。

  x = oNameAccessible.Value1
  y = oNameAccessible.Value2
 
  ' is the same as
  ' 以下と同じです
 
  x = oNameAccessible.getByName( "Value1" )
  y = oNameAccessible.getByName( "Value2" )
 
  ' but
 
  oNameAccessible.Value1 = x' Runtime Error, Value1 cannot be changed
				   ' ランタイム・エラー、 Value1は変更できません。
  oNameAccessible.Value2 = y' Runtime Error, Value2 cannot be changed
				   ' ランタイム・エラー、 Value2は変更できません。
 
  ' oNameReplace is an object that supports XNameReplace
  ' replaceByName() sets the element Value1 to 42
  ' oNameReplaceは、XNameReplaceをサポートするオブジェクトです。
  ' replaceByName()は、要素のValue1を42に設定します。
  oNameReplace.replaceByName( "Value1", 42 )

UNOサービスをインスタンス化する

原文「Instantiating UNO Services

Basicでは、Basic Runtime Library (RTL)関数のcreateUnoService()を使用して、サービスをインスタンス化します。この関数は、完全修飾サービス名を期待し、そして、それが、利用可能である場合、このサービスをサポートしているオブジェクトを返します。:

oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )

この呼び出しは、com.sun.star.ucb.SimpleFileAccessサービスをインスタンス化します。 関数が正常に実行されたことを確認するために、返されたオブジェクトは、IsNull関数で確認することができます。:

  oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
  bError = IsNull( oSimpleFileAccess )' bError is set to False
						  ' bErrorは、Falseに設定されます。
 
  oNoService = CreateUnoService( "com.sun.star.nowhere.ThisServiceDoesNotExist" )
  bError = IsNull( oNoService )' bError is set to True
 					' bErrorは、Trueに設定されます。

CreateUnoService()を使用して、サービスをインスタンス化する代わりに、また、それは、GetProcessServiceManager()を呼び出すことによって、OpenOffice.org処理のグローバルなUNO com.sun.star.lang.ServiceManagerを取得できます。一度、取得すると、直接、createInstance()を使用します。

  oServiceMgr = GetProcessServiceManager()
  oSimpleFileAccess = oServiceMgr.createInstance( "com.sun.star.ucb.SimpleFileAccess" )
 
  ' is the same as
 
  oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )

GetProcessServiceManager()の利点は、サービスが、サービス・マネージャーを使用して、インスタンス化されるとき、その追加の情報と、受け取った引数に渡すことです。例えば、引数でサービスを初期化するために、 com.sun.star.lang.XMultiServiceFactoryのcreateInstanceWithArguments()メソッドは、サービス・マネージャーで使用する必要があります。なぜなら、適切なBasic RTL関数が、ありません。

例:

  Dim args(1)
  args(0) = "Important information"
  args(1) = "Even more important information"
  oService = oServiceMgr.createInstanceWithArguments _
      ( "com.sun.star.nowhere.ServiceThatNeedsInitialization", args() )

GetProcessServiceManager()で返されるオブジェクトは、com.sun.star.lang.ServiceManagerをサポートする通常のBasic UNOオブジェクトです。そのプロパティとメソッドは、先程説明したようにアクセスされます。

新しいスタイルのサービス・コンストラクタを使用する

Using new-style service constructors

OpenOffice.org 3.2から始まるOpenOffice.org Basicでは、UNOの新しいスタイルのサービスコンストラクタをサポートしています。詳細については、Servicesのセクションを確認して下さい。上で使用されるサンプル・サービスのため、コンストラクタは、このように定義することができました。:

  module com { module sun { module star { module nowhere {
 
  service ServiceThatNeedsInitialization: XFoo { 
      create1([in] long arg);
      create2([in] string important1, [in] string important2);
  };
 
  }; }; }; };

UNOサービスは、OpenOffice.org Basicオブジェクトにマッピングされています。それらは、完全なUNO名前空間パスを使用して、対処する必要があります。コンストラクタは、これらのサービス・オブジェクトのメソッドとして、呼び出すことができます。:

  Dim oServiceObj
  oServiceObj = com.sun.star.nowhere.ServiceThatNeedsInitialization
  Dim oInstance As Object
  oInstance = oServiceObj.create2( "Useless", "Invalid" )

もちろん!サービス・オブジェクトは、予め、変数に格納する必要ありません。また、インスタンスは、1つのステートメントだけで実行します。:

  Dim oInstance As Object
  oInstance = com.sun.star.nowhere.ServiceThatNeedsInitialization.create1( 42 )

内部的に、UNOの既定のコンテキストは、作成するために使用され、サービスに渡されます。また、それは、最初の引数として追加する代わりに、独自のコンテキストを使用することもできます。:

  Dim oMyContext As Object
  oMyContext = GetContextFromSomewhere()
  oInstance = oServiceObj.create1( oMyContext, 42 )

新しいスタイルのサービスだけが、暗黙のコンストラクタを持っている場合、それは、OpenOffice.org Basicで、パラメータなしで、メソッド"create"にマッピングされました。

プロパティのビルド

Build in properties

Basic RTLは、APIエントリ・ポイントとして特別なプロパティを提供します。それらは、OpenOffice.org Basicの機能で、更に詳細に説明されています。:

OpenOffice.org Basic RTLプロパティ 解説
ThisComponent Writer、Calc、DrawやImpressドキュメントに埋め込まれているBasicコードの中に存在するだけです。それには、Basicコードが、埋め込まれているドキュメント・モデルが含まれています。
ThisDatabaseDocument 元にした文書に埋め込まれるBasicコードの中に存在するだけです。それには、Basicコードが埋め込まれているドキュメントのモデル(すなわちBase文書)が含まれています。マクロが、Baseドキュメントに含まれるFormドキュメントからイベントによって開始されるとき、役に立ちます。
StarDesktop オフィス・アプリケーションのcom.sun.star.frame.Desktopシングルトン。それは、ドキュメント・コンポーネントを読み込み、ドキュメント・ウィンドウを処理します。例えば、一番上のウインドウのドキュメントは、oDoc = StarDesktop.CurrentComponentを使用して取得することができます。

ThisComponentは、StarDesktop.CurrentComponentより推奨されます。IDEからの開発とデバッグに便利なため、BasicIDEがアクティブである場合、ThisComponentが、常にコンポーネントを参照するしている間、StarDesktop.CurrentComponentは、BasicIDEそのものを参照します。それは、BasicIDEが、一番上のウインドウになる前に、アクティブでした。

UNOオブジェクトに関する情報を取得する

原文「Getting Information about UNO Objects

Basic RTLは、UNOオブジェクトに関する情報を取得します。実行時に、オブジェクトを評価する関数があります。 そして、オブジェクト・プロパティは、デバッギングの間、オブジェクトを調べるために使用されます。

実行時に、インターフェイスを確認する

原文「Checking for interfaces during runtime」

けれども、Basicでは、C ++やJavaのような、queryInterfaceの概念はサポートされていません。知っていることが、役に立つことがあります。特定のインターフェイスが、UNO Basicオブジェクトでサポートされている、あるいは、されていない場合、 関数HasUnoInterfaces()は、これを検出します。

HasUnoInterfaces()が期待する最初のパラメータは、テストする必要があるオブジェクトです。1つ以上の完全修飾されたインターフェイス名のパラメータは、次に関数に渡すことができます。これらすべてのインタフェースが、オブジェクトによってサポートされている場合、関数は、True、それ以外の場合、falseを返します。

  Sub Main
    Dim oSimpleFileAccess
    oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
 
  Dim bSuccess
      Dim IfaceName1$, IfaceName2$, IfaceName3$
      IfaceName1$ = "com.sun.star.uno.XInterface"
      IfaceName2$ = "com.sun.star.ucb.XSimpleFileAccess2"
      IfaceName3$ = "com.sun.star.container.XPropertySet"
 
      bSuccess = HasUnoInterfaces( oSimpleFileAccess, IfaceName1$ )
      MsgBox bSuccess ' Displays True because XInterface is supported
			  ' XInterfaceがサポートされているため、Trueを表示します
 
      bSuccess = HasUnoInterfaces( oSimpleFileAccess, IfaceName1$, IfaceName2$ )
      MsgBox bSuccess ' Displays True because XInterface
      ' and XSimpleFileAccess2 are supported
			  ' XInterfaceとXSimpleFileAccess2がサポートされるため、Trueを表示します
 
      bSuccess = HasUnoInterfaces( oSimpleFileAccess, IfaceName3$ )
      MsgBox bSuccess ' Displays False because XPropertySet is NOT supported
			  ' XPropertySetがサポートされないため、Falseを表示します
 
      bSuccess = HasUnoInterfaces( oSimpleFileAccess, IfaceName1$, IfaceName2$, IfaceName3$ )
      MsgBox bSuccess ' Displays False because XPropertySet is NOT supported
			  ' XPropertySetがサポートされないため、Falseを表示します
  End Sub

実行時に、オブジェクトが構造体であるかどうかを調べる

Testing if an object is a struct during runtime

先程、構造体のマッピングのセクションで説明したように、構造体は、値として扱われるため、オブジェクトと異なる方法で処理されます。 それを確認するためにIsUnoStruct()関数を使用して、UNO Basicオブジェクトは、オブジェクトや構造体を表します。この関数は1つのパラメータを必要とし、Trueを返します。このパラメータが、UNO構造体である場合、それ以外の場合は、Falseです。

例:

  Sub Main
      Dim bIsStruct
          ' Instantiate a service
      Dim oSimpleFileAccess
      oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
      bIsStruct = IsUnoStruct( oSimpleFileAccess )
      MsgBox bIsStruct ' Displays False because oSimpleFileAccess is NO struct
                       ' Instantiate a Property struct
                       ' oSimpleFileAccessが、構造体でないため、Falseを表示します
                       ' プロパティ構造体をインスタンス化します
      Dim aProperty As New com.sun.star.beans.Property
      bIsStruct = IsUnoStruct( aProperty )
      MsgBox bIsStruct ' Displays True because aProperty is a struct
                       		  ' aPropertyが構造体であるため、Trueを表示します
      bIsStruct = IsUnoStruct( 42 )
      MsgBox bIsStruct ' Displays False because 42 is NO struct
                       		  ' 42が、構造体でないため、Falseを表示します
  End Sub

実行中を識別するためのテスト・オブジェクト

Testing objects for identity during runtime

見つけるために、2つのUNO OpenOffice.org Basicオブジェクトが、同じUNOオブジェクト・インスタンスを参照する場合、 関数EqualUnoObjects()を使用します。Basicは、比較演算子=を、型オブジェクトの引数に適用することができません。例えば、Obj1 = Obj2である場合、その次に、実行時エラーを引き起こします。

  Sub Main
      Dim bIdentical
      Dim oSimpleFileAccess, oSimpleFileAccess2, oSimpleFileAccess3
          ' Instantiate a service
          ' サービスのインスタンス化
      oSimpleFileAccess = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
      oSimpleFileAccess2 = oSimpleFileAccess ' Copy the object reference
          ' オブジェクト参照をコピーします
      bIdentical = EqualUnoObjects( oSimpleFileAccess, oSimpleFileAccess2 )
      MsgBox bIdentical ' Displays True because the objects are identical
          ' Instantiate the service a second time
          ' オブジェクトが同一のため、Trueを示します
          ' 二度目は、サービスをインスタンス化します
      oSimpleFileAccess3 = CreateUnoService( "com.sun.star.ucb.SimpleFileAccess" )
      bIdentical = EqualUnoObjects( oSimpleFileAccess, oSimpleFileAccess3 )
      MsgBox bIdentical ' Displays False, oSimpleFileAccess3 is another instance
  		         ' Falseを表示し、oSimpleFileAccess3は、他に、インスタンスとしての機能も持っています。
      bIdentical = EqualUnoObjects( oSimpleFileAccess, 42 )
      MsgBox bIdentical ' Displays False, 42 is not even an object
          ' Instantiate a Property struct
          ' Falseを表示し、42は、オブジェクトではありません。プロパティ構造体をインスタンス化します
      Dim aProperty As New com.sun.star.beans.Property
      Dim aProperty2
      aProperty2 = aProperty ' Copy the struct
   			           ' 構造体をコピーします
      bIdentical = EqualUnoObjects( aProperty, aProperty2 )
      MsgBox bIdentical ' Displays False because structs are values
          ' and so aProperty2 is a copy of aProperty
          ' 構造体が値であるため、Falseを表示します。そして、このように、aProperty2は、aPropertyのコピーです
          ' 
  End Sub

OpenOffice.org Basicオブジェクトの背後にある基本的な隠蔽されたインターフェイスは、開発者がAPI構造を使用するとき、問題を引き起こします。API参照を理解することは難しい場合があります。そして、オブジェクトにアクセスし、特定の目標に到達する正しい方法を見つけます。

開発とデバッグの間、支援するために、OpenOffice.org BasicのすべてのUNOオブジェクトは、特別なプロパティを持っています。それは、オブジェクト構造についての情報を提供します。これらのプロパティは、開発とデバッギングが意図してそれらが使用されていることを強調するために、すべて、Dbg_が前に置かれます。これらのプロパティ型は、Stringです。プロパティを表示するために、MsgBox関数を使用します。

デバッグ中のインターフェイスの検査する

Inspecting interfaces during debugging

Dbg_SupportedInterfacesは、オブジェクトによってサポートされているすべてのインターフェイスの一覧を表示します。 次の例では、オブジェクトは、前のセクションで、オブジェクトの例として説明した関数GetProcessServiceManager()で、返されます。

  oServiceManager = GetProcessServiceManager()
  MsgBox oServiceManager.Dbg_SupportedInterfaces

これは、メッセージボックスの表示するために呼び出されます。:

Dbg_SupportedInterfacesプロパティ

Dbg_SupportedInterfacesプロパティ

リストには、オブジェクトによってサポートされる、すべてのインターフェイスが含まれています。インターフェイスのために、他のインターフェイスから派生しています。優れたインターフェイスは、com.sun.star.container.XSetのために、上で示されるように、インデントされています。それは、com.sun.star.container.XElementAccessに基づいて、com.sun.star.container.XEnumerationAccessから派生しています。

インタフェース名の後ろに "(ERROR:Not really supported!)"と表示されている場合、オブジェクトの実装には、通常、バグがあります。なぜなら、オブジェクトは、このインターフェイスをサポートするふりをしています。 (com.sun.star.lang.XTypeProviderごとに、しかし、その失敗のための問合わせは、機能しません。詳細については、UNOリフレクションAPIを参照してください)。

デバッギングの間、プロパティを検査する

Inspecting properties during debugging

Dbg_Propertiesは、com.sun.star.beans.XPropertySetを通して、そして、Basicオブジェクト・プロパティにマッピングされることができるgetとsetメソッドを通して、オブジェクトによって、サポートされる、すべてのプロパティの一覧を表示します。:

  oServiceManager = GetProcessServiceManager()
  MsgBox oServiceManager.Dbg_Properties

このコードは、次の例のようなメッセージボックスを作成します。:

Dbg_Properties

Dbg_Properties

デバッギングの間、メソッドを検査する

Inspecting Methods During Debugging

Dbg_Methodsは、オブジェクトによってサポートされるすべてのメソッドの一覧を表示します。

例:

  oServiceManager = GetProcessServiceManager()
  MsgBox oServiceManager.Dbg_Methods

このコードは、以下を表示します:

Dbg_Methods

Dbg_Methods

Dbg_PropertiesとDbg_Methodsで使用される表記は、Basicでは、内部の実装型名前を参照します。Sbx接頭辞は、無視されることができます。残りの名前は、通常のBasic型表記に対応しています。SbxEMPTYは、Variantと同じ型です。 Basic型に関する詳細については、次のChapterで利用できます。

Basicは、検出するために、com.sun.star.lang.XTypeProviderインターフェイスを使用しています。それは、オブジェクトをサポートするインタフェースです。

その結果、このインタフェースをサポートすることが重要です。Basicからアクセスできる必要があるコンポーネントを実装するとき、詳細については、UNOコンポーネントを記述するを確認して下さい。

インスペクタ・ツール

Inspector tools

これらのDbg_プロパティを使用することは、APIオブジェクトの内容を発見する極めて粗雑な方法です。代わりにXrayツールMRIツールを使用します。

要素のリストは、MsgBoxで表示するには、不便なほど長くなることがあります。コードは、すべてのDbg_要素を、新しいWriter文書に記述するために、利用できます。OpenOffice.org Macros > Tools > Debug > WritedbgInfoを確認して下さい。 Toolsライブラリが、このルーチンを使用するために、読み込む必要があります。:

GlobalScope.BasicLibraries.LoadLibrary( "Tools" )
Call Tools.WritedbgInfo(MyObject)
このエントリーをはてなブックマークに追加