| xHarbour Reference Documentation > Function Reference | |
 |
 |
 |
Instantiates a new OLE Automation object.
CreateObject( <cProgID> ) --> oOleAuto
cProgID := "Word.Application" // MS Office Word cProgID := "Excel.Application" // MS Office Excel cProgID := "InternetExplorer.Application" // Internet Explorer
The function returns a TOleAuto object which handles OLE automation on behalf of the xHarbour application. When the requested OLE object cannot be instantiated, a runtime error is raised.
OLE automation is a fundamental technology on Windows platforms. It allows for reusing functionality built into existing applications not developed with xHarbour. CreateObject() is the only function required to instantiate an OLE Automation object. For example:
oOLE := CreateObject( "Word.Application" )
This function call loads an instance of MS Office Word into memory and makes the functionality of Word available to the xHarbour application. The returned xHarbour OLE object communicates with the Word application, sends requests to it and returns responses of Word to the xHarbour application.
An OLE Automation object exposes its interface(s), methods and properties to the calling xHarbour application. They are available via methods and instance variables of the xHarbour object returned from CreateObject(). When a method name is sent to this object, the method of the same name of the OLE Automation object is invoked. Likewise, when a value is assigned to an instance variable of the xHarbour object, this value is passed on to a property of the OLE Automation object.
A detailed explanation of the communication between xHarbour and an OLE Automation object goes far beyond this documentation. However, the problem of the developer is to know the names of properties, methods and their arguments available in the OLE Automation object. This information is stored in what is called a Type Library which is part of an OLE application.
Type libraries can be contained in separate files (.tlb, .olb) or can be linked to an executable file (.dll, .exe). The type Library information is extracted from the calling process and is interpreted for data exchange. Refer to the ListOle.prg file in the samples folder of your xHarbour installation for listing information avialable in type libraries.
Note: a commonly used TypeLib viewer is called OleView.exe and is included in the Microsoft Windows SDK. Two example programs below are helpful for an xHarbour user for extracting #define constants and finding help information on an OLE application. Default locations for type libraries of common Microsoft products are listed in the tables below:
Default MS Office directories
| Version | Installation directory |
|---|---|
| Office 97 | C:\Program Files\Microsoft Office\Office |
| Office 2000 | C:\Program Files\Microsoft Office\Office |
| Office XP | C:\Program Files\Microsoft Office\Office10 |
| Office 2003 | C:\Program Files\Microsoft Office\Office11 |
| Office 2007 | C:\Program Files\Microsoft Office\Office12 |
Type library names
| Office product | Ver 97 | Ver 2000 | Ver XP, 2003 and later |
|---|---|---|---|
| Access | Msacc8.olb | Msacc9.olb | Msacc.olb |
| Excel | Excel8.olb | Excel9.olb | Excel.exe |
| Graph | Graph8.olb | Graph9.olb | Graph.exe |
| Outlook | Msoutl97.olb | Msoutl9.olb | MSOutl.olb |
| PowerPoint | Msppt8.olb | Msppt9.olb | MSPpt.olb |
| Word | Msword8.olb | Msword9.olb | MSWord.olb |
The type library of the Internet Explorer is stored in C:\windows\system32\shdocvw.dll.
| See also: | GetActiveObject(), Ole2TxtError(), OleError() |
| Category: | OLE Automation , xHarbour extensions |
| Source: | rtl\win32ole.prg |
| LIB: | xhb.lib, ole.lib |
| DLL: | xhbdll.dll |
Simple Office Automation
// The example outlines Office Automation using MS Office Word as
// automation object. The example creates a new Word document, and
// saves it as DOC, RTF and PDF file.
#define CRLF Chr(13)+Chr(10)
#define wdFormatDocument 0 // .DOC
#define wdFormatRtf 6 // .RTF
PROCEDURE Main
LOCAL cFileName := CurDrive()+":\"+CurDir()+"\test"
LOCAL cDocFile := cFileName+".doc"
LOCAL cRtfFile := cFileName+".rtf"
LOCAL oWord, oDocument, oText
TRY
oWord := GetActiveObject( "Word.Application" )
CATCH
TRY
oWord := CreateObject( "Word.Application" )
CATCH
Alert( "ERROR! Word not avialable. [" + Ole2TxtError()+ "]" )
RETURN
END
END
// create a new, empty Word document
oDocument := oWord:documents:add()
// get the text selection object
oText := oWord:selection()
// assign some text
oText:Text := "OLE from xHarbour" + CRLF
// select font name, size and attribute
oText:font:name := "Arial"
oText:font:size := 48
oText:font:bold := .T.
// display the Word window
oWord:visible := .T.
// maximize the word window
? oWord:windowState := 1
// save file as regular DOC file
oDocument:saveAs( cDocFile )
// save file as rich text
oDocument:saveAs( cRtfFile, wdFormatRtf )
// hide Word window
oWord:Visible := .F.
oDocument:close()
/******************* C A U T I O N ***********************
*
* oDocument is automatically released from memory and
* cannot be used anymore after being :close()ed
*
******************* C A U T I O N ***********************/
// create new Document object
oDocument := oWord:documents:open( cRtfFile )
oWord:visible := .T.
// select PDF printer driver
oWord:activePrinter := "FreePDF XP"
// print PDF file via PDF printer driver
oWord:printOut()
// terminate Word application
oWord:quit()
RETURN
Finding OLE Help files
// A good OLE Automation product comes with a help file explaining
// the interfaces, properties and methods. The following example
// implements a utility program that opens the online help file of
// an OLE application, if it is available.
//
// The complete file name of the file including the type library
// must be passed as command line parameter.
//
// e.g: C:\Program Files\Microsoft Office\Office12\MsWord.olb
#define NO_HELP_FILE "No help file available"
#define SW_SHOW 5
PROCEDURE Main( cFileName )
LOCAL oTypeLib, cHelpFile, cSearch
CLS
IF Empty( cFileName )
? "Usage: FindHelp.exe <typeLibraryFileName>"
QUIT
ENDIF
TRY
? "Loading Type Library, please wait..."
oTypeLib := LoadTypeLib( cFileName, .T. )
CATCH
? "Unable to load Type Library for:", cFileName
QUIT
END
cHelpFile := OLEHelpFile( oTypeLib )
IF cHelpFile == NO_HELP_FILE
? cHelpFile
QUIT
ENDIF
IF .NOT. File( cHelpFile )
cSearch := SearchHelpFile( cHelpFile )
IF cSearch == NO_HELP_FILE
? "Help file not found:", cHelpFile
QUIT
ELSE
cHelpFile := cSearch
ENDIF
ENDIF
? "Help file found:"
?
? cHelpFile
?
? "Press Y to open help file"
?
WAIT "(Y/N) "
IF Chr(LastKey()) $ "yY"
OpenHelpFile( cHelpFile )
ENDIF
RETURN
// Extracts the help file location from a type library
FUNCTION OLEHelpFile( oTypeLib )
LOCAL cFile := NO_HELP_FILE
LOCAL oOLE_CLASS
FOR EACH oOLE_CLASS IN oTypeLib:Objects
IF .NOT. Empty( oOLE_CLASS:HelpFile )
cFile := oOLE_CLASS:HelpFile
EXIT
ENDIF
NEXT
RETURN cFile
// Language specific help files are installed in
// sub-directories. Search sub-directories for help files.
FUNCTION SearchHelpFile( cHelpFile )
LOCAL aDir
aDir := DirectoryRecurse( cHelpFile )
RETURN IIf( Empty( aDir ), NO_HELP_FILE, aDir[1,1] )
// Open help file with associated viewer application
FUNCTION OpenHelpFile( cHelpFile )
LOCAL nRet, cPath, cFileName, cFileExt
HB_FNameSplit( cHelpFile, @cPath, @cFileName, @cFileExt )
nRet := _OpenHelpFile( cPath, cHelpFile )
RETURN nRet
#pragma BEGINDUMP
#pragma comment( lib, "shell32.lib" )
#include "hbapi.h"
#include <windows.h>
HB_FUNC( _OPENHELPFILE )
{
HINSTANCE hInst;
LPCTSTR lpPath = (LPTSTR) hb_parc( 1 );
LPCTSTR lpHelpFile = (LPTSTR) hb_parc( 2 );
hInst = ShellExecute( 0, "open", lpHelpFile, 0, lpPath, SW_SHOW );
hb_retnl( (LONG) hInst );
return;
}
#pragma ENDDUMP
Extracting enumerated OLE constants
// This program extracts enumerated constants from a
// type library and creates a list of #define constants
// applicable for properties of an OLE Automation object.
// Output is directed to STDOUT.
//
// The complete file name of the file including the type library
// must be passed as command line parameter.
//
// e.g: C:\windows\system32\shdocvw.dll
#translate ? [<x,...>] => OutStd( Chr(13)+Chr(10) ); OutStd( <x> )
#translate ?? [<x,...>] => OutStd( <x> )
PROCEDURE Main( cFileName )
LOCAL oTypeLib
CLS
IF Empty( cFileName )
? "Usage: OleConst.exe <typeLibraryFileName>"
QUIT
ENDIF
TRY
QOut( "Loading Type Library, please wait..." )
oTypeLib := LoadTypeLib( cFileName, .T. )
CATCH
QOut( "Unable to load Type Library for:", cFileName )
QUIT
END
IF .NOT. Empty( oTypeLib:Enumerations )
? "// "
? "// Enumerations Extracted from file:"
? "// "
? "// ", cfileName
? "// "
?
?
ListOleEnums( oTypeLib:Enumerations )
ENDIF
RETURN
// Collect enumerations in hash for automatic alpha sort
STATIC PROCEDURE ListOleEnums( aEnums )
LOCAL hEnums, oEnum, aConst, oConst
LOCAL nAlign := 0
LOCAL i, imax
hEnums := Hash()
HSetCaseMatch( hEnums, .F. )
FOR EACH oEnum IN aEnums
aConst := Array( Len( oEnum:constants ) )
hEnums[ oEnum:name ] := aConst
// Collect constants in array for value sort
FOR EACH oConst IN oEnum:constants
aConst[ HB_EnumIndex() ] := oConst
nAlign := Max( nAlign, Len( oConst:name ) )
NEXT
NEXT
// Output xHarbour code for CH file
imax := Len( hEnums )
FOR i:=1 TO imax
? "/*", PadL( " * ", nAlign + 20, "*" )
? PadR( " * ENUMERATION: "+ HGetKeyAt( hEnums, i ), nAlign + 20 ), "*"
? " *", PadL( " */", nAlign + 20, "*" )
ListDefines( HGetValueAt( hEnums, i ), nAlign )
?
NEXT
RETURN
// Output #define directives for an xHarbour #inlude file
STATIC PROCEDURE ListDefines( aConst, nPad )
LOCAL i, imax := Len( aConst )
LOCAL oConst
// Sort by value, not by name, for readability
ASort( aConst,,, {|o1,o2| o1:value < o2:value } )
FOR EACH oConst IN aConst
? "#define ", PadR( oConst:name, nPad ), " 0x"+NumToHex(oConst:value,8)
IF oConst:helpString <> NIL
?? " //", oConst:helpString
ENDIF
NEXT
RETURN
http://www.xHarbour.com