OfficeInside header Vote for this Product at ClarionShop  
Buy now at ClarionShop
Version version number Gold
CapeSoft Sofware copyright
www.capesoft.com
c3pa approved
     




Contents
 

What's new in OfficeInside 3

 
bullet small General Information
 

Start Here!
License & Copyright
Introduction
Important Changes and Version Compatibility
Features
Support
How to install "Office Inside"
System Requirements
What you need to ship
Office Inside Templates  ( Quick Reference )
Office Inside Class Reference
Data Types and Equates
Version History
 

    Using the oiObject Class to access the Office Object Model
    oiExcelImpEx - importing and exporting to and from Excel
bullet small Component-specific documentation
 
 word icon Microsoft Word Excel icon Microsoft Excel
Outlook icon Microsoft Outlook Powerpoint icon Microsoft PowerPoint 
bullet small Dll Functions
 

oi_ChangeDefaultShowMessageIcon
oi_DebugMessage
oi_GetFileVersionInfo
oi_ GetOSVersionInfo
oi_GetRegValue
oi_GetWorkAreaHeight
oi_GetWorkAreaWidth
oi_UnloadCOM
oi_GetCStringFromBstr
oi_FreePWVariantCache
oi_SetFocusWindow
oi_SetRegValue
oi_GetClarionDateFromLongLong
oi_GetClarionTimeFromLongLong

oi_OpenDoc
oi_RGBToBGRLong
oi_SendEmail
oi_SetForegroundWindow
oi_SetRegValue
oi_SysTempDir
oi_ Version
oi_GetLongLongFromClarionDateTime
oi_LongToHex
oi_ByteToHex
oi_HexToLong
oi_RGBLongToBGRLong
oiDecToBase
oiBaseToDec

bullet small Useful References
 

Tips & FAQs
Using Office Inside with File Explorer

Example Applications
Considerations when upgrading from earlier versions of Office Inside
Getting Started with Office Automation
Using DebugView
Office Inside Coding Conventions
Office Inside DLL version info
Version History

     

horizontal rule

bulletStart Here!

Welcome to Office Inside!  If you are new to Office Inside, or if you have not used the product for a while, these steps should get you going in the right direction.

Whether you are just starting off with this product, or are wanting to see what features the current version offers, or are wanting to find out how to do something with Office Inside, the best place to start is typically with the examples.  The abc "Demo" app (offdemo.app and the Clarion 6 version offdemo6.app) is the most comprehensive of the examples, and will show most of the features which Office Inside has to offer.  A good place to start is to compile this example application and spend a few minutes having a look at what it can do ( we recommend doing this each time you install a new version of Office Inside also ).  Once you have found what you're wanting to do, you can then have a look at the source code to see how we did it.  This documentation explains the various objects, templates, and function calls which we use, but the example is easier to get your teeth into, and we'd suggest using this documentation more as a reference than as something which you read from start to finish.  A common question is "Office Inside is so big, how do I find what I'm looking for?".  To answer that question see the section titled Getting Started with Office Automation.

Another useful habit to get into is to read the Product History each time you install a new version of Office Inside, which will list the changes / improvements / new features which have been added.

If you are still unsure about something after you've looked at the example applications, and read the documentation, feel free to contact us for further assistance or to be pointed in the right direction. The Frequently Asked Questions is another useful reference to read through once in a while, and may give you some ideas as to what other Developers are asking about and using the product for.

Enjoy!


horizontal rule

bullet License& Copyright

This template is copyright © 2011 by CapeSoft Software. None of the included files may be distributed (with the exception of the DLLs when distributing your application in standalone mode, and pwutil.dll which you need to always ship with your application see What You Need To Ship for more information). Your programs which use "Office Inside" can be distributed without any "Office Inside" royalties.

Each developer needs his own license to use CapeSoft Office Inside. (Need to buy more licenses?)

This product is provided as-is. Use it entirely at your own risk. Use of this product implies your acceptance of this, along with the recognition of copyright stated above. In no way will CapeSoft Software, their employees or affiliates be liable in any way for any damages or business losses you may incur as a direct or indirect result of using this product.

 

horizontal rule  

bulletIntroduction

Why "another" Office product you might ask? Primarily because for the first time Clarion is now able to access COM components without the performance and stability problems we experienced in the past. With those obstacles out of the way, there is now room for a product that makes it really easy to implement Office functionality into your apps without having to spend substantial amounts of time learning new technologies or tweaking your code. Want to add spell-checking?  Two minutes. Want to generate editable Word documents from all your existing reports? 2 minutes. Drop it in, and compile. When new versions of MS Office are released, download the latest version of Office Inside, recompile, and ship. That's why.

The way the product is "built" is as follows: We have built several classes which we ship as a DLL and lib. These classes handle the complexity of communicating with MS Office COM components (interfaces), and simplify complex tasks, data types and logic into easy-to-use methods. We then have templates which implement those classes for you. You can either use our templates ( we will add more templates and expand on the existing ones regularly ), or you can write code which calls our classes. We provide example applications showing how to do both.

