class WIN32OLE_TYPE (Ruby 3.3 リファレンスマニュアル)

要約

WIN32OLE_TYPEオブジェクトは、型情報ライブラリ（TypeLib）内に定義された 1つの型情報を保持します。

サンプルコード

require 'win32ole'

excel_app_type = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Application')
puts excel_app_type.progid # => "Excel.Application.14"

Ruby-1.9.1以降、WIN32OLE_TYPELIBオブジェクトの WIN32OLE_TYPELIB#ole_typesメソッドを利用して、型情報ライブラリ内に定義されているすべての型情報をWIN32OLE_TYPEオブジェクトの配列として取得できます。

@see WIN32OLE_TYPELIB

特異メソッド

new(libname, ole_class) -> WIN32OLE_TYPE[permalink][rdoc][edit]

WIN32OLE_TYPEオブジェクトを生成します。

[PARAM] libname:: 生成するTypeLibのレジストリ上のドキュメント文字列（WIN32OLE_TYPELIB#name）または GUID（WIN32OLE_TYPELIB#guid）またはTLBファイル名を文字列で指定します。
[PARAM] ole_class:: 型情報を取り出す型の名前を指定します。
[RETURN]: 指定されたTypeLIbに定義された型の情報を格納したWIN32OLE_TYPEオブジェクトを返します。
[EXCEPTION] WIN32OLERuntimeError:: TypeLibが見つかりません。またはole_classで指定した型が未定義です。

excel_app_type = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Application')
puts excel_app_type.progid # => "Excel.Application.14"

TypeLibに定義されているすべての型を取得するには、 WIN32OLE_TYPELIBオブジェクトのWIN32OLE_TYPELIB#ole_typesメソッドを利用します。

ole_classes(libname) -> [WIN32OLE_TYPE][permalink][rdoc][edit]

TypeLibで定義されているすべての型情報を取得します。

[PARAM] libname:: 生成するTypeLibのレジストリ上のドキュメント文字列（WIN32OLE_TYPELIB#name）または GUID（WIN32OLE_TYPELIB#guid）またはTLBファイル名を文字列で指定します。
[RETURN]: TypeLibに格納されているすべての型をWIN32OLE_TYPEオブジェクトの配列として返します。
[EXCEPTION] WIN32OLERuntimeError:: 引数で指定したTypeLibが見つかりません。

types = WIN32OLE_TYPE.ole_classes('Microsoft Excel 14.0 Object Library')
classes = types.map{|k| k.name} # => ["Adjustments", "CalloutFormat", ...]

Ruby-1.9.1からは、TypeLibに定義されているすべての型を取得するには、 WIN32OLE_TYPELIBオブジェクトのWIN32OLE_TYPELIB#ole_typesメソッドを利用してください。

progids -> [String][permalink][rdoc][edit]

システムに登録されているすべてのコンポーネントクラスのPROGIDを取得します。

[RETURN]: システムに登録されているすべてのコンポーネントクラスのPROGIDを文字列配列で返します。

excel = nil
WIN32OLE_TYPE.progids.each do |pg|
  if pg =~ /excel\.application/i   # ExcelのPROGIDをバージョン無視で取り出す
    excel = WIN32OLE.new(pg)
    break
  end
end
unless excel
  $stderr.puts "Excel isn't installed"
  exit(1)
end
excel.visible = true
# ...
excel.Quit

PROGIDは、生成可能なOLEオートメーションサーバのCoClass（コンポーネントクラス）が持つレジストリ登録名です。WIN32OLE.newの引数に指定して WIN32OLEオブジェクトを生成できます。

typelibs -> [String][permalink][rdoc][edit]

システムに登録されているすべてのTypeLibのドキュメント文字列を取得します。

[RETURN]: システムに登録されているすべてのTypeLibのドキュメント文字列の配列を返します。

Ruby-1.9.1からは、すべてのTypeLibのドキュメント文字列を取得するには、 WIN32OLE_TYPELIBオブジェクトを利用して、以下のように記述してください。

WIN32OLE_TYPELIB.typelibs.map {|t| t.name}

インスタンスメソッド

default_event_sources -> [WIN32OLE_TYPE][permalink][rdoc][edit]

型が持つソースインターフェイスを取得します。

default_event_sourcesメソッドは、selfがCoClass（コンポーネントクラス）の場合、そのクラスがサポートするデフォルトのソースインターフェイス（イベントの通知元となるインターフェイス）を返します。

[RETURN]: デフォルトのソースインターフェイスをWIN32OLE_TYPEの配列として返します。返すのは配列ですが、デフォルトのソースインターフェイスは最大でも1インターフェイスです。ソースインターフェイスを持たない場合は空配列を返します。

tobj = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Worksheet')
tobj.default_event_sources.map {|intf| intf.name} #=> ["DocEvents"]

WIN32OLE_EVENT.newでインターフェイス名を指定しない場合は、ここで返されたインターフェイスが選択されます。

次のサンプルは、IEのnaviaget2メソッドによってどのようなイベントが通知されるかを、実際にメソッド呼び出し（=イベント通知）をトレースして調べるプログラムです。イベントを受け付けるために、 WIN32OLE_EVENT.message_loopの呼び出しが必要な点に注意してください。ここでは最終イベントのStatusTextChangeイベントのメッセージについては既知としています。

# coding : cp932
require 'win32ole'

type = WIN32OLE_TYPE.new('Microsoft Internet Controls', 'InternetExplorer')
ctl = WIN32OLE.new(type.progid)
source = type.default_event_sources[0]
class WebEvent
  def initialize
    @completed = false
  end
  attr_reader :completed
end
source.ole_methods.each do |m|
  WebEvent.module_eval do
    define_method("on#{m.name}") do |*arg|
      if arg[0] == "ページが表示されました"
        @completed = true
      end
      puts "#{Time.now}: #{m.name} was called"
      p arg
    end
  end
end
evt = WIN32OLE_EVENT.new(ctl)
evt.handler = WebEvent.new
ctl.navigate2 'http://www.ruby-lang.org/'
loop do
  break if evt.handler.completed
  WIN32OLE_EVENT.message_loop
end
ctl.Quit

このプログラムを実行するとWindows7のIE8環境では以下のような出力を得られます。

2010-10-06 22:33:54 +0900: PropertyChange was called
["{265b75c1-4158-11d0-90f6-00c04fd497ea}"]
2010-10-06 22:33:54 +0900: BeforeNavigate2 was called
[#<WIN32OLE:0x9d08f0>, "http://www.ruby-lang.org/", 0, "", nil, "", false]
2010-10-06 22:33:54 +0900: DownloadBegin was called
[]
2010-10-06 22:33:54 +0900: PropertyChange was called
["{D0FCA420-D3F5-11CF-B211-00AA004AE837}"]
2010-10-06 22:33:54 +0900: CommandStateChange was called
[2, false]
2010-10-06 22:33:54 +0900: CommandStateChange was called
[1, false]
2010-10-06 22:33:54 +0900: StatusTextChange was called
["www.ruby-lang.org を検索しています"]
2010-10-06 22:33:54 +0900: ProgressChange was called
[100, 10000]
2010-10-06 22:33:54 +0900: StatusTextChange was called
["サイト 221.186.184.68 に接続しています"]
2010-10-06 22:33:54 +0900: StatusTextChange was called
["Web サイトが見つかりました。応答を待っています..."]
……
2010-10-06 22:33:54 +0900: TitleChange was called
["オブジェクト指向スクリプト言語 Ruby"]
2010-10-06 22:33:54 +0900: StatusTextChange was called
["待機中: http://www.ruby-lang.org/ja/ ..."]
2010-10-06 22:33:54 +0900: ProgressChange was called
[10000, 10000]
2010-10-06 22:33:54 +0900: ProgressChange was called
[-1, 10000]
2010-10-06 22:33:54 +0900: DownloadComplete was called
[]
2010-10-06 22:33:54 +0900: ProgressChange was called
[10000, 10000]
2010-10-06 22:33:54 +0900: DocumentComplete was called
[#<WIN32OLE:0x438a2f8>, "http://www.ruby-lang.org/ja/"]
2010-10-06 22:33:54 +0900: StatusTextChange was called
["ページが表示されました"]

[SEE_ALSO] WIN32OLE_TYPE.new, WIN32OLE_TYPE#progid, WIN32OLE_TYPE#ole_methods, WIN32OLE_METHOD#name, WIN32OLE_EVENT.new, WIN32OLE_EVENT#handler=, WIN32OLE_EVENT.message_loop

default_ole_types -> [WIN32OLE_TYPE][permalink][rdoc][edit]

型が持つデフォルトのインターフェイスを取得します。

default_ole_typesメソッドは、selfがCoClass（コンポーネントクラス）の場合、そのクラスが実装しているデフォルトのインターフェイスと、サポートしていればデフォルトのソースインターフェイスを返します。

[RETURN]: デフォルトインターフェイスをWIN32OLE_TYPEの配列として返します。デフォルトインターフェイスは、最大でも、クラス操作用のインターフェイス（OLEオートメーション用）と、イベント用のソースインターフェイスの2要素です。デフォルトインターフェイスを持たない場合は空配列を返します。

tobj = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Worksheet')
tobj.default_ole_types.map {|intf| intf.name} #=> ["_Worksheet", "DocEvents"]

guid -> String | nil[permalink][rdoc][edit]

この型のGUID（グローバル一意識別子）を取得します。

[RETURN]: GUIDを文字列で返します。GUIDを持たない型の場合はnilを返します。

tobj = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Application')
puts tobj.guid  # => {00024500-0000-0000-C000-000000000046}

GUIDは、COMのクラス識別子(CLSID)、インターフェイス識別子(IID)など多数の領域でWindows上のオブジェクトの識別に利用される128ビットの値です。

helpcontext -> Integer | nil[permalink][rdoc][edit]

この型に関連するヘルプファイルのトピックID（ヘルプコンテキスト）を取得します。

[RETURN]: 型に関連するヘルプコンテキストを整数で返します。ヘルプコンテキストが登録されていない場合はnilを返します。

tobj = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Worksheet')
puts tobj.helpcontext # => 131185

helpfile -> String | nil[permalink][rdoc][edit]

オブジェクトに関連付けられたヘルプファイルのフルパス名。

ここで返されたヘルプファイルを表示するには、 WIN32OLE#ole_show_helpメソッドを呼び出します。

オブジェクトがヘルプファイルを持たない場合はnilを返します。

[RETURN]: オブジェクトに関連付けられたヘルプファイルのフルパス名を文字列で返します。ヘルプファイルが未定義の場合はnilを返します。

tobj = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Worksheet')
puts tobj.helpfile # => C:\...\VBAXL9.CHM
WIN32OLE.ole_show_help tobj.helpfile, tobj.helpcontext
# 注）WIN32OLE.ole_show_help(tobj) の呼び出しが望ましい

当メソッドがフルパス名を返しても、ヘルプファイルがインストールされていない場合があることに注意してください。

また、返送値はOLEサーバの登録値をそのまま利用するため、Rubyのパス名形式（ディレクトリ区切りは「/」）ではなく、Windowsのパス名形式（ディレクトリ区切りは「\」）です。

helpstring -> String | nil[permalink][rdoc][edit]

型のドキュメント文字列を取得します。

[RETURN]: ドキュメント文字列を返します。未定義の場合はnilを返します。

tobj = WIN32OLE_TYPE.new('Microsoft Internet Controls', 'IWebBrowser')
p tobj.helpstring   # => "Web Browser interface"

ドキュメント文字列は、コンテキストヘルプなどに利用可能な型の簡単な説明文です。

implemented_ole_types -> [WIN32OLE_TYPE][permalink][rdoc][edit]

この型が実装するインターフェイスを取得します。

implemented_ole_typesメソッドは、selfがCoClass（コンポーネントクラス）の場合、そのクラスが実装しているすべてのインターフェイスを返します。

[RETURN]: クラスが実装するすべてのインターフェイスをWIN32OLE_TYPEの配列として返します。この型がインターフェイスを実装しない場合は、空配列を返します。
[EXCEPTION] WIN32OLERuntimeError:: 型属性が取得できない場合に通知します。

tobj = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Worksheet')
tobj.implemented_ole_types.map {|intf| intf.name} #=> ["_Worksheet", "DocEvents"]

inspect -> String[permalink][rdoc][edit]

selfを説明的な文字列で表現します。

[RETURN]: "#<WIN32OLE_TYPE"とWIN32OLE_TYPE#to_sの結果を「:」で結合し、「>」で閉じた文字列を返します。

x = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Worksheet')
puts x.inspect #=> #<WIN32OLE_TYPE:Worksheet>

[SEE_ALSO] WIN32OLE_TYPE#to_s

major_version -> Integer[permalink][rdoc][edit]

型のメジャーバージョン番号を取得します。

[RETURN]: 型のメジャーバージョン番号を整数で返します。
[EXCEPTION] WIN32OLERuntimeError:: 型属性の読み取りに失敗すると通知します。

tobj = WIN32OLE_TYPE.new('Microsoft Word 14.0 Object Library', 'Documents')
p tobj.major_version   # => 8

minor_version -> Integer[permalink][rdoc][edit]

型のマイナーバージョン番号を取得します。

[RETURN]: 型のマイナーバージョン番号を整数で返します。
[EXCEPTION] WIN32OLERuntimeError:: 型属性の読み取りに失敗すると通知します。

tobj = WIN32OLE_TYPE.new('Microsoft Word 14.0 Object Library', 'Documents')
p tobj.minor_version   # => 5

name -> String[permalink][rdoc][edit]

to_s -> String

selfの型名を取得します。

[RETURN]: selfの型名を文字列で返します。

tobj = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Application')
p tobj.name   # => "Application"

ole_methods -> [WIN32OLE_METHOD][permalink][rdoc][edit]

型が持つメソッドのメタデータを取得します。

[RETURN]: 型が持つメソッドのメタデータをWIN32OLE_METHODの配列として返します。メソッドを持たない場合は空配列を返します。

tobj = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Worksheet')
methods = tobj.ole_methods.map {|m| m.name }
                     # => ['QueryInterface', 'AddRef', 'Release',....]

[SEE_ALSO] WIN32OLE_METHOD

ole_type -> String | nil[permalink][rdoc][edit]

selfの型の種類（TYPEKIND）を取得します。

[RETURN]: selfの型の種類を文字列で返します。情報が取得できない場合はnilを返します。

tobj = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Application')
p tobj.ole_type  # => Class

ole_typeには以下があります。

Enum: 列挙子（0）
Record: ユーザ定義型（メソッドを持たない構造体）（1）
Module: モジュール（静的関数やデータだけを保持）（2）
Interface: COMのインターフェイス（メソッド定義の集合）（3）
Dispatch: OLEオートメーションサーバ（4）
Class: コンポーネントクラス（InterfaceやDispatchの実装）（5）
Alias: 他の型の別名（6）
Union: 共用体（7）
Max: 型の種類を示す列挙体の終端マーカ（8）

MaxはTYPEKINDの終端マーカなので意味を持ちません。

[SEE_ALSO] WIN32OLE_TYPE#typekind

ole_typelib -> WIN32OLE_TYPELIB | nil[permalink][rdoc][edit]

この型を登録してある型情報ライブラリ（TypeLib）を取得します。

[RETURN]: この型を登録しているTypeLibをWIN32OLE_TYPELIBオブジェクトとして返します。見つからない場合はnilを返します。

tobj = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Worksheet')
puts tobj.ole_typelib.name  # => 'Microsoft Excel 14.0 Object Library'

progid -> String | nil[permalink][rdoc][edit]

selfのPROGIDを取得します。

[RETURN]: selfのPROGIDを文字列で返します。selfがPROGIDを持たない、または CoClassでない場合はnilを返します。

tobj = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Application')
p tobj.progid   # => "Excel.Application.14"

この例は、ExcelのApplicationクラスが「Excel.Application.14」という PROGIDを持つことを示します。

[SEE_ALSO] WIN32OLE.new

source_ole_types -> [WIN32OLE_TYPE][permalink][rdoc][edit]

型が持つソースインターフェイスを取得します。

source_ole_typesメソッドは、selfがCoClass（コンポーネントクラス）の場合、そのクラスがサポートするすべてのソースインターフェイス（イベントの通知元となるインターフェイス）を返します。

ActiveXコントロールのようにイベント（WIN32OLE_EVENT）をサポートしているコンポーネントクラスの場合は、このメソッドの呼び出しによりイベントインターフェイスを調べることが可能です。

[RETURN]: ソースインターフェイスをWIN32OLE_TYPEの配列として返します。ソースインターフェイスを持たない場合は空配列を返します。

tobj = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Worksheet')
tobj.source_ole_types.map {|intf| intf.name} #=> ["DocEvents"]

src_type -> String | nil[permalink][rdoc][edit]

selfが他の型の別名ならば、元の型名を取得します。

[RETURN]: selfが別名ならば元の型名を文字列で返します。別名でなければnilを返します。

tobj =  WIN32OLE_TYPE.new('Microsoft Office 14.0 Object Library', 'MsoRGBType')
p tobj.src_type   # => "I4"

この例は、OfficeのMsoRGBType型は符号付き32ビット整数（I4）の別名だということを示します。

typekind -> Integer[permalink][rdoc][edit]

selfの種類を示す値を取得します。

値の意味については、WIN32OLE_TYPE#ole_typeを参照してください。

[RETURN]: 型の種類を示す数値を返します。
[EXCEPTION] WIN32OLERuntimeError:: 型の種類（TYPEKIND）を取得できない場合に通知します。

tobj = WIN32OLE_TYPE.new('Microsoft Word 14.0 Object Library', 'Documents')
p tobj.typekind   # => 4

[SEE_ALSO] WIN32OLE_TYPE#ole_type

variables -> [WIN32OLE_VARIABLE][permalink][rdoc][edit]

型が持つ変数を取得します。

型がEnum（列挙型）やユーザ定義型の場合、メンバ変数の情報を WIN32OLE_VARIABLEオブジェクトの配列として返します。

[RETURN]: 型が持つ変数情報をWIN32OLE_VARIABLEの配列として返します。変数を持たない場合は空配列を返します。
[EXCEPTION] WIN32OLERuntimeError:: 型属性が取得できない場合に通知します。

tobj = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'XlSheetType')
vars = tobj.variables
vars.each do |v|
  puts "#{v.name} = #{v.value}"
end

上記を実行すると以下の出力が得られます。

xlChart = -4109
xlDialogSheet = -4116
xlExcel4IntlMacroSheet = 4
xlExcel4MacroSheet = 3
xlWorksheet = -4167

[SEE_ALSO] WIN32OLE_VARIABLE

visible? -> bool[permalink][rdoc][edit]

この型が公開されているかどうかを照会します。

[RETURN]: 公開されていれば真を返します。

tobj = WIN32OLE_TYPE.new('Microsoft Excel 14.0 Object Library', 'Application')
p tobj.visible?  # => true

要約

サンプルコード

目次

特異メソッド

インスタンスメソッド