Class: COM::Instantiable

Inherits:
Object
  • Object
show all
Defined in:
lib/com/instantiable.rb

Overview

Represents instantiable COM objects. These are COM objects that we can connect to and create.

Class Method Summary collapse

Instance Method Summary collapse

Methods inherited from Object

#observe, #respond_to?, #to_com, #unobserve, #with_properties

Constructor Details

#initialize(options = {}) ⇒ Instantiable

Connects to or creates a new instance of a COM object.

Parameters:

  • options (Hash) (defaults to: {}) —

    a customizable set of options

Options Hash (options):

  • :connect (Boolean) — default: false —

    Whether or not to connect to a running instance (see connect)

  • :constants (Boolean) — default: true —

    Whether or not to load constants associated with the COM object (see constants)



113
114
115
116
117
118
119
 
# File 'lib/com/instantiable.rb', line 113

def initialize(options = {})
  @connected = false
  connect if options.fetch(:connect, self.class.connect?)
  self.com = COM.new(self.class.program_id) unless connected?
  self.class.load_constants(com) if
    options.fetch(:constants, self.class.constants?)
end

Dynamic Method Handling

This class handles dynamic methods through the method_missing method in the class COM::Object

Class Method Details

.connect ⇒ Object

Marks this class as trying to connect to already running instances of COM objects.

Returns:

  • true



30
31
32
 
# File 'lib/com/instantiable.rb', line 30

def connect
  @connect = true
end

.connect? ⇒ Boolean

Queries whether or not this class tries to connect to already running instances of COM objects.

The default is false.

Returns:

  • (Boolean) —

    Whether or not this class tries to connect to already running instances of COM objects

See Also:

  • #connect


43
44
45
 
# File 'lib/com/instantiable.rb', line 43

def connect?
  @connect ||= false
end

.constants(constants) ⇒ Boolean

Sets whether or not this class tries to load constants when connecting to or creating a COM object.

Parameters:

  • constants (Boolean) —

    Whether or not to load constans

Returns:

  • (Boolean) —

    Whether or not to load constants



52
53
54
 
# File 'lib/com/instantiable.rb', line 52

def constants(constants)
  @constants = constants
end

.constants? ⇒ Boolean

Queries whether or not this class tries to load constans when connecting to or creating a COM object.

The default is true.

Returns:

  • (Boolean) —

    Whether or not to load constants



62
63
64
65
 
# File 'lib/com/instantiable.rb', line 62

def constants?
  return true unless defined? @constants
  @constants
end

.constants_loaded? ⇒ Boolean

Queries whether constants have already been loaded for this class.

Returns:

  • (Boolean) —

    Whether or not constants have already been loaded for this class



89
90
91
 
# File 'lib/com/instantiable.rb', line 89

def constants_loaded?
  @constants_loaded ||= false
end

.load_constants(com) ⇒ Boolean

Loads constants associated with COM object com. This is an internal method that shouldn’t be called outside of this class.

Parameters:

  • com (WIN32OLE) —

    COM object to load constants from

Returns:

  • (Boolean) —

    Whether or not any constants where loaded



79
80
81
82
83
84
 
# File 'lib/com/instantiable.rb', line 79

def load_constants(com)
  return if constants_loaded?
  modul = nesting[-2]
  com.load_constants modul, typelib
  @constants_loaded = true
end

.program_id(id = nil) ⇒ String

Gets or sets the COM program ID.

If no program ID has explicitly been set, one based on the name of this class and its containing module. For example, A::B is turned into ‘A.B’.

Parameters:

  • id (String, nil) (defaults to: nil) —

    Program ID to, if given, use

Returns:

  • (String) —

    The set or automatically generated program ID

Raises:

  • (ArgumentError) —

    If no program ID has been set and one can’t be automatically generated



17
18
19
20
21
22
23
24
 
# File 'lib/com/instantiable.rb', line 17

def program_id(id = nil)
  @id = id if id
  return @id if defined? @id
  raise ArgumentError,
    'no automatic COM program ID for class available: %s' % self unless
      matches = /^.*?([^:]+)::([^:]+)$/.match(name)
  @id = '%s.%s' % matches[1..2]
end

.typelib(typelib = nil) ⇒ Object

Typelib to use for loading constants, if it can’t be determined automatically.



69
70
71
72
 
# File 'lib/com/instantiable.rb', line 69

def typelib(typelib = nil)
  @typelib = typelib if typelib
  @typelib ||= nil
end

Instance Method Details

#connected? ⇒ Boolean

Queries whether or not an already running COM object was connected to. This is useful when deciding whether or not to close down the COM object when you’re done with it.

Returns:

  • (Boolean) —

    Whether or not an already running COM object was connected to



126
127
128
 
# File 'lib/com/instantiable.rb', line 126

def connected?
  @connected
end

#inspect ⇒ Object 



130
131
132
 
# File 'lib/com/instantiable.rb', line 130

def inspect
  '#<%s%s>' % [self.class, connected? ? ' connected' : '']
end