bullet Important Changes and Version Compatibility

From time to time there will be changes in Office Inside that may produce compile errors in your code, or require changes within you application.

Office Inside 2.40 - August 2007

Office Inside 1.95 - 03 April 2006

 

horizontal rule

bulletFeatures


NOTE: Have a look at the section titled "Version History" to see what we're working on and what progress we're making.

 

horizontal rule

bulletSupport

Your questions, comments and suggestions are welcome. Check our web page (www.capesoft.com) for new versions. You can also contact us in one of the following ways.


CapeSoft Support
  Email support@capesoft.com  
Telephone +27 21 715 4000
Fax +27 21 715 2535
Post PO Box 511, Plumstead, 7801, Cape Town, South Africa
     

Office Inside can be purchase at $397 from:

CapeSoft Sales
  Web www.capesoft.com  
Email sales at capesoft dot com
Telephone
+27 21 715 4000
Fax
+27 21 715 2535
Post
PO Box 511, Plumstead, 7801, Cape Town, South Africa
     



Buy Online
  Web  
 
 
 
 
     

 

horizontal rule

bulletHow to install "Office Inside"

To install "Office Inside", run the supplied installation file.  The install file will optionally register the template for you, and update your redirection file to include various subdirectories within Clarion\3rdParty\.

horizontal rule

bulletSystem Requirements

In order for Office Inside to use the MS Office components, those components must be available. This means that if you want to use the templates that generate MS Word reports (for instance), MS Word must be installed on the PC. Office Inside supports all versions of Office from Office 2000 onwards (2003 and up is recommended). Office 2007, Office 2010 and future versions are fully supported. OfficeInside will continue to work with all future versions as long as the Office COM interface exists.

horizontal rule

bulletWhat you need to ship

DLLs required (Standalone mode compiles)
  Clarion Version DLL required  
Clarion 6.1 / Clarion 6.2 C60OFFX.DLL and PWUTIL.DLL
Clarion 5.5 C55OFFX.DLL and PWUTIL.DLL
     

DLLs required (Local mode compiles)
  Clarion Version DLL required  
Clarion 6.1 / Clarion 6.2 PWUTIL.DLL
Clarion 5.5 PWUTIL.DLL
     

 

horizontal rule

bulletTemplates

This table (Quick Reference) can be used to easily locate documentation on any of the Office Inside templates (listed below alphabetically).

Office Inside Templates : Quick Reference
  Component Template Description  
  (all) Activate_Office_Inside Global extension for using Office Inside in your application.
excel icon Excel Add_MSExcel_Object Adds and configures an object in your procedure and allows the object type and settings to be chosen.
excel icon Excel ImportXLStoTPSAbc Template Utility to add an Excel Import Wizard to your application.
excel icon Excel ImportAnXLSFile Code template for adding an Excel Import function to a button or other control.
Outlook Add_MSOutlook_Object Adds and configures an object in your procedure and allows the object type and settings to be chosen.
word icon Word Add_MSWord_Object Adds and configures an object in your procedure and allows the object type and settings to be chosen.
word icon Word OfficeInside Spell Checking Window Controls Adds the Spell Checking controls to a window to provide feedback for spelling checking. We recommend using the provided template utility "ShowSpellingSuggestionsABC" or "ShowSpellingSuggestionsLegacy" to add the procedure to your application.
word icon Word OfficeInside Spell Checking Adds and configures an object in your procedure and allows the object type and settings to be chosen.
word icon Word Office Inside Spell Check for C55 RTF Control template. Adds a button to allow an RTF control to be spell checked in C55. This only applies to C55, in Clarion 6 and above the RTF control supports spell checking using the Word_Spellingchecking template without the need for this control template.
     

Below follows a list of all the Office Inside templates which are not "component-specific", meaning that they do not only apply to a single component of Office. Use the "Quick Reference" table (above) for a complete listing of all the Office Inside templates.

Template : Activate_Office_Inside
 
Summary
 
Global Extension Template
Activate CapeSoft Office Inside Features in your application
Required
 

What does it do?
You must add this template to your app or no other templates / objects will work. This template sets up the Office Inside classes (dll / lib) so that other templates can implement those classes.
 

How do I implement it?

1. Open your app
2. Select "Global Properties" from the "Application" menu
3. Click the "Extensions" button
4. Click the "Insert" button Select "Activate_Office_Inside" ( found under "Class OfficeInside" )
5. Click the "Select" button ( you can leave all default settings, these are discussed below )
6. Click "OK"
7. Click "OK" again

If you are using Legacy and would like to use the Editable Report Word and Excel template you need to ticked on "Enable the use of ABC classes" checkbox under Global Settings on the Classes tab. Please also note that in Legacy you must have at least one of the SV report output templates added. This limitation will be removed in a future release.

     

horizontal rule

bullet Class Reference

The most frequently used classes are the oiWord, oiExcel, oiOutlook and oiPowerpoint classes, which are documented separately, see the Component Specific Documentation links in the Contents. This section documents additional classes that provide other functionality, as well as object that are generic to all of the application classes.

