 |
 |
||
 |
|||
Version
  www.capesoft.com |
 |
||
Microsoft
Word
Microsoft Excel
Microsoft
Outlook
Microsoft PowerPoint
Start
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!
License
& Copyright
This template is copyright © 2008 by CapeSoft
Software (Pty) Ltd. 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 (Pty) Ltd, 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.
Introduction
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.
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
-
Important: If you are using the 'Import XLS To TPS' control template (now called 'Import and Excel File') then you must move your code for processing each record from the old ImportXLSFile_TakeRecord() method to the new TakeImportRecord() method. Also note that instead of each column being passed as a parameter the columns are now passed using a queue.
Office Inside 1.95 - 03 April 2006
- Important: If you have declared queues with the same structure as those in Office Inside for use with methods such as GetContactsQ then you will need to change the size of the strings in the queue. It is strongly recommended that you use the types defined by Office Inside. See the Demo application for examples. If your queue structures are incorrect you will get the compiler error: Syntax error: No matching prototype available.
Features
-
Take control of Microsoft Office from your
app. No stability issues, no learning curve, no "funny" data
types, no worries. At this time you can automate:
- Microsoft Word
- Microsoft Excel
- Microsoft Outlook
- Microsoft PowerPoint (work in progress)
- Examples, docs, and / or templates will enable you do add the following to your apps in under 5 minutes :
- Spell Checking
- Read / Write to the Address Book
- Add / Edit Tasks in MS Outlook
- Generate read-only, or fully editable Word documents from your existing Clarion reports, without having to add any extra code!
- Generate fully editable Excel spreadsheets from your existing Clarion reports, without having to add any extra code!
- Send email straight to your MS Outlook "Outbox"
NOTE: Have a look at the section titled "Version
History" to see what we're working on and what progress we're making.
Support
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 | |||
| 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 $349 from:
| CapeSoft Sales | |||
| Web | www.capesoft.com | ||
| sales@capesoft.com | |||
| Telephone |
+27 21 715 4000
|
||
| Fax |
+27 21 715 2535
|
||
| Post |
PO Box 511, Plumstead, 7801, Cape Town, South Africa
|
||
| Buy Online | |||
| Web | |||
How
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\.
System
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. At this time Office Inside is being developed for Office 2000, Office XP (2002), and Office 2003 and Office 2007. As new version of Office are released they are tested, and new features may be exposed that only new versions of Office support. In this case they will be noted as such, and using unsupported features will not break on older versions, they will simply not work.
What
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 | ||
Templates
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 | Add_MSExcel_Object | Adds and configures an object in your procedure and allows the object type and settings to be chosen. | ||
| Excel | ImportXLStoTPSAbc | Template Utility to add an Excel Import Wizard to your application. | ||
| 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 | Add_MSWord_Object | Adds and configures an object in your procedure and allows the object type and settings to be chosen. | ||
| Word | Word_SpellChecking | Adds and configures an object in your procedure and allows the object type and settings to be chosen. | ||
| 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 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. |
|||
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 functionlity, 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 (coming soon) 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.
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)
DLL
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 | |||||||||||||||||||||||||||||||||||||||||
|
|||||||||||||||||||||||||||||||||||||||||
USEFUL
REFERENCES
General Tips & FAQs
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:
- The .disabled property of the class is set to 1 directly after the New call.
- 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)
General FAQ
| 1. | 
|
Can I use Office Inside in a 16-bit app? |
| No. | ||
2. |
What versions of Clarion does Office Inside support? |
|
|
Clarion 5.5, Clarion 6 and Clarion 7. | |
3. |
Does Office Inside support Legacy applications? |
|
|
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? |
|
|
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. |
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. | |
| 6. |
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". Thanks to Alan Beames for figuring this one out! | |
| 7. |
Issues with Office Inside and Zone Alarm. |
|
|
|
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..) | |
| 8. |
The example application will not compile (I'm using Clarion 5.5). |
|
|
|
TThere 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. | |
| 9. |
MMy 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. | |
10. |
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. |
|
| 11. | 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 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 |
|
| 12. | 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. | |
|
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. | |
| 13. | My columns in my Excel editable report don't line up, or it just all looks very odd... | |
|
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. | |
14 |
What do I need to use the Word and Excel editable report templates? | |
|
|
|
| 15 | 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 becuase 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. |
|
Using
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.
|
 |
"Demo" - ABC, offDemo6.appThe Clarion 6 version of the full OfficeInside demo application. Clarion 6 provides the Report Generator Interface that Office implements for generation of editable Word and Excel reports (this allows you to output a standard Clarion reports as a Word or Excel file). This application is a great place to start and is updated with all the latest and greatest Office Inside features. Although it uses the ABC template chain, the templates and embed code is identical for Legacy applications.
"Demo" - abc, offDemo.appThe full OfficeInside demo application. This application is a great place to start and is updated with all the latest and greatest Office Inside features. Although it uses the ABC template chain, the templates and embed code is identical for Legacy applications. This is a Clarion 5.5 app file. Other example application have been deprecated as features and example code have been moved to the Demo example.
Considerations
if upgrading from earlier 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)
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!
Using
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.
Notes
on Office Inside Coding Conventions
The following coding conventions have been used when building Office Inside:
- Anything prefixed with an underscore ( e.g. the _ConvertColorValue() method or the _oi:VersionCounter equate ) implies that it was built for "internal" use only, and is not intended to be used publicly (unless otherwise documented). If you choose to use any part of Office Inside (method, property, equate etc) which is prefixed with an underscore, we do not support such use and do not guarantee the effect of doing this or that such methods, properties and equates will not change in future builds (unless specifically otherwise documented).
-
Equates which pertain only to specific Office
Inside components are prefixed as follows:
- Microsoft Word - oiw:
- Microsoft Excel - oix:
- Microsoft Outlook - oio:
- Equates which do not pertain to a specific component ("global" equates) are prefixed with oi: (e.g. oi:REG_NONE)
-
We do not recommend or support calling any methods directly, which are either:- Suffixed with "_LB" or "_EB"
- Not documented
- Refer to the documentation for each method to see how error handling is done. Some methods will return a 1 if the method did not encounter any errors, other methods (where a value needs to be returned) will return a negative number to indicate an error, e.g. oiExcel.CountOpenWorkbooks() which would return 2 if two open workbooks were found, or -1 if an error occurred.