CapeSoft.Com
Clarion Accessories
Office Inside
Documentation
oiObject
CapeSoft Logo

CapeSoft Office Inside
oiObject Documentation

Download Latest Version FAQ History
Installed Version Latest Version

Introduction

OfficeInside 4 builds on the very basic functionality introduced in Office Inside 3 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.

From there, a number of child, grandchild, and so on, classes can be accessed to explore all the methods and properties that the various Office applications have to offer.

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 demonstrates the fundamentals of the 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 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: oiWord, oiExcel, oiOutlook and oiPowerpoint. 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.

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 Reference.

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 approaches is to record a macro within the Office application itself. If you're not sure how to record a macro, check the FAQ section of this doc.

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 Sub
In 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:
  data
Word			oiWord
Document		oiObject
Selection		oiObject
  code
    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 oiWord class (which derives from oiWord:
msWord.QuickTest procedure ()
Document       oiObject
Selection      oiObject
InlineShapes   oiObject
  code

                 !First we get a handle to the selection object that hangs off the ActiveDocument class, which is a child of the iApplication class.
    if self.iApplication.GetChild('ActiveDocument', Document)    
        if Document.GetChild('Selection', Selection)        

                 !In the VB macro above, we have the first line, which we will now translate into Clarion code
                 !    Selection.TypeText Text:="Hello World"    
                 !The method name is 'TypeText' and there is one string parameter called 'Text'
            Selection.params.AddString('Hello World')   !We first add the string parameter (where there are multiple params, this must be done in order)
            Selection.CallEx('TypeText')                !Now we call the function using CallEx

                 !In the VB macro above, we have the second line, which we will now translate into Clarion code
                 !    Selection.TypeParagraph
                 !The method name is 'TypeParagraph' and in this case there are no params, so we just call the method
            Selection.CallEx('TypeParagraph')
            
                 !Now we get a handle to the InlineShapes object that is a child of the Selection class
            if Selection.GetChild('InlineShapes', InlineShapes)
                InlineShapes.params.AddString('C:\Users\Sean\Pictures\bitshift_avatar_exp.png')  !The first parameter for the AddPicture function
                InlineShapes.params.AddBool(false)                                               !The second parameter (i.e. the LinkTofile property)
                InlineShapes.params.AddBool(true)    !The third parameter (i.e. the SaveWithDocument property)
                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 explicitly 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.

Passing Parameters (oiParams)

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 parameter
For 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 explicit type conversion, passing literal values and for inserting "Null" values for optional parameters:

AddString

AddString (string sVal, long pType = 0)

Description

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

AddBString (string bs)

AddInt

AddInt (long pVal, bool isBool=false)

AddBool

AddBool (long pVal)

AddNull

AddNull ()

Class Methods

Methods provided by the oiObject class, along with examples demonstrating the typical use of each method.
ConstructThe object Constructor
DestructThe object Destructor
InitIntializes the object as a new object of the selected type
KillCleans up and clears the object
IsInitializedChecks whether the object has been initialized
GetChildRetrieves a child object of the current object by name
GetChildExRetrieves a child object and allows parameters to be passed
GetParentReturns the Parent of this object
MoveToMoves this object into another oiObject
AsVariantReturns the address of a Variant that represents the object
FromVariantCreates a new object from a Variant which stores an object
GetRetrieves a property of the object
GetTypeRetrieves the type of a property of the object
GetTypeNameRetrieves a description of the type passed
SetSets a property of the object
SetStringSet a property and pass a string literal
SetIntSet a property and pass a long value
SetBoolSet a property and pass a Office Boolean value
CallCall a method of the object
CallExCall a method of the object

Construct

Construct ()

Description

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

Kill, Init, GetChild

Destruct

Destruct ()

Description

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

Kill, Init, GetChild

ErrorTrap

ErrorTrap ()

Description

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

Kill, Init, GetChild

Init

Init (string pName, *oiObject iParent, <long itemNumber>), long, proc

Description

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
Parameter Description
string pNameThe 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 occurring the ErrorTrap method will be called with additional information.

Examples
Example
Appointment    oiObject
Recipients     oiObject
 code
    Recipients.Init('Recipients', Appointment)

    ! Alternative using GetChild to initialise the object:
    Appointment.GetChild('Recipients', Recipients) 
See Also

GetChild

Kill

Kill ()

Description

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 occurring the ErrorTrap method will be called with additional information.

Examples
Example
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 up
See Also

GetChild , Init

GetChild

GetChild (string cName, *oiObject child, <*long itemNumber>), long, proc
GetChild (string cName, *oiObject child, *string identifier), long, proc


Description

Retrieves a child object based on the name specified. The Office Object model is hierarchical, 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
Parameter Description
string cNameThe 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 identifierAn 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 occurring the ErrorTrap method will be called with additional information.

Examples
Example
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

Init, Kill, GetParent

GetParent

GetParent (*oiObject iParent), long, proc

Description

Retrieves the parent oiObject, if there is one associated with the current object.

Parameters
Parameter Description
*oiObject iParentAn 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 occurring the ErrorTrap method will be called with additional information.

Examples
Example
Appointment   oiObject
Recipients    oiObject
 code
    Recipients.GetParent(Appointment)
See Also

GetChild

FromVariant

FromVariant (*oiVariant vtRet), long

Description

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
Parameter Description
vtRetAn 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
Example
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

AsVariant

AsVariant (), long

Description

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
Example
Appointment   oiObject
varObj        long          
 code
    varObject = Appointment.AsVariant()
See Also

None

Get

Get (string propertyName, *long pValue), long, proc
Get (string propertyName, *string pValue), long, proc
Get (string propertyName, *long dateValue, *long timeValue), long, proc
Get (string propertyName, *oiVariant pValue), long, proc
Get (string propertyName, *short pValue), long, proc
Get (string propertyName, *real pValue)

Description

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
Parameter Description
string propertyNameThe name of the property to retrieve.
The following additional parameter options are supported:
pValueThe variable to receive the specified value. Office Inside handles the necessary type conversion internally.
*long dateValue, *long timeValueWhen 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
Example
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
    end
See Also

Set, Call

GetType

GetType (string propertyName), long

Description

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
Parameter Description
propertyNameThe 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
Example
Appointment   oiObject
varObj        long          
 code
    varObject = Appointment.AsVariant()
See Also

None

GetType

GetType (string propertyName), long

Description

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
Parameter Description
propertyNameThe 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)
                        end