oiRecentFiles

The oiRecentFiles class represents the Recent Files list for each of the Office application. This is the list that you typically see at the bottom of the File menu in Word, Excel and PowerPoint and it contains a list of the most recently used documents for the particular application. Each one of the Office Inside application classes contain a RecentFiles object. This object is initialised for you when the parent is initialised (so when the Init() method of oiWord, oiExcel, oiPowerpoint etc. is called). In addition the list is populated when the object is initialised and corresponds to the list when the office Application starts.

The RecentFiles class also allows you to refresh the list, and to perform actions on the files in the list, such as delete them, open them in the currently open Office application etc. The oiRecentFiles class contains a queue of oiRecentFile objects, each object represents a specific file. You don't need to manage the RecentFile objects, the parent class does it for you and provides methods to access them easily.

See the Demo application for an example of using the RecentFiles class. Below the class methods are described briefly, full documentation and example code will be added to future releases.

Copy Procedure(*oiRecentFilesQ fileQ)

This method copies the Recent Files list into a queue for use in your application. The example demonstrates using this method to populate a queue and then display the contents in a listbox.

Init procedure(long pApplication)

Initialises the object and populates the queue with the recent files list. This is done for you when the application initialises and typically this method never needs to be called.

Kill procedure()

Cleans up and destroys the object, this is done when the Kill method of the application is called and typically this method would never need to be called manually.

Refresh procedure()

Clears all queue entries and fetches the list again. This is useful for ensuring that the list is up to date if documents have been opened, closed or created.

Fetch procedure(long index)

Fetches a specific enter from the queue.

Count procedure

Returns the number of files in the list

Insert procedure(string fileName)

This adds a new file to the Recent Files list in the Office application. This method allows you to add a file to the list that the user did not necessarily open with the Office application.

Open procedure(long index)

Opens the Recent File in the Office application. The index parameter specifies which file in the list should be opened.

Delete procedure(long index)

Deletes a file from Recent Files list.

 

horizontal rule

bullet Data Types and Equates

For data types and equates that relate to a specific Office Inside object please see the documentation on the Word, Excel, Outlook and PowerPoint classes.

Equates

The size equates below are used for the various fields and type declared in Office Inside. For example the data types used by the Outlook class for storing Appointments, Tasks, Contacts etc.

_oit:TinyStringSize           equate( 20 )                      ! Really small Office Inside String Size
_oit:SmallStringSize equate( 50 ) ! Small Office Inside String Size
_oit:MedStringSize equate( 100 ) ! Medium Office Inside String Size
_oit:StdStringSize equate( 255 ) ! Standard Office Inside String Size
_oit:LargeStringSize equate( 1024 ) ! Large Office Inside Sting size
_oit:TelNoStringSize equate( 30 ) ! String size for telephone / fax numbers _oit:EntryIDSize equate(_oit:LargeStringSize)
   

horizontal rule

bulletDLL Functions

These functions can be called from anywhere within your app ( so long as you have added the "Activate_Office_Inside" global extension template ).
Dll Functions
 

oi_ChangeDefaultShowMessageIcon
oi_DebugMessage
oi_GetFileVersionInfo
oi_ GetOSVersionInfo
oi_GetRegValue
oi_GetWorkAreaHeight
oi_GetWorkAreaWidth
oi_WordAvailable
oi_UnloadCOM
oi_GetCStringFromBstr
oi_FreePWVariantCache
oi_SetFocusWindow
oi_SetRegValue
oi_GetClarionDateFromLongLong
oi_GetClarionTimeFromLongLong

oi_OpenDoc
oi_RGBToBGRLong
oi_SendEmail
oi_SetForegroundWindow
oi_SetRegValue
oi_SysTempDir
oi_Version
oi_GetLongLongFromClarionDateTime
oi_LongToHex
oi_ByteToHex
oi_HexToLong
oi_RGBLongToBGRLong
oiDecToBase
oiBaseToDec

 
     


oi_ChangeDefaultShowMessageIcon  (string pIconName)

Globally changes the icon used in the ShowMessage methods.

This function does not need to be called for each object.  Typically you would call this function as your Application (frame) initializes.

Parameters

string pIconName

A string that contains the icon name (or equate) to use.

Examples

oi_ChangeDefaultShowMessageIcon(icon:exclamation)

