COM Supporting for REBOL

2. 2 How does it work ?

COMLib.dll is built on top of DispHelper. This Library allows the creation and manipulation of COM Objects, it's properties and methods. DispHelper was built to be fully C/C++ compliant it uses pure API calls so it's very compact and can be linked with many compilers (i use LCC-WIN32). The library uses UNICODE and VARIANT Types to "talk" to the COM Objects so many of the modified functions do a conversion before making the call to the internal dll wrappers This way the dll introduces very few changes to the original disphelper code, ensuring a cleaner and less buggy module. Some original function take pointer to objects, this issue is solved by casting this pointer to an integer, So REBOL can "hold it" (the object reference), this could be particular dangerous because a bad number can crash rebol's interpreter (by corrupting his memory), have special care when using an object, do now overwrite it's value by mistake, and remember, not to use it after you release it, disphelper has SEH (structured error handling) eventually this can prevent the crashes but you can never be sure ! a custom callback "exceptionHandler" will be called, and "exeptionThrown" will be set to true, if some error happened (by example calling a bad method or making a typo error) but in the case of bad pointer, or some thing worst, a general exception is thrown and a message box will show you the function and the line of error.

This graphic will help you understand the work flow.

note:

Some times is good to receive errors, an example is shown on the iexplorer example. For more information about this library, the author and the downloads go to http://sourceforge.net/projects/disphelper/ /note:

3. COMLib.r functions.

initDipsHelper

It takes an integer (it's here for future usage), and returns no value.
Initialize The library

Example: initDipsHelper ;The argument can be any integer

closeDipsHelper

It does not take any arguments, and returns no value.
Closes The library, be sure to release your objects first, after this call it's safe to free the dll resources

Example: closeDipsHelper

setErrorHandler :function

Arguments: a function which takes a string and an integer
It's called upon an error on the dll, using SEH.

Example:
exceptionHandler: func [msg [string!] code [integer!]] [
print msg
print code
return code
]
setErrorHandler :exceptionHandler

createObject

Arguments: the object name as a string!
Returns: A reference of the object as an integer!
Creates a new COM object

example: ieApp: createObject "InternetExplorer.Application"

retrieveObject

Some COM functions return objects, like when you open a new document in word.
The arguments are: the parent object, and the member function.

Example: word_doc: retrieveObject word_obj ".Documents.Add" ""  ;Create a new Document and retrieve the object.
Note: when you stop using the object release it by using release.
release word_obj

makeContainer

Arguments: option, integer! its here for future improvements its safe to pass any value
Returns: an empty object container.

In prior versions of the Library, getObject did not create the object
instead you have to create one your self using this function and pass the object thru.
In some cases a COM method may take an empty object reference.
If this case you can use this function to get a freshly new one.

release

Arguments: an object reference
Release the object make, sure not to use it any more

Example: release word_obj

objectMethod

Arguments: the object which exposes the method, the "method string" and the arguments (if more than one use a block!
calls a COM method by passing the "method string", and the nº arguments it requires

example objectMethod ieApp "Document.Writeln(%s)" "<body bgcolor='black'>"
Note, than the %s will be replaced with the second parameter inside the dll

sendValue

Sets a value inside the Object (like setting public variables from an object)
It's Arguments are: the object, the property to set and the optional values
It's very easy to send more than one value using a block as third parameter

example: sendValue wdBalloon ".Labels(%d).Text = %s" [2 "No they don't"]
Note: the %d will be replaced with the integer 1 and %s with the string "No they don't"
Example passing only one parameter: sendValue ieApp ".Left = %s" "200"

getNumber

It gets a number (integer!) from the object either by calling a method which retrieves a value or by returning a public variable from the object.
The arguments are: an object a member function or property and the optional n arguments

example: num: getNumber MS_script ".Eval(%s)" "2 + 2" 
Note than the %s will be replaced with the string "2 + 2"

getText

retrives the text form an object member method or property
The arguments are: an object a member function or property and the optional n arguments

Example: text: getText word_doc ".Range.Text" ""

4. 3 Examples

Opening MS Word and seting some text in it:

initDipsHelper 1
setErrorHandler :exceptionHandler ;exceptionHandler i will explain this later
word_obj: createObject "Word.Application" ;creates an instance of the COM object
sendValue word_obj ".Visible = %s" "TRUE" ;set it to visible so we can see the word open
word_doc: retriveObject word_obj ".Documents.Add" ""  ;Create a new document retrieve it as an object
sendValue word_obj ".ActiveDocument.ShowSpellingErrors = %s" "0" ;turn spelling off
;setting some text propertyes
color: to-string to-integer to-binary 255.128.0 ;note than R and B get swapped

sendValue word_obj ".Selection.Font.Size = %s" "20"
sendValue word_obj ".Selection.Font.SmallCaps =%s" "1"
sendValue word_obj ".Selection.Font.Name = %s" "Comic Sans MS";
sendValue word_obj ".Selection.Font.Color = %s" color;
message: make string! rejoin [ "REBOL / COM interface Word Sample!" newline] ; create some text
objectMethod word_obj ".Selection.TypeText(%s)" message ;send it to word 
;clean the object
release word_obj

Opening a Browser instance and setting some HTML in it (trivial i guess)

initDipsHelper 1
setErrorHandler :exceptionHandler ;exceptionHandler i will explain this later
ieApp: createObject "InternetExplorer.Application" ;create an instance of the object
objectMethod ieApp ".Navigate(%s)" "About:blank"   ;set it to a blank page
;setting the window properties
;Options
sendValue ieApp ".Toolbar = %s"     "0"
sendValue ieApp ".StatusBar = %s"   "0"
sendValue ieApp ".Width = %s"       "640"
sendValue ieApp ".Height = %s"      "480"
sendValue ieApp ".top = %s"         "200"
sendValue ieApp ".Left = %s"        "200"
;sending some HTML to the Browser
objectMethod ieApp "Document.Writeln(%s)" "<html><head><title>REBOL EULA</title></head>"
objectMethod ieApp "Document.Writeln(%s)" "<body bgcolor='black'>"
;write a png to see if the browser can take it 
save/png join what-dir %logo.png system/view/VID/image-stock/2
;display the logo
img: replace/all to-local-file what-dir "\" "/"
objectMethod ieApp "Document.Writeln(%s)" rejoin ["<img border='0' src='file://" img "/logo.png'>"]
objectMethod ieApp "Document.Writeln(%s)" "<BR>"
objectMethod ieApp "Document.Writeln(%s)" "<p align='justify'><font face='Verdana' color='white' size='2'>"
objectMethod ieApp "Document.Writeln(%s)" system/license
objectMethod ieApp "Document.Writeln(%s)" "</font></p>"
;close the tags
objectMethod ieApp "Document.Writeln(%s)" "</body></html>"
;Show the windows
sendValue ieApp ".Visible = %s" "1"
;whait for the user to close the window
;the basis of this function is to trow an error
;back in C it whas the same but in a nicer manner using SUCCEEDED() macro
while [equal? exeptionThrown false]
[
    to-logic busy: getNumber ieApp ".Busy" "" false
    wait 0.1
]
exaptionThrown: false
;Clean all reference to the object
release ieApp

COM Supporting for REBOL

Contents:

1. 1 What is COMLib ?

2. 2 How does it work ?

3. COMLib.r functions.

4. 3 Examples

5. Known errors and bugs: