2.2 LuaCOM objects

LuaCOM deals with LuaCOM objects, which are no more than a Lua table with the LuaCOM tag and a reference to the LuaCOM C++ object; this one is, in turn, a proxy for the ActiveX object: it holds an IDispatch pointer to the object and translates Lua accesses to ActiveX calls and property accesses. Here is a sample where a LuaCOM object is used:

-- Instantiate a Microsoft(R) Calendar Object
calendar = luacom_CreateObject("MSCAL.Calendar")

-- Error check
if calendar == nil then
  print("Error creating object")
  exit(1)
end

-- Method call
calendar:AboutBox()

-- Property Get
current_day = calendar.Day

-- Property Put
calendar.Month = calendar.Month + 1

print(current_day)
print(calendar.Month)

LuaCOM objects can be created using the LuaCOM Lua API; there are a number of functions that return LuaCOM objects. The most relevant ones are luacom_CreateObject and luacom_GetObject. LuaCOM objects may also be created on demand implicitly, when a return or output value of a COM method is a dispinterface. LuaCOM objects are released through Lua's garbage collection mechanism, so there isn't any explicit API function to destroy them. A LuaCOM object may be passed as an argument to method calls on other LuaCOM objects, if these methods expect an argument of type dispinterface. Here is a sample to illustrate this situation:

-- Gets a running instance of Excel
excel = luacom_GetObject("Excel.Application")

-- Gets the set of worksheets
sheets = excel.Worksheets

-- gets the first two sheets
sheet1 = sheets:Item(1)
sheet2 = sheets:Item(2)

-- Exchange them (here we pass the second sheet as a parameter
-- to a method)
sheet1:Move(nil, sheet2)

There are two kinds of LuaCOM objects: typed and generic ones. The typed ones are those whose COM object has type information. The generic ones are those whose COM object does not supply any type information. This distinction is important in some situations.