oi_ChangeDefaultShowMessageIcon('
~csoOffice.ico')


 

oi_DebugMessage   ( string debugMessage)

Sends a Debug Message to your Debug Console, such as Debug View.

Parameters

string debugMessage: A string to output to the system debug output.

Return Value

None.

Examples

oi_DebugMessage('MyApp: Call the SendEmail method to send the mail message.')


 

oi_GetFileVersionInfo   (string pFileName), string

Used to read the version number information from a file's resource information. Returns the version information as a string.

Parameters

string pFileName

A string containing the file name (and path) of the file to extract the version resource information from.

Return Value

A string containing the version information for the specified file.

Examples 

versionString = oi_GetFileVersionInfo (LongPath() & '\oihelper.exe')


 

oi_GetOSVersionInfo ( ),string

This function returns the current Operating System.

The syntax of the string returned is as follows:

OS.MajorVersion.MinorVersion.BuildNumber; e.g. NTS.0005.0001.0000.

We always return the string in the format XXXX.XXXX.XXXX.XXXX, to make string processing easier (i.e. ReturnString[1:4], ReturnString[6:9], ReturnString[11:14], ReturnString[16:19] ). Note that the OS component could be preceded by blank spaces ( e.g. "  95" ) to make string processing easier, while the remaining components will be preceded by zeros (0) if they are not 4 characters long, or will be clipped to the first four characters if they are longer. This may sound complicated but it makes coding much easier (as illustrated above).

  • The OS component of the string returned will be one of the following:
    •  31  (Windows 3.1)
    •  95  (Windows 95)
    •  98  (Windows 98)
    •  ME  (Windows Millennium)
    • NTW  (NT Workstation)
    • NTS  (NT Server)
    • W2KP  (Windows 2000 Professional)
    • W2KS  (Windows 2000 Server)
    • 0000  (Four zeros indicates an unknown OS, please notify CapeSoft support)

Parameters

None

Return Value

Returns a string containing the Windows version information

Examples

versionString = oi_GetOSVersionInfo()
if versionString[3:4] = '
95'
    ! Windows 95
end
buildNumber = versionString[16:19]
displayText = Left(versionString)

 

 

oi_GetRegValue (string parentFolder, string nameOfKey, string nameOfValue), string

Reads a value from the Windows registry.

Parameters

string parentFolder

The parent folder to fetch the key from, this is typically on of the preset root register hives (folders):

'HKEY_LOCAL_MACHINE'
'HKEY_CURRENT_USER'
'HKEY_CLASSES_ROOT'
'HKEY_USERS'
'HKEY_CURRENT_CONFIG'

string nameOfKey

The name of the key to retrieve

string nameOfValue

The name of the value to retrieve from the specified key

Return Value

The value of the registry key (if it exists and could be retrieved). This value is returned as a string.

Examples

deviceName = oi_GetRegValue('HKEY_CURRENT_USER', 'Software\Microsoft\Windows NT\CurrentVersion\Windows', 'Device')


 

oi_GetWorkAreaHeight   ( ),long
TempLong = oi_GetWorkAreaHeight ()
  • Returns the height (in pixels) of the work area for the primary display monitor.  The work area is the portion of the screen not obscured by the Windows' taskbar or by application desktop toolbars.
     
oi_GetWorkAreaWidth   ( ),long
TempLong = oi_GetWorkAreaWidth ()
  • Returns the width (in pixels) of the work area for the primary display monitor.  The work area is the portion of the screen not obscured by the Windows' taskbar or by application desktop toolbars.
     
oi_OpenDoc  ( string FileName ),byte,proc
TempByte = oi_OpenDoc ('c:\temp\MyDoc.doc')
  • At this time this method simply uses ShellExecute to open the document (passed as "FileName").  This is useful if you simply want to start an MS Office application and open a document.  This method has nothing to do with COM, and you have no control over the MS Office application.  It is purely a wrapper for ShellExecute to save you from having to prototype anything. 
oi_RGBToBGRLong   ( long pR, long pG, long pB ) ,long
MyWord.SetFontColor( color:blue )
MyWord.SetFontColor( 13373688 )
MyWord.SetFontColor( oi_RGBToBGRLong(248, 16, 204) )
  • This function takes converts three individual color parameters (R, G, and B) and returns a long (BGR) which Microsoft Word can use to set various color properties, as shown above.
     
oi_SendEmail   ( string pToAddress, string pCCAddress, string pBCCAddress, string pSubject, string pAttachments, string pBody, byte pPlainText, byte pOpen=false ) ,byte,proc
  1. This function is not recommended for most scenarios, as it creates and destorys the Outlook object each time it is called. A better approach is to add an Outlook object to the procedure using the template provided, and set the template to initialise the object when the window is opened and kill it when the window is closed. To send an email the SendEmail method of the oiOulook object is used. The parameters are identical to the oi_SendEmail method. This has two advantages:
    1. Outlook is initialised when the window is opened, so there is no long delay when the Send button is pressed (or the oi_SendEmail method is otherwise called). The initialisation is done transparently when the window is opened, and the cleanup is done when the window is closed.
    2. For sending multiple emails it is a great deal faster, cleaner and less resource intensive, as the Outlook object only needs to be created once, and can then be used to send as many emails as required.

      oi_SendEmail ('support@capesoft.com', '', '', 'Test', '', 'Test Email', false)

oi_SendEmail ('support@capesoft.com', 'arb@capesoft.com; support@capesoft.com', '', 'Test', 'c:\test.txt; c:\myfile.doc', 'This is a test', false)

  • Sends an email from your app, using Outlook.  "Puts" the email into your MS Outlook "Outbox".
  • The pToAddress, pCCAddress and pBCCAddress parameters can all take multiple email addresses, just separate the addresses with semi-colon.
  • The pAttachments parameter can take multiple files, just separate the file names with a semi-colon.
  • The pPlainText parameter must be either false (0), or true (1).  If false, then both html and plain text versions of the email will be sent.  If true, then only a plain text version will be sent.  In the future File Explorer will integrate with this function easily so that you can build the email in a WYSIWYG editor control.
  • The pOpen parameter determines if the email is sent, or displayed on the screen (in which case the user can change it manually before sending it manually).
  • Returns true (1) if no problems were experienced.
     
oi_SetForegroundWindow   ( string WindowTitle )
oi_SetForegroundWindow ('Inbox - Outlook Express')
  • You pass this function the name (in the Title Bar) of a window and it will bring that window to the "front" of your desktop.
     
oi_SetRegValue   (string ParentFolder, string NameOfKey, string NameOfValue, string NewValue),string,proc
oi_SetRegValue('HKEY_CURRENT_USER', 'Software\Microsoft\Windows NT\CurrentVersion\Windows', 'Device', '\\PC3\HP970C,winspool,Ne02:')
  • Writes a value to the Windows' Registry
     
oi_SysTempDir   ( ),string
loc:StringVar = oi_SysTempDir()
  • Returns the path of the system's default temporary directory
     
oi_Version  ( byte pOption=0 ),string
TempString = oi_Version ( ) ! eg. '3.12'
TempString = oi_Version (1) ! eg. '3.12 Beta'
TempString = oi_Version (2) ! eg. '48'
  • Returns Office Inside version information.
  • If pOption is 0, the Office Inside DLL version (number) is returned, as shown above.
  • If pOption is 1, the Office Inside DLL version string (description) is returned, as shown above. 
  • If pOption is 2, the DLL version counter is returned See the section titled "Office Inside dll version info" for more info.

oi_UnloadCOM (byte pOption)

Unloads the COM interface for one or more threads in an application. Use with extreme caution. In general this does not need to be called, as each Office Inside object will dispose of allocated resources and will intelligently dispose of the COM interface on the per thread basis if no other objects are using it.

 Parameters

byte pOption: Determines what the method does. If this is zero then the method does not do anything. If it is set to 1 then the Com interface is disposed for the current thread. Setting pOption to 2 will dispose of it for all threads.

 Return Value

Returns 1 for success and zero for failure.

 Remarks

If the application was started and passed the /oidebugmax switch on the command line then this method will output debug information to the debug log (which can be viewed using the free DebugView tool from www.sysinternals.com).

 

oi_GetCStringFromBstr (*long pbstr)

Returns a cstring when passed a pointer to a bstring object. This method is not commonly used externally at this stage.

 Parameters

*long pbstr: a long containing a pointer (address) of a bstring object in memory.

 Return Values

Returns a pointer to a cstring that contains the contents of the bstring that was passed to the method. The caller is responsible for disposing of the cstring pointer returned.

 

oi_FreePWVariantCache ()

This method frees all cached variants stored in PWVariantFactory objects. The PWVariantFactory class and objects are not exposed and this method does not currently need to be called by applications that use OfficeInside.

 

oi_SetFocusWindow (string windowTitle)

Sets the focus to the window that has the title matching the passed string (windowTitle) parameter. This can be used to give focus to any window on the system, regardless of which application it is. The window that gains focus does not necessarily become visible or change its ordering with other windows. To bring a window to the top (make it the topmost window) call the oi_SetForegroundWindow() method.

 Parameters

string windowTitle: A string that contains the title of the window to give focus to. This can be any window in any application on the system.

 

oi_SetRegValue (string parentFolder, string nameOfKey, string nameOfValue, string newValue)

Sets the value of an entry in the Windows registry based on the passed parameters. If passed key does not exists it is created and the value set to the passed value.

Parameters

string parentFolder: The name of the root key that contains the key to set. Must be one of the following values:

  • 'HKEY_CLASSES_ROOT'
  • 'HKEY_CURRENT_USER'
  • 'HKEY_LOCAL_MACHINE'
  • 'HKEY_USERS'

string nameOfKey: The name of the key that contains the value to be set.

string nameOfValue: The name of the value to be set. If a value with this name is not already present in the key, the function adds it to the key.

If nameOfValue is an empty string, '', the function sets the type and data for the key's unnamed or default value.

string newValue: The new value to set or to be added

Return Value

The functions returns zero for success or an Windows API error code (non zero value) if it fails.

Notes

For more information, see Registry Element Size Limits.

Registry keys do not have default values, but they can have one unnamed value, which can be of any type.


Windows Me/98/95:  Every key has a default value that initially does not contain data. On Windows 95, the default value type is always REG_SZ (a null terminated string). On Windows 98 and Windows Me, an unnamed value can be of any type.

 

oi_LongToHex (long pLong)

Returns a string containing the hexadecimal equivalent of the passed value.

Parameters

long pLong: A long value to convert to a hexadecimal representation

Return Value

A string containing the hexadecimal representation of the passed long value.

Notes

The oiDecToBase() function is a generic form of this method that will convert a decimal (base 10) number to any base, including hexadecimal (base 16)

 

oi_ByteToHex (byte pByte)

Converts a byte to the hexadecimal representation. This function is identical to the oi_LongToHex() function, but converts a byte instead of a long.

Parameters

byte pByte: A byte value to convert to a hexadecimal representation

Return Value

A string containing the hexadecimal representation of the passed long byte.

Notes

The oiDecToBase() function is a generic form of this method that will convert a decimal (base 10) number to any base, including hexadecimal (base 16)

 

oi_HexToLong (string pHex)

Converts the passed hexadecimal value to the equivalent long.

Parameters

string pHex: A string that contains the hexadecimal representation of a number.

Return Values

Returns a long containing the value of the passed string

Notes

The oiBaseToDec() function is a generic form of this method that will convert a number with any base, including hexadecimal (base 16) to decimal (base 10) and return the value as a long.

 

oi_RGBLongToBGRLong (long pRGB)

Flips the byte order of the passed long from RGB to BGR. Used for colour conversion where the first and third bytes (least significant) need to be swapped.

Parameters

long pRGB: A long value that stores a colour in RGB (Red, Green, Blue) byte order.

Return Values

A long representing the passed colour, but with the byte order reversed to BGR (Blue, Green, Red)

 

oiDecToBase (long num, long base=16)

Converts a passed long value to any base (such as hexadecimal, base 16) and returns the value in a string

Parameters

string num: The number to convert

long base: The base to convert the number to. For example 10 converts to Decimal, 16 converts to Hexadecimal, 8 converts to Octal.

Return Values

Returns a string containing the passed number converted to the specified base

 

oiBaseToDec (string num, long base=16)

Converts the passed number to a long value (a "decimal" number). Although the long simply contains the value and is actually binary (base 2) it is typically displayed as a decimal number.

 Parameters

string num: A string containing the number to convert to a long. This number can have any base, such as base 8 (Octal) or base 16 (Hexadecimal).

long base: The base of the number to convert. The passed string will be assumed to be a number with this base.

 Return Value

A long containing the value of the passed number

 

horizontal rule

bulletUSEFUL REFERENCES

bulletGeneral Tips & FAQs

What's new in OfficeInside 3

This section contains Tips and Frequently Asked Questions pertaining to the Office Inside product as a whole.  Tips and FAQs pertaining to specific sections / components of Office Inside can be found as follows:

MS Word related FAQ's ( click here)
MS Excel related FAQ's ( click here )
MS Outlook related FAQ's ( click here )
MS PowerPoint related FAQ's ( click here )

Dynamically Creating OfficeInside objects using New

You can use New to create a new OfficeInside object, however you must ensure that:

  1. The .disabled property of the class is set to 1 directly after the New call.
  2. The Init() method is called after the call to New and setting .disabled to 1.

Example

MyWord        &oiWord
 
code
    MyWord &=
new oiWord
    MyWord.disabled = 1
    MyWord.Init(0, 1)

Compile Errors

  1. I'm getting an error message "Entry Point Not Found / procedure entry point could not be located in the DLL PWUtil.dll"

    Your app is using an old version of the file called "pwutil.dll".  Use whichever version of this dll shipped with the version of File Explorer that you used when compiling the app.
  2. I'm getting compile errors in the offdemo.app example as follows: "FIELD NOT FOUND: REPORT$"

    Fixed in version 1.22 Beta.  The problem seemed to be that some versions of Clarion don't like report labels other than "REPORT". 
  3. The example application will not compile (I'm using Clarion 5.5).

    There seems to be an issue whereby some C55 installations (only C55 "G" as far as I know) have a window.tpw file which does not set up the %LocalClassDefinition embed point, which our templates use.  It might be caused by running the "gold to G" patch, but this has not been confirmed.  You can download the correct version of window.tpw by clicking here.
  4. My application will not compile.  I added the spelling template and now I get a compiler error saying that "oiShowSpellingSuggestions" is an unknown function label...

    You don't have a procedure in your app called "oiShowSpellingSuggestions".  You need to run a template utility which will create this procedure for you.  This is explained in the documentation on the MS Word object.
  5. When using Editable Reports, I get the compile errors "Syntax error: Field Not Found: ADDITEM" and "Syntax error: Unknown procedure label".

    If you are using Legacy and would like to use the Editable Report Word and Excel templates you need to ticked on "Enable the use of ABC classes" checkbox under Global Settings on the Classes tab.
  6. I get a compile error "Invalid use of private data" on a line using an RTFControl.CtlRTF property

    A Checkbox has been added to the Global Extension that should be checked in order to use spell checking on a Clarion 6 RTF control. This has been added because in order to use spell checking on Clarion 6 RTF controls the RtfControlClass needs to have a line modified. If you have ticked this box to enable spell checking of Clarion 6 RTF controls, then open the rtfctl.inc file in your Clarion6\libsrc directory and change the lines that reads: 

     
    CtlRTF SIGNED,PROTECTED

    to:

      CtlRTF SIGNED!,PROTECTED

    The PROTECTED attribute needs to be commented out in order to allow Office Inside to identify which control the object is associated with.
  7. My Legacy application crashes after adding Office Inside.

    This is most likely because you are including the use of the Editable report templates. You can either exclude these on the global extension, or in the application global properties (Classes tab) check the "Enable the use of ABC classes" which will include ABC into your legacy application (thus making the use of the Editable reports possible).

  8. I just upgraded and now I get "Syntax error: No matching prototype available" compiler errors when calling methods like GetContactsQ.

    In version 1.95 we increased the size of the strings used in the queue and group types defined by Office Inside, such as:

    oioFolderNamesQType
    oioFolderItemsQType
    oioAttachmentsQ
    oioContactsQType1
    oioContactProperties
    oioCalendarQType1
    oioAppointmentProperties
    oioTasksQType1
    oioTaskProperties
    oioGrpProgressControls

    If you have declared groups or queue with the same structure for passing to Office Inside methods then you will need to update them. We strongly recommend that you use the types declared in Office Inside rather than redeclaring them inside your application. For example:

    MyAddressList            queue(oioContactsQType1)
                             end
    

General FAQ

1. Can I use Office Inside in a 16-bit app?
bullet small No.


2.

What versions of Clarion does Office Inside support?
bullet small Clarion 5.5, Clarion 6 and Clarion 7.


3.

Does Office Inside support Legacy applications?
bullet small Yes


4.

What will happen if I try to run my app (which uses Office Inside) on a computer where MS Office is not installed?
bullet small Absolutely nothing.  The Office Inside code will simply not work.  It will not freeze the computer, or "time-out" trying to find MS Office.  It will simply do nothing.  Calls to the Office Inside objects will simply fail.  The easiest way to manager this is to test what value the Init methods return.  If Init fails (returns "false"), then you could simply disable any "Office" controls in your app.


5.

Issues with Office Inside and Zone Alarm.
bullet small It has been reported that certain versions of Zone Alarm (including Zone Alarm Pro Ver. 4.5.530.000) seem to cause issues when using Office Inside.  Apparently version 4.0.146.029 works fine..  (Thanks to Johan de Klerk for figuring this one out..)
6. I am using an editable Excel report and a non editable Word report template for the same report and the Word icon is not being displayed on the output selection window.
bullet small You should change the Word report to editable if you are using it in conjunction with the editable Excel report template. This is becuase of the way the report targets are added.
7. My columns in my Excel editable report don't line up, or it just all looks very odd...
bullet small Remember that Excel is very restrictive in what can be displayed, so make sure you think in terms of lining everything up in rows and columns. Try to keep "one column, one control width" in mind, so if there is a control that will go into a particular column make sure that above and below it there aren't multiple controls that will fall into the same "column". It also helps to keep all controls in a column the same width. Future version of the reporting engine will be smarter and do more automatically, but for Excel it is always worth keeping the limitations in mind in order to get great looking reports. We recommend checking the C6 demo application for a good example of a multi page Excel report with numerous controls.

8
What do I need to use the Word and Excel editable report templates?
bullet small
  1. If you are using Legacy and would like to use the Editable Report Word and Excel templates you need to ticked on "Enable the use of ABC classes" checkbox under Global Settings on the Classes tab.
  2. In previous version the Softvelocity Advanced Report output templates were required, this is no longer the case.
9 When UAC is enabled, my application has problems accessing Outlook. 
bullet small Ensure that your applications that will interact with Outlook have a valid manifest file for Vista/Windows 7. Without a valid manifest file, your application may require elevation in order to run, which will prevent Outlook from displaying security prompts to the user. In the event of a security prompt requiring user interaction, this will prevent your application from interacting with Outlook, and it may appears as if your application has locked up while waiting for a response from Outlook. It is strongly recommended that elevated applications do not interact with Outlook directly. The Microsoft design recommendations should be followed - seperated the functionality that requires elevation into a seperate application, or seperate the components that interact with Office into applications that can be run without requiring priviledge elevation.
   

horizontal rule
bulletUsing Office Inside with File Explorer

Prior to Office Inside 2.10 it was not possible to use File Explorer and Office Inside on the same thread (for example both extensions on a single Window). Office Inside 2.10 introduces a new option to the Office Inside Object extensions - "Activate compatibility with File Explorer". In order to use an Office Inside object on the same Window as a File Explorer object, make sure that this check box is checked on the local extension. Each Office Inside control must have this box checked if used on the same window as FileExplorer.

Do not check the box if you have not added FileExplorer to the same procedure, as Office Inside will then not initialise the COM interface, and it will simply not do anything when you call the methods unless you set the oiOffice.noComInit property of the object to zero and call the oiOffice.Init() method after setting this property back to zero.

If you are calling the Init() method manually the you need to set the oiOffice.noComInit property of the object to 1 before calling the Init() method.

 

horizontal rule

bulletExample Applications

Office Inside ships with several example applications, which demonstrate how to implement this product.  These examples can be found in subfolders in your "Clarion\3rdParty\Examples\OfficeInside" folder.  The examples are summarized below:


 

horizontal rule

bulletWhat's new in Office Inside 3:

bullet smallWhat you need to change in your application:

You should import the Spell Checking window using the provided template utility. The new window uses the brand new control template that is part of the OfficeInside 3 spell checking solution.

bullet smallWhy is CapeSoft charging for an upgrade?

As much as we can we try to keep upgrades free. Charging an upgrade gives us the resources to pack in a whole lot of extra functionality into a product, that we would otherwise not be able to do. We are not forcing you to upgrade - and we will continue supporting and building Office Inside 2 in future versions of Clarion. If you would rather not pay for the additional functionality offered in Office Inside 3, you're welcome to continue using Office Inside 2.

bullet small Considerations if upgrading from very early versions of Office Inside

Although we try to ensure that Office Inside is always backward compatible, we may from time to time if we think it is going to improve the product long term, deliberately do something that would make Office Inside non backward compatible.  In such cases we will document these changes in the Version History, as well as provide a summary here:


Version 1.91

A Checkbox has been added to the Global Extension that should be checked in order to use spell checking on a Clarion 6 RTF control. This has been added becuase in order to use spell checking on Clarion 6 RTF controls the RtfControlClass needs to have a line modified. Open the rtfctl.inc file in your Clarion6\libsrc directory and change the lines that reads:

CtlRTF SIGNED,PROTECTED 

to:

CtlRTF SIGNED!,PROTECTED 

The PROTECTED attribute needs to be commented out in order to allow Office Inside to identify which control the object is associated with.


Version 1.40 Beta
- Changed the Init method (all objects: Word, Excel, Outlook etc).  This method now only takes two parameters, as I've done away with the first parameter (EarlyBound)

 

horizontal rule

bullet Getting Started with Office Automation

The simplest definition of automation in this sense is to control another, external program. A large part of what OfficeInside does is to make Automation of Microsoft Office products simpler, by taking care of the complexities inside the OfficeInside DLL. When you use the Office Inside DLL from your own application, all you need to do to start an instance of Microsoft Word (for instance) which you can then control from your application, is write one line of code (assuming you're not using the templates, which would do that for you), as follows: MyObject.Init(). Easy as that. The thousands of lines of code that are needed to actually get an instance of Word available to you and automate (control) that process are hidden from you inside the Office Inside DLL.

The DLL consists in part of several objects, such as oiWord, oiExcel, oiOutlook, etc. Each of these objects contain methods which you can then call to make the Office Programs "do things". For instance, once you have started Microsoft Word, if you wish to write some text to the Word document, you would use the oiWord object's InsertText() method, as follows: MyObject.InsertText('I wrote this'). And again, the DLL would then take care of getting that text into Word.

One of the big questions which we hear is "there are so many methods in Office Inside, how do I know what to look for?". The easiest way to get started is to compile the example application called "OffDemo.app". This example shows off most of what Office Inside is capable of doing, and contains "Automation Examples" for all the Microsoft Office programs which we currently support. Below is a picture of the Microsoft Excel automation example, showing the Clarion window called "Automate MS Excel", along with the instance of Microsoft Excel that the Clarion program started and is now automation ("controlling"). To make life easier for you, we have created a menu bar in each of the Clarion examples which matches the actual menu bar in the applicable Microsoft program. So if you want to know how to insert a picture into Word, you simply use the Clarion example application's "Automate MS Word" procedure, click on the "Insert" menu (in the Clarion example), and then click on "Insert Picture - From File". The actual method that is then called from code will appear in a list box on the Clarion window (as shown below for the Excel example), so that you can see exactly which method you need to use. You can then look up that method in the documentation to find out more about it, how it can be used, and what parameters etc can be used in it!

 

horizontal rule

bulletUsing DebugView

DebugView by SysInternals (now Microsoft) is an application that lets you monitor debug output on your local system. We use DebugView when developing because it gives an accurate picture as to what's happening in your code (as opposed to Message() or Stop()). If you start your application (any application into which Office Inside is compiled) with the following command line parameters, debug output will be generated accordingly, which you can then monitor using DebugView.

MyApp.exe same as MyApp.exe /oidebugoff
MyApp.exe /oidebugoff almost no debug output
MyApp.exe /oidebugmin minimum amount of debug output
MyApp.exe /oidebugmax maximum amount of debug output

Tip

I'd recommend using debug output only when you're testing something. It can be quite annoying for other programmers to work on a system where there are a dozen different apps generating debug output at the same time! To make life easier, all Office Inside debug messages are prefixed with "[OfficeInside]", as shown below. You can set DebugView to ignore all messages that do not contain "[OfficeInside]". You will also take a very small performance hit when running an app with debugging turned on.

 

 

horizontal rule

bulletNotes on Office Inside Coding Conventions

The following coding conventions have been used when building Office Inside:

 

horizontal rule

bulletOffice Inside DLL version info

The oi_Version function returns version information on Office Inside.  See the documentation on this function for more info. The current version of pwutil.DLL that you should ship with your application is 2.5.0.0. Please ensure that you ship the latest version of pwutil.DLL.

horizontal rule

Version History