Examples

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.
Example
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)
    end
See Also

None

GetTypeName

GetTypeName (long pType), string

Description

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
Parameter Description
propertyNameThe 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
Example
Appointment   oiObject
varObj        long          
 code
    varObject = Appointment.AsVariant()
See Also

None

Set

Set (string propertyName, *real pValue), long, proc
Set (string propertyName, *string pValue), long, proc
Set (string propertyName, *long pValue), long, proc
Set (string propertyName, *short pValue), long, proc
Set (string propertyName, long dateValue, long timeValue), long, proc
Set (string propertyName, long pValue), long, proc
Set (string propertyName, *oiObject pObj), long, proc


Description

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
Parameter Description
string propertyNameThe name of the property to set the value for.
The following additional parameters options are supported:
pValueThe variable that contains the value to set the property to, or
dateValue, timeValueThe Clarion date and time to set the DateTime property to. The date and time will be automatically converted to the Office DateTime format, or
pObjAn 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
Example
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
    end
See Also

Get, Call, SetInt, SetString, SetBool

SetInt

SetInt (string propertyName, long pValue), long, proc

Description

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
Parameter Description
propertyNameThe name of the property to set the value for.
pValueThe value to set the Property to.
Return Value

Returns True is successful or False if an error occurs.

SetBool

SetBool ((string propertyName, long oiBool), long, proc

Description

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
Parameter Description
propertyNameThe name of the property to set the value for.
oiBoolThe 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

SetString (string propertyName, string pValue), long, proc

Description

Sets the value of a property of an object and passes the string by value, allowing contants, equates and literals to be passed.

Parameters
Parameter Description
propertyNameThe name of the property to set the value for.
pValueThe value to set the Property to.
Return Value

Returns True is successful or False if an error occurs.

Call

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


Description

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
Parameter Description
string methodNameThe name of the method to call.
*long pValue, or *string pValue, or *oiObject pObjOptionally 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 occurring the ErrorTrap method will be called with additional information.

Examples
Example
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
    end
See Also

CallEx, Call (multi parameter)

Call

Call (string methodName, *oiObject pObj), long, proc

Description

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
Parameter Description
string methodNameThe name of the method to call.
*long pValue, or *string pValue, or *oiObject pObjOptionally 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 occurring the ErrorTrap method will be called with additional information.

Examples
Example
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
    end
See Also

CallEx, Call (multi parameter)

Call

Call (string methodName, *oiParams pParams, long memberType = oi:DISPATCH_METHOD, <*oiVariant vtRet>), long, proc

Description

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
Parameter Description
string methodNameThe name of the method to call.
pParamsAn oiParams object which contains all the parameters to pass. Use the oiParams.Insert and oiParams.Add methods to add parameters to a call.
memberTypeThe 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 occurring the ErrorTrap method will be called with additional information.

See Also

CallEx

CallEx

CallEx (string methodName, long memberType = oi:DISPATCH_METHOD, <*oiVariant vtRet>), long, proc

Description

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
Parameter Description
string methodNameThe name of the method to call.
memberTypeThe 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 occurring 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.
Example
! 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

Call

Class Properties

The properties provided by the class. Other than the name property, the class does not currently provide any properties that can be accessed.
handleInternal handle to the interface
parentInternal handle to the parent interface
nameThe name of this object such as "Cell" or "Range"
paramsoiParams object, used for calls with any number of parameters
name string(64) 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.

How Tos and Examples

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
    end
The .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 explicitly, 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 explicitly 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)

How do I record a macro in Word

At the time of writing this document, Word 2010, using the View menu:


Select the 'Record Macro' from the ribbon bar:

You will then be able to record what you want to do. At the end of doing the routine you're wanting to do, select the Stop Recording option from the same menu and then Click View Macros, and then highlight the macro you just recorded and click edit. This will take you to the Macro editor and display the VBA script that you can then use to convert to Clarion code (see Converting a Macro from VBA to Clarion using OfficeInside for more detail).