 |
Using the oiObject class To access the Office Object Model for Word, Excel, Outlook and Powerpoint |
| Contents | |||
 |
Introduction | ||
| Using the oiObject Class (recommended reading) | |||
| Converting a Macro from VBA to Clarion using OfficeInside (recommended reading) | |||
| Passing Parameters (oiParams) | |||
|
Class Reference
Equates |
||
| |
HowTos and Examples |
||
|
FAQ | ||
OfficeInside 3 introduced some exciting new functionality in the form of a "generic" class that can represent any object in the Office Object Model. This allows the entirety of Office to be accessed.
The root of each of the Office classes is the Application, which represents Word, Outlook, Excel or Powerpoint. Each of the OfficeInside classes (oiWord, oiExcel, oiOutlook and oiPowerpoint) have an iApplication member that represents this object, and allows you to interact with the Office applications.
Using the oiObject Class (recommended reading)
Let's start with an example of accessing the Page Setup properties of a Worksheet in Excel:
ExcelBook oiExcel ! Instance of the oiExcel class
iSheet oiObject
ipageSetup oiObject
code
ExcelBook.Init()
ExcelBook.iApplication.GetChild('ActiveSheet', iSheet) ! Get the active sheet from oiExcel
iSheet.GetChild('PageSetup', iPageSetup) ! Get the PageSetup for the sheet
centerFooter = 'My Worksheet' ! A string for the center footer contents
iPageSetup.Set('CenterFooter', centerFooter) ! Set the center footer to our string
This simple example demostrates the fundamentals of the new oiObject class. Starting with the iApplication that the OfficeInside classes provide, the GetChild method allows any of the child objects to be retrieved. These represent the elements available in each of the Office applications. For example, in Excel: Workbook, Worksheet, Cells, Rows etc. are all objects that can be retrieved. In Outlook items such as Mail, Appointments, Folders and the like are all objects that can be retrieved and interacted with. ce an object has been retrieved, the Get(), Set() and CallMethod() methods can be called.
In the example above the Set() method is used to set a property called 'CenterFooter' to the passed value (the centerFooter string).
Now for a slightly more complex example, using Outlook and accessing the Appointment item, getting and setting it's properties, anding an attendee to an appointment.
Outlook oiOutlook
Namespace oiObject
Appointment oiObject
Recipients oiObject
Attendee oiObject
ItemID string(_oit:EntryIDSize) ! Standard Entry ID
attendeeList string(1024) ! Semi colon seperated list of attendees
code
ident = 'MAPI'
if Outlook.iApplication.GetChild('GetNamespace', Namespace, ident)
! Get the specific appointment object
if Namespace.GetChild('GetItemFromID', Appointment, ItemID)
Appointment.Set('BusyStatus', oio:Busy) ! Example of setting a property
! Get the Recipients object that is a child of the Appointment
if Appointment.GetChild('Recipients', Recipients)
! The recipients object is now fully accessible, so for example,
! Add a recipient and get the returned object so that it can be modified.
if Recipients.GetChild('Add', Attendee, attendeeName) ! Add to the recpients
Message('Attendee Added.')
Attendee.Set('Type', oio:Required)
else
Message('Failed to add an Attendee.')
end
! Other methods available for the Recpients object include:
! Add(), Item(), Remove() and RemoveAll()
Appointment.Call('Save')
! Refresh the list of attendees (C55 users should call GetProp instead of Get).
Appointment.Get('RequiredAttendees', attendeeList)
Message('Attendees: ' & Clip(attendeeList))
end
else
Message('Could not get the requested appointment, the ID may be invalid.')
end
end
! The objects can be cleaned up directly after use by calling the Kill method:
Namespace.Kill()
Appointment.Kill()
Recipients.Kill()
Attendee.Kill()
(This will be done automatically when the objects go out of scope, but for procedures that remain open for long periods of time, this can be more efficient.)
The new "Generics" example demonstrates this and more. The oiObject class opens up a whole host of new possibilities, by freeing you from the limitation of what is built into the base OfficeInside classes. The oiObject class implements the bulk of the functionality in four classes: msWord, msExcel, msOutlook and msPowerpoint. These classes are in the msOffice.inc and msOffice.clw files in the Generics example folder. They serve as a good basis for becoming familiar with the Office Object Model, as well as a good place to start with your own classes that expand on the built in classes. The Generics example also contains a variety of additional useful functionality.
A good starting place for what is available is the Office Developer Reference.
For each of the applications (Word, Excel, Outlook and Powerpoint), see the Object Model section under Develop Refererence.
For example, for MS Word, see the Word Object Model Reference.
Converting VBA (Macros) to Clarion
Because of the shear size of the Office Object Model it is often difficult to determine exactly which objects are needed for a particular task. One of the simplest approachs is to record a macro within the Office application itself.
For example in Word we could record a Macro for adding text and an image to a document. Editing this Macro then displays the VBA code:
Sub quicktest()
'
' quicktest Macro
'
'
Selection.TypeText Text:="Hello World"
Selection.TypeParagraph
Selection.InlineShapes.AddPicture FileName:= _
"C:\Users\Sean\Pictures\bitshift_avatar_exp.png", LinkToFile:=False, _
SaveWithDocument:=True
End SubIn this case the object being used is the Selection object. The first task is the get the Selection object from the Document (this isn't done in the macro above as it is automatically provided).
All objects are a child of the Application object, and each of the OfficeInside classes has an iApplication property which represents this object. The GetChild method is used to get each child object. We will start by getting the Application.ActiveDocument object and then getting the Selection from the document:
Word.iApplication.GetChild('ActiveDocument', Document)
Document.GetChild('Selection', Selection)
In the code snippet above Word is an oiWord object and both Document and Selection are oiObject objects. Once the required object has been retrieved from the parents the methods and properties can be accessed. In the example below we have extended the msWord class (which derives from oiWord - see the Generic example):
msWord.QuickTest procedure ()
Document oiObject
Selection oiObject
InlineShapes oiObject
code
if self.iApplication.GetChild('ActiveDocument', Document)
if Document.GetChild('Selection', Selection)
Selection.params.AddString('Hello World')
Selection.CallEx('TypeText')
Selection.params.Free()
Select.Call('TypeParagraph')
if Select.GetChild('InlineShapes', InlineShapes)
InlineShapes.params.AddString('C:\Users\Sean\Pictures\bitshift_avatar_exp.png')
InlineShapes.params.AddBool(false)
InlineShapes.params.AddBool(true)
inlineShapes.CallEx('AddPicture')
end
end
end
First the Selection.TypeText method is called. Before a method is called
all the parameters required are set, in this case by calling
Selection.params.AddString(). The .params property of the oiObject class
provides parameter handling and type conversion, and allows any number of
parameters to be passed. When the parameter values are stored in variables
of the correct type the Insert method is the primary method that is used
to add parameters:
SomeFunction Function (long longVal, string stringVal, real realVal)
Selection oiObject
code
Selection.params.Insert(longVal)
Selection.params.Insert(stringVal)
Selection.params.Insert(realVal)
In addition to params.Insert() a number of methods are provided for explicity type conversion, passing literal values and for inserting "Null" values for optional parameters: AddString, AddBString, AddInt, AddBool, AddNull.
Once the parameters have been set the CallEx method is used to call the method and pass the parameters. The params.Free method is used to clear the parameters so that the next set of parameters can be added for another method call.
The oiObject class provides two forms of parameter passing. The first is for simple calls which don't take any parameters, or pass a single integer (long), string or oiObject as a parameter. This uses the simple Call method:
MyItem.Call('SomeMethod') ! No parameter
MyItem.Call('SomeMethod', stringVal) ! A single parameterFor more complex calls the oiObject.CallEx() method allows any number of parameters of any types to be passed. It also supports optional parameters, which can be passes as "Null". The oiObject.params property allows these parameters to be specified. This property is an instance of the oiParams class and provides methods for setting the parameters to pass.
When the parameter values are stored in variables of the correct type the Insert method is the primary method that is used to add parameters:
SomeFunction Function (long longVal, string stringVal, real realVal)
Selection oiObject
code
Selection.params.Insert(longVal)
Selection.params.Insert(stringVal)
Selection.params.Insert(realVal)
In addition to params.Insert() a number of methods are provided for explicity type conversion, passing literal values and for inserting "Null" values for optional parameters:
AddString Procedure (string sVal, long pType = 0)
Adds the passed string as a parameter. Allows the COM parameter type to be specified by setting pType to one of the following values:
oiParam:String equate(0) ! string
oiParam:Long equate(1) ! integer (Clarion long)
oiParam:Bool equate(2) ! boolean (Clarion bool)
oiParam:Real equate(3) ! float (Clarion real)
oiParam:Short equate(4) ! Short
oiParam:Const equate(5) ! A Constant (equate).
AddBString Procedure (string bs)
AddInt Procedure (long pVal, bool isBool=false)
AddBool Procedure (long pVal)
AddNull Procedure ()
Class Methods
Methods provided by the oiObject class, along with examples demonstrating the typical use of each method.
The class constructor, called when the object enters scope.
Parameters
None
Return Value
None
Notes
This method should not be called directly. Use the Init or GetChild method to get a specific object.
See Also
The class destructor, handles cleanup when the object is no longer in scope. The Kill method can be used to deallocated memory before the object goes to of scope. Objects can be resused by calling Kill before reusing them.
Parameters
None
Return Value
None
Notes
This method should not be called directly. Use the Kill method to cause the object to clean up and deallocate memory.
See Also
The ErrorTrap method is called when an error occurs. Additional information is passed to the ErrorTrap method, and it provides centralised error handling. In addition the method sends debug and error information to the system debug output if the .debug property of the class is set to True (1) and if the application was run using one of the OfficeInside debug command line switches such as /oidebugmax.
Parameters
None
Return Value
None
Notes
This method is a callback method and is not typically called directly (member of the object will call this method to trap errors).
See Also
Init procedure (string pName, *oiObject iParent, <long itemNumber>), long, proc
Initialises the object and associates it with the Outlook Object Model object based on the name specified and the parent object passed. Each of the core OfficeInside objects has an iApplication property, which represents the Office application associated with that object. This is typically used as the parent object for retrieving other objects in the Office Object Model heirarchy.
As an alternative to the Init method, the GetChild method is provided. Functionaly the two methods are identical, however GetChild provides alternative syntax that can improve code legibility. The GetChild method also provide additional functionality, allowing string and long parameters. We recommend using GetChild rather than Init in most cases.
Parameters
string pName
The name of object to retrieve from the parent.
*oiObject iParent,
The parent object to get the child from.
<long itemNumber>
A optional long that identifies which item should be retrieved. This is typically used when retrieving an item from a collect of multiple objects (for instance when getting a specific document from a collection of documents).
Return Value
Returns True (1) for success and False (0) for failure. In the event of an error occuring the ErrorTrap method will be called with additional information.
Examples
Appointment oiObject
Recipients oiObject
code
Recipients.Init('Recipients', Appointment)
! Alternative using GetChild to initialise the object:
Appointment.GetChild('Recipients', Recipients) See Also
Kill Procedure ()
Cleans up the object and deallocates any memory. This is called automatically by the destructor when the object is no longer in scope. The Kill method can be called to clean up before the object is out of scope. It can also be used to clean up before call the Init or GetChild method to reuse the oiObject object (see the example below).
Parameters
None
Return Value
Returns True (1) for success and False (0) for failure. In the event of an error occuring the ErrorTrap method will be called with additional information.
Examples
oItem oiObject
code
Namespace.GetChild('GetItemFromID', oItem, ItemID) ! Get a item from Outlook
! Note: The ItemID passed is an Outlook ID that uniquely identifies and item
! previously added or retrieved.
oItem.Call('Save') ! Call the Save method
Appointment.Set('BusyStatus', oio:Busy) ! Example of setting a property
oItem.Kill() ! Clean up
! The object can now be reused as needed
ExcelBook.iApplication.GetChild('ActiveSheet', oItem) ! Get the active sheet from oiExcel
oItem.Call('Delete') ! Delete the sheet
oItem.Kill() ! Clean upSee Also
GetChild procedure (string cName, *oiObject child, <*long itemNumber>), long, proc
GetChild procedure (string cName, *oiObject child, *string identifier), long, proc
Retrieves a child object based on the name specified. The Office Object model is heirachical, with the Application object at the root. This allows a child object to be retrieved from the parent. Once an object is retrieved the methods and properties can be accessed, along with any child objects that the new object provides. For example the Documents object is a child of the Word Application object. The Documents object contains a number of Document children, and each Document contains child object that represent text , tables, selections and the like.
Parameters
string cName
The name of the child object to retrieved.
*oiObject child,
The object to store the child in.
<*long itemNumber>
An optional parameter that specifies the position of the child object in a collection of objects.
*string identifier
An optional parameter that specifies the identifier of the child object in a collection of objects.
Return Value
Returns True (1) for success and False (0) for failure. In the event of an error occuring the ErrorTrap method will be called with additional information.
Examples
Outlook oiOutlook
Namespace oiObject
Appointment oiObject
Recipients oiObject
code
oiOutlook.Init() ! Initialise the Outlook Object
ident = 'MAPI' ! Get the NameSpace Child
Outlook.iApplication.GetChild('GetNamespace', Namespace, ident)
! Get the specific Appointment child object
Namespace.GetChild('GetItemFromID', Appointment, ItemID)
! Get the Recipients object that is a child of the Appointment
Appointment.GetChild('Recipients', Recipients) See Also
GetParent procedure (*oiObject iParent), long, proc
Retrieves the parent oiObject, if there is one associated with the current object.
Parameters
*oiObject iParent
An oiObject that will hold the parent object.
Return Value
Returns True (1) for success and False (0) for failure. In the event of an error occuring the ErrorTrap method will be called with additional information.
Examples
Appointment oiObject
Recipients oiObject
code
Recipients.GetParent(Appointment)See Also
FromVariant procedure (*oiVariant vtRet), long
Initializes the object using the passed variant. The variant contains an COM object. This method is not typically called directly, in normal use the GetChildEx method provides the ability to retrieved
Parameters
vtRet
An oiVariant which contains a COM object, such as that returned by the Call, CallEx or Get methods.
Return Value
Returns True (1) for success or False (0) for failure.
Examples
Appointment oiObject
varObj like(oiVariant)
code
oItems.pItems.AddInt(1)
! Option1: Get the child object as a Variant and convert it manually
if oItems.CallEx('Item', , varObject) ! Get the item from the Items collection
Appointment.FromVariant(varObject) ! Convert the returned variant to an object
end
! Option 2: Use GetChildEx to convert it internally
oItems.GetChildEx('Item', Appointment)See Also
None
Returns a long that represents the underlying object as a variant. This is used internally to pass objects as parameters. It is not typically used directly.
Parameters
None
Return Value
Returns the address of a variant that contains the object if successful, and zero if a failure occurs..
Examples
Appointment oiObject
varObj long
code
varObject = Appointment.AsVariant()See Also
None
Get procedure (string propertyName, *long pValue), long, proc
Get procedure (string propertyName, *string pValue), long, proc
Get procedure (string propertyName, *long dateValue, *long timeValue), long, proc
Get Procedure (string propertyName, *oiVariant pValue), long, proc
Get Procedure (string propertyName, *short pValue), long, proc
Get Procedure (string propertyName, *real pValue)
Gets a property from an object using the name of the property.
Note: For Clarion 5.5 users these methods are named GetProp, as the C55 compiler does not allow Get as a method name.
Parameters
string propertyName
The name of the property to retrieve.
The following additional parameter options are supported:
pValue
The variable to receive the specified value. Office Inside handles the neccessary type conversion internally.
or
*long dateValue, *long timeValue
When retrieving a date/time, the object splits the Office date/time into a Clarion date and time and stores the values in the passed Long variables.
Return Value
Returns True (1) for success and False (0) for failure. In the event of an error occuring the ErrorTrap method will be called with additional information.
Examples
Appointment oiObject
NameSpace oiObject
ident string(200) ! Outlook Item Identifier
attendeeList string(4096)
code
ident = 'MAPI'
if Outlook.iApplication.GetChild('GetNamespace', Namespace, ident)
if Namespace.GetChild('GetItemFromID', Appointment, ItemID)
Appointment.Get('RequiredAttendees', attendeeList)
end
endSee Also
GetType procedure (string propertyName), long
Returns a long that contains the TYPE for the property that matches the passed propertyName. This can be used to identify the type of a particular property of an object. Use the GetTypeName method to convert the returned integer into
Parameters
propertyName
The name of the property to fetch the type of.
Return Value
Returns an integer for the type of the property, or -1 if an error occurs.
Examples
Appointment oiObject
varObj long
code
varObject = Appointment.AsVariant()See Also
None
GetType procedure (string propertyName), long
Returns a long that contains the TYPE for the property that matches the passed propertyName. This can be used to identify the type of a particular property of an object. Use the GetTypeName method to convert the returned integer into
Parameters
propertyName
The name of the property to fetch the type of.
Return Value
Returns an integer for the type of the property, or -1 if an error occurs.
The following TYPES are defined (Call GetTypeName to convert the TYPE into a string that contains the type description).
oiVARENUM itemize(0), pre(oi)
VT_EMPTY equate(0)
VT_NULL equate(1)
VT_I2 equate(2)
VT_I4 equate(3)
VT_R4 equate(4)
VT_R8 equate(5)
VT_CY equate(6)
VT_DATE equate(7)
VT_BSTR equate(8)
VT_DISPATCH equate(9)
VT_ERROR equate(10)
VT_BOOL equate(11)
VT_VARIANT equate(12)
VT_UNKNOWN equate(13)
VT_DECIMAL equate(14)
VT_I1 equate(16)
VT_UI1 equate(17)
VT_UI2 equate(18)
VT_UI4 equate(19)
VT_I8 equate(20)
VT_UI8 equate(21)
VT_INT equate(22)
VT_UINT equate(23)
VT_VOID equate(24)
VT_HRESULT equate(25)
VT_PTR equate(26)
VT_oiSafeArray equate(27)
VT_CARRAY equate(28)
VT_USERDEFINED equate(29)
VT_LPSTR equate(30)
VT_LPWSTR equate(31)
VT_RECORD equate(36)
VT_FILETIME equate(64)
VT_BLOB equate
VT_STREAM equate
VT_STORAGE equate
VT_STREAMED_OBJECT equate
VT_STORED_OBJECT equate
VT_BLOB_OBJECT equate
VT_CF equate
VT_CLSID equate
VT_VERSIONED_STREAM equate
VT_BSTR_BLOB equate(0fffh)
VT_VECTOR equate(01000h)
VT_ARRAY equate(02000h)
VT_BYREF equate(04000h)
VT_RESERVED equate(08000h)
VT_ILLEGAL equate(0ffffh)
VT_ILLEGALMASKED equate(0fffh)
VT_TYPEMASK equate(0fffh)
endExamples
The example below reads the type of the Zoom property of the Excel PageSetup object. If this is a Boolean value then it means that zooming is disabled and the Fit To Pages options are being used. If it is an integer it means that it is enabled. This example switches the value. Properties with the "dual nature" are fairly uncommon, however GetType and GetTypeName are still immensely useful for debugging.
propType long
code
Excel.GetPageSetup()
propType = Excel.PageSetup.GetType('Zoom')
Message('The Zoom property type is ' & Appointment.GetTypeName(propType))
case propType
of oi:VT_BOOL ! If it's currently a Bool it means it is disabled, set it to a Long value to enable it
Excel.Pagesetup.SetInt('Zoom', 96) ! Switch to using a Zoom (96%)
of oi:VT_I4
Excel.Pagesetup.SetBool('Zoom', oi:False)
Excel.Pagesetup.SetInt('FitToPagesWide', 1)
Excel.Pagesetup.SetInt('FitToPagesWide', 1)
endSee Also
None
GetTypeName procedure (long pType), string
Returns a string that contains a description of the TYPE specified by the pType paramter. Call the GetType method to get the TYPE for a particular property.
Parameters
propertyName
The name of the property to fetch the type of.
Return Value
Returns an integer for the type of the property, or -1 if an error occurs.
Examples
Appointment oiObject
varObj long
code
varObject = Appointment.AsVariant()See Also
None
Set procedure (string propertyName, *real pValue), long, proc
Set procedure (string propertyName, *string pValue), long, proc
Set procedure (string propertyName, *long pValue), long, proc
Set procedure (string propertyName, *short pValue), long, proc
Set procedure (string propertyName, long dateValue, long timeValue), long, proc
Set procedure (string propertyName, long pValue), long, proc
Set procedure (string propertyName, *oiObject pObj), long, proc
Sets the value of a property of an object.
Note: For Clarion 5.5 users these methods are named SetProp, as the C55 compiler does not allow Set as a method name.
Parameters
string propertyName
The name of the property to set the value for.
The following additional parameters options are supported:
pValue
The variable that contains the value to set the property to.
or
dateValue, timeValue
The Clarion date and time to set the DateTime property to. The date and time will be automatically converted to the Office DateTime format.
or
pObj
An oiObject object that represents an object to set the property to (this is infrequently used and handles the case where a property being set is itself and object).
Return Value
Returns True (1) for success and False (0) for failure. In the event of an error occuring the ErrorTrap method will be called with additional information.
Examples
Appointment oiObject
NameSpace oiObject
ident string(200) ! Outlook Item Identifier
code
ident = 'MAPI'
if Outlook.iApplication.GetChild('GetNamespace', Namespace, ident)
if Namespace.GetChild('GetItemFromID', Appointment, ItemID)
Appointment.Set('BusyStatus', oio:Busy) ! Example of setting a property
end
endSee Also
Get, Call, SetInt, SetString, SetBool
SetInt procedure (string propertyName, long pValue), long, proc
Sets the value of a property of an object and passes an integer by value (allowing constants or literal values to be passed). Note that for Boolean values the SetBool method should be called and the Office Boolean value should be used (oi:True and oi:False) not the Clarion boolean values.
Parameters
propertyName
The name of the property to set the value for.
pValue
The value to set the Property to.
Return Value
Returns True is successful or False if an error occurs.
SetBool procedure ((string propertyName, long oiBool), long, proc
Sets the value of a property of an object where the property is a Boolean type (msoTristate). The Office Boolean values should be used (oi:True and oi:False)) not the Clarion boolean values.
Parameters
propertyName
The name of the property to set the value for.
oiBool
The value to set the property to. The Office Boolean values should be used (oi:True and oi:False)) not the Clarion boolean values.
Return Value
Returns True is successful or False if an error occurs.
SetString procedure (string propertyName, string pValue), long, proc
Sets the value of a property of an object and passes the string by value, allowing contants, equates and literals to be passed.
Parameters
propertyName
The name of the property to set the value for.
pValue
The value to set the Property to.
Return Value
Returns True is successful or False if an error occurs.
Call procedure (string methodName), long, proc
Call procedure (string methodName, *long pValue), long, proc
Call procedure (string methodName, *string pValue), long, proc
Call procedure (string methodName, *oiObject pObj), long, proc
Calls a method that belongs to the current object. The oiObject must be intialised by calling Init, or by passing it to the GetChild method of the parent, before this functionality can be called.
Parameters
string methodName
The name of the method to call.
*long pValue, or *string pValue, or *oiObject pObj
Optionally a value can be passed to the called method.
Return Value
Returns True (1) for success and False (0) for failure. In the event of an error occuring the ErrorTrap method will be called with additional information.
Examples
Appointment oiObject
NameSpace oiObject
ident string(200) ! Outlook Item Identifier
code
ident = 'MAPI'
if Outlook.iApplication.GetChild('GetNamespace', Namespace, ident)
if Namespace.GetChild('GetItemFromID', Appointment, ItemID)
Appointment.Call('Save') ! call the Save method
end
endSee Also
CallEx, Call (multi parameter)
Call procedure (string methodName, *oiObject pObj), long, proc
Calls a method that belongs to the current object. The oiObject must be intialised by calling Init, or by passing it to the GetChild method of the parent, before this functionality can be called.
Parameters
string methodName
The name of the method to call.
*long pValue, or *string pValue, or *oiObject pObj
Optionally a value can be passed to the called method.
Return Value
Returns True (1) for success and False (0) for failure. In the event of an error occuring the ErrorTrap method will be called with additional information.
Examples
Appointment oiObject
NameSpace oiObject
ident string(200) ! Outlook Item Identifier
code
ident = 'MAPI'
if Outlook.iApplication.GetChild('GetNamespace', Namespace, ident)
if Namespace.GetChild('GetItemFromID', Appointment, ItemID)
Appointment.Call('Save') ! call the Save method
end
endSee Also
CallEx, Call (multi parameter)
Call procedure (string methodName, *oiParams pParams, long memberType = oi:DISPATCH_METHOD, <*oiVariant vtRet>), long, proc
Calls a method that belongs to the current object. The oiObject must be intialised by calling Init, or by passing it to the GetChild method of the parent, before this functionality can be called. This version of the call Method allows any number of parameters to be passed using an oiParams object. This method is not typically used - generally the CallEx method is used to provide this functionality (the methods are identical in function, this method simply allows an oiParams object to be passed rather than using the oiObject.params object).
Parameters
string methodName
The name of the method to call.
pParams
An oiParams object which contains all the parameters to pass. Use the oiParams.Insert and oiParams.Add methods to add parameters to a call.
memberType
The type of member being called. By default this is calls a method of the object, however multiple parameters can also be passed when getting and setting properties (although this is unusual and seldom used). Can be one of the following values:
oi:DISPATCH_METHOD -
Call a method
oi:DISPATCH_PROPERTYGET - Get a property
oi:DISPATCH_PROPERTYPUT - Put (Set) the
value of a property
oi:DISPATCH_PROPERTYPUTREF - Put a
property that is a reference
vtRet [optional]
An optional oiVariant group. If this is passed then the value returned from the call will be stored in this group. A variant can represent any type of data, including objects. For methods which return an object the variant can be passed to an oiObject's FromVariant method to create a new oiObject which represent that object contained in the variant.
Return Value
Returns True (1) for success and False (0) for failure. In the event of an error occuring the ErrorTrap method will be called with additional information.
See Also
CallEx procedure (string methodName, long memberType = oi:DISPATCH_METHOD, <*oiVariant vtRet>), long, proc
Calls a method that belongs to the current object. This version of the call Method allows any number of parameters to be passed using the oiObject.params member, which can be used to add any number and type of parameters to a call.
The oiObject must be intialised by calling Init, or by passing it to the GetChild method of the parent, before this functionality can be called.
Parameters
string methodName
The name of the method to call.
memberType
The type of member being called. By default this is calls a method of the object, however multiple parameters can also be passed when getting and setting properties (although this is unusual and seldom used). Can be one of the following values:
oi:DISPATCH_METHOD -
Call a method
oi:DISPATCH_PROPERTYGET - Get a property
oi:DISPATCH_PROPERTYPUT - Put (Set) the
value of a property
oi:DISPATCH_PROPERTYPUTREF - Put a
property that is a reference
vtRet [optional]
An optional oiVariant group. If this is passed then the value returned from the call will be stored in this group. A variant can represent any type of data, including objects. For methods which return an object the variant can be passed to an oiObject's FromVariant method to create a new oiObject which represent that object contained in the variant.
Return Value
Returns True (1) for success and False (0) for failure. In the event of an error occuring the ErrorTrap method will be called with additional information.
Examples
The example below calls the Word.Documents.Add method. It demonstrates getting the Documents object from the Word application and then calling the Add method, passing four parameters, one of which is optional. Uses an oiWord object called Word. When multiple calls are made using the same .params object call FreeParams() between each call to clear the values stores.
! Create a new document. Uses the Word.Documents interface
! to add a new document in Word.
!
! Parameters
! template: The name of the template to be used for the new document.
! If this argument is omitted, the Normal template is used.
! newTemplate: oi:True to open the document as a template. The default value is oi:False.
! documentType: Can be one of the following NewDocumentType constants:
! oiw:NewBlankDocument, oiw:NewEmailMessage, oiw:NewFrameset, or oiw:dNewWebPage.
! The default constant is oiw:NewBlankDocument
! visible: oi:True to open the document in a visible window. If this value is oi:False,
! Microsoft Word opens the document but sets the Visible property of the
! document window to oi:False (hidden). The default value is oi:True.
! Return Value
! Returns True for success of False for failure.
NewDoc Procedure(<string template>, long newTemplate = oi:False, long documentType=oiw:NewBlankDocument, long visible=oi:True)
Documents oiObject
code
if not Word.iApplication.GetChild('Documents', Documents)
return False
end
! Call: Application.Documents.Add(template, newTemplate, documentType, visible)
Documents.params.Free()
if Omitted(2)
Documents.params.AddNull()
else
Documents.params.Insert(template)
end
Documents.params.AddBool(newTemplate)
Documents.params.Insert(documentType)
Documents.params.AddBool(visible)
return Documents.CallEx('Add')See Also
ThThe properties provided by the class. Other than the name property, the class does not currently provide any properties that can be accessed.
The name of this object such as "Cell" or "Range".
This is set by the object after the Init or GetChild method is used to associate
the oiObject with an object in the Office Object Model. It is provided primarily
for debugging and convenience. Setting it directly has no effect.
Also see the Generics example application, and the example code provided above for each of the methods. See the CallEx method for additional information and example code.
How To: Pass any number of parameters of any type to a method (or property Get/Set call):
! Inserts the contents of a file into the current document (merging it
! with the document).
! Parameters
! fileName: The name of the file to insert the contents of.
! Notes:
! This calls Selection.InsertFile(fileName, range, confirm, link, attachment)
! The call used in this method merges the file with the current document - i.e.
! it inserts the contents at the end of the current document. The Selection.InsertFile
! method can also be used to insert the contents of a document at a particular
! position (range), as well as it link or attach a document rather than inserting
! it directly.
msWord.InsertFile Procedure(string fileName)
code
if not self.Selection.IsInitialized()
Message('Error, there was no Selection object available. Cannot Insert the file', 'Word File Insertion Error')
return False
end
self.Selection.params.Free()
self.Selection.params.AddString(Clip(fileName))
self.Selection.params.AddNull()
self.Selection.params.AddBool(oi:False)
self.Selection.params.AddBool(oi:False)
self.Selection.params.AddBool(oi:False)
if self.Selection.CallEx('InsertFile') ! Insert the file
return True
else
return False
endThe .params property of each oiObject is an instance of the oiParams class. This allows any number of parameters to be "inserted" before calling the CallEx() method to call the method. This approach can also be used to pass parameters to Get and Set calls by specifying memberType parameter as a value other than oi:DISPATCH_METHOD, which is the default. Other support values are:
oi:DISPATCH_PROPERTYGET equate(02h) - Get a property
oi:DISPATCH_PROPERTYPUT equate(04h) - Set a property
oi:DISPATCH_PROPERTYPUTREF equate(08h) - Set a property reference
In addition an oiVariant can be passed to the method using the vtRet parameter to receive the return value from the call.
How To: Moving Mail Betweeen Folders
The code below demonstrates how to move items between folders. This is based on the actual code in the MoveItem method provided by the oiOutlook class (of course, using the MoveItem method is far simpler is this specific case).
Also note that the oiOutlook object now provides a GetNameSpace method, so the namespace no longer needs to be fetched manually, as well as methods to retrieve the Folders collection etc. This specific example is intended purely to demonstrate the use of the oiObject class.
Folders oiObject ! The Folders collection
InboxFolder oiObject ! The default Inbox (the source folder in this case)
Items oiObject ! A collection of items in the source folder
DestFolder oiObject ! The destination Folder
MailItem oiObject ! Each item that is processed from the source folder
searchString string(200) ! The search string for matching against a Mail field
destFolderName string(80) ! The name of the destination folder
code
! The root item in Outlook is a "NameSpace", which is identified by the string 'MAPI'
! In these examples the namespace is fetched each time a routine is called, however
! It would be more efficient to fetch it once, and then use it as needed, and only
! call the Kill method when done (or allow the object to do this automatically when
! it goes out of scope).
! Get the default MAPI namespace, and then get the default Inbox
ident = 'MAPI'
if Outlook.iApplication.GetChild('GetNamespace', Namespace, ident)
if InboxFolder.Init('GetDefaultFolder', Namespace, oio:FolderInbox)
! Get the Folders collection that is the parent of the default inbox
if Folders.Init('Folders', InboxFolder) and InboxFolder.GetChild('Items', Items)
destFolderName = 'Test'
if Folders.GetChild('Item', DestFolder, destFolderName)
! Find all mail messages with a specific subject line
searchString = '[Subject]="Test Email From Office Inside"'
if not Items.GetChild('Find', MailItem, searchString)
Message('No matching Mail Items were found.', 'No mail to move')
do Cleanup
exit
end
! Move matching mail items to the DestFolder folder
loop
! Found mail item, move it to the Test folde
MailItem.Call('Move', DestFolder)
MailItem.Kill() ! Clean up for the next item
if not Items.GetChild('FindNext', MailItem)
! Loop until there are no more matching items
break
end
end
end
else
Message('The specified destination folder does not exist')
end
end
end
do MailCleanup
! Cleanup: In this case we clean up explictly, as these routines take a "once off" approach.
! In actual code the object would typically be used as many times and needed, and the Kill
! method only called if an object needs to be reused for another purpose (getting a different item for example)
! or the object is no longer used. If the Kill method is not explictly called, then it will be called
! when the object goes out of scope (the procedure that it is declared in exits for example).
MailCleanup routine
NameSpace.Kill()
InboxFolder.Kill()
Folders.Kill()
Items.Kill()
DestFolder.Kill()
MailItem.kill()
How To: Send and Receive for all Accounts.
This example demonstrates using the SyncObject objects to perform a Send and Receive for all accounts.
i long
SyncCol oiObject
SyncObj oiObject
numAccs long
Outlook oiOulook ! Typically populated by the template
code
if Outlook.GetNameSpace()
if Outlook.pNamespace.GetChild('SyncObjects', SyncCol) ! Get the specific appointment object
SyncCol.GetProperty('Count', numAccs)
loop i = 1 to numAccess
if SyncCol.GetChild('SyncObject', SyncObj, i)
SyncCol.CallMethod('Start')
SyncObj.Kill()
else
break
end
end
else
Message('Could not get the SyncObjects collection from Outlook, cannot send and receive')
end
end
SyncCol.Kill()
FAQ (Frequently Asked Questions)
Coming soon.