adxvcl
TRANSCRIPT
-
7/31/2019 adxvcl
1/77
,
Getting Started
Add-in Express 2007 for VCL
-
7/31/2019 adxvcl
2/77
Add-in Expr ess VCLAdd-in Expr ess2007 f or VCL
page 2
Add-in Express 2007 for VCL
Document version 3.0
Revised at 27-Dec-06
Product version 3.x
Copyright Add-in Express Ltd. All rights reserved.
Add-in Express, ADX Extensions, ADX Toolbar Controls, Afalina, AfalinaSoft and Afalina Software are trademarks or registered trademarks of Add-in
Express Ltd. in the United States and/or other countries. Microsoft, Outlook and the Office logo are trademarks or registered trademarks of Microsoft
Corporation in the United States and/or other countries. Borland and the Delphi logo are trademarks or registered trademarks of Borland Corporation in the
United States and/or other countries.
THIS SOFTWARE IS PROVIDED "AS IS" AND ADD-IN EXPRESS LTD. MAKES NO REPRESENTATIONS OR WARRANTIES, EXPRESS OR IMPLIED.
BY WAY OF EXAMPLE, BUT NOT LIMITATION, ADD-IN EXPRESS LTD. MAKES NO REPRESENTATIONS OR WARRANTIES OF
MERCHANTABILITY OR FITNESS FOR ANY PARTICULAR PURPOSE OR THAT THE USE OF THE LICENSED SOFTWARE, DATABASE OR
DOCUMENTATION WILL NOT INFRINGE ANY THIRD PARTY PATENTS, COPYRIGHTS, TRADEMARKS OR OTHER RIGHTS.
-
7/31/2019 adxvcl
3/77
Add-in Expr ess VCLTable of Contents
page 3
Table of Contents
Introduction ...........................................................................................................................6Why Add-in Express?...........................................................................................................................................7Add-in Express Extensions .................................................................................................................................8
System Requirements..........................................................................................................................................9
Supported Delphi Versions ...................................................................................................................................... 9Host Applications...................................................................................................................................................... 9
COM Add-ins .......................................................................................................................................................... 9Real-Time Data Servers ....................................................................................................................................... 10Smart Tags........................................................................................................................................................... 10
Technical Support ..............................................................................................................................................11Add-in Express Web Site...................................................................................................................................... 11Internet E-mail Support......................................................................................................................................... 11Technical Support via Instant Messengers ........... .......... ........... .......... .......... ........... .......... ........... .......... .......... ... 11
Installing and Activating ....................................................................................................................................12Activation Basics................................................................................................................................................... 12Setup Package Contents ...................................................................................................................................... 12
Getting Started ....................................................................................................................14Creating Add-in Express Projects ....................................................................................................................15
Add-in Express Modules ........................................................................................................................................ 15COM Add-ins ........................................................................................................................................................ 16RTD Servers......................................................................................................................................................... 16Smart Tags........................................................................................................................................................... 17Excel Automation Add-ins..................................................................................................................................... 17Excel Workbooks.................................................................................................................................................. 18Word Documents.................................................................................................................................................. 18
Add-in Express Components ................................................................................................................................. 20How to Add an Add-in Express Component to Add-in Express Designer .......... ........... .......... ........... ........... ........ 20Office 2007 Ribbon Components.......................................................................................................................... 20Office 2007 Custom Task Panes.......................................................................................................................... 20Command Bars..................................................................................................................................................... 20Command Bar Controls ........................................................................................................................................ 21Built-in Control Connector..................................................................................................................................... 22Keyboard Shortcut ................................................................................................................................................ 23Outlook Bar Shortcut Manager ............................................................................................................................. 23Outlook Forms Manager ....................................................................................................................................... 23Outlook Property Page ......................................................................................................................................... 24Smart Tag............................................................................................................................................................. 24RTD Topic ............................................................................................................................................................ 24Application-level Events........................................................................................................................................ 24MSForms Controls................................................................................................................................................ 24
Your First Microsoft Office COM Add-in ............................................................................................................... 26Step #1 Creating an Add-in Express COM Add-in Project................................................................................. 26Step #2 Add-in Express COM Add-in Module.................................................................................................... 28Step #3 Add-in Express COM Add-in Designer .......... .......... .......... ........... .......... ........... .......... .......... ........... .... 29Step #4 Adding a New Command Bar ............................................................................................................... 30Step #5 Adding a New Command Bar Button.................................................................................................... 31
-
7/31/2019 adxvcl
4/77
Add-in Expr ess VCLTable of Contents
page 4
Step #6 Accessing Host Application Objects .......... .......... ........... .......... ........... .......... .......... ........... .......... ........ 32Step #7 Handling Host Application Events ........................................................................................................ 32Step #8 Handling Excel Worksheet Events ....................................................................................................... 34Step #9 Customizing the Office 2007 Ribbon User Interface............................................................................. 34Step #10 Running the COM Add-in ................................................................................................................... 35Step #11 Debugging the COM Add-in ............................................................................................................... 37Step #12 Deploying the COM Add-in................................................................................................................. 38
Your First Microsoft Outlook COM Add-in ............................................................................................................ 39Step #1 Creating an Add-in Express Outlook COM Add-in Project.................................................................... 39Step #2 Add-in Express COM Add-in Module.................................................................................................... 41Step #3 Add-in Express COM Add-in Designer .......... .......... .......... ........... .......... ........... .......... .......... ........... .... 43Step #4 Adding a New Explorer Command Bar................................................................................................. 44Step #5 Adding a New Command Bar Button.................................................................................................... 45Step #6 Accessing Outlook Objects................................................................................................................... 45Step #7 Handling Outlook Events .......... .......... .......... ........... .......... .......... ........... .......... ........... .......... .......... ..... 45Step #8 Adding a New Inspector Command Bar ............................................................................................... 46Step #9 Handling Events of Outlook Items Object ........... .......... ........... .......... .......... ........... .......... ........... ......... 47Step #10 Adding Folder Property Pages ........................................................................................................... 49Step #11 Intercepting Keyboard Shortcut .......... .......... ........... .......... .......... ........... .......... ........... .......... .......... ... 50Step #12 Customizing the Outlook 2007 Ribbon User Interface........................................................................ 51Step #13 Running the COM Add-in ................................................................................................................... 52Step #14 Debugging the COM Add-in ............................................................................................................... 53Step #15 Deploying the COM Add-in................................................................................................................. 53
Your First Excel RTD Server .................................................................................................................................. 54Step #1 Creating a New Add-in Express RTD Server Project ........................................................................... 54Step #2 Add-in Express RTD Server Module .................................................................................................... 56Step #3 Add-in Express RTD Server Designer.................................................................................................. 57Step #4 Adding and Handling a New Topic ....................................................................................................... 57Step #5 Running the RTD Server ...................................................................................................................... 58Step #6 Debugging the RTD Server .................................................................................................................. 58Step #7 Deploying the RTD Server.................................................................................................................... 59
Your First Smart Tag............................................................................................................................................... 60Step #1 Creating a New Smart Tag Library Project ........... .......... .......... ........... .......... ........... .......... .......... ........ 60Step #2 Add-in Express Smart Tag Module....................................................................................................... 61Step #3 Add-in Express Smart Tag Designer ........... .......... ........... .......... .......... ........... .......... ........... .......... ...... 63Step #4 Adding a New Smart Tag ..................................................................................................................... 63Step #5 Adding and Handling Smart Tag Actions.............................................................................................. 64Step #6 - Running Your Smart Tag....................................................................................................................... 64Step #7 Debugging the Smart Tag .................................................................................................................... 66Step #8 Deploying the Smart Tag...................................................................................................................... 66
Your First Excel Automation Add-in...................................................................................................................... 67Step #1 Creating a New COM Add-in Project.................................................................................................... 67Step #2 Involving Excel Automation Add-in Functionality .......... ........... .......... ........... .......... .......... ........... ......... 69Step #3 Creating User-Defined Functions .......................................................................................................... 69Step #4 Running the Excel Automation Add-in.................................................................................................. 70Step #5 Debugging the Excel Automation Add-in.............................................................................................. 71Step #6 Deploying the Excel Automation Add-in ............................................................................................... 72
Add-in Express Tips and Notes.........................................................................................................................73Terminology .......................................................................................................................................................... 73Getting Help on COM Objects, Properties and Methods ...................................................................................... 73
-
7/31/2019 adxvcl
5/77
Add-in Expr ess VCLTable of Contents
page 5
Add the COM Add-ins Command to a Toolbar or Menu .......... .......... ........... .......... ........... .......... .......... ........... .... 73How to Get Access to the Add-in Host Applications ............................................................................................. 74Registry Entries .................................................................................................................................................... 74ControlTag vs. Tag Property................................................................................................................................. 74Pop-ups ................................................................................................................................................................ 74Edits and Combo Boxes and the Change Event................................................................................................... 74Built-in Controls and Command Bars.................................................................................................................... 74CommandBar.SupportedApps.............................................................................................................................. 75Outlook Command Bar Visibility Rules ................................................................................................................. 75Removing Custom Command Bars and Controls ................................................................................................. 75My Add-in Is Always Disconnected....................................................................................................................... 75Update Speed for an RTD Server......................................................................................................................... 75Sequence of Events When a Task Pane Shows .................................................................................................. 75Adding a Task Pane to an Existing Add-in Express Project.................................................................................. 76Final Note ............................................................................................................................................................. 77
-
7/31/2019 adxvcl
6/77
Add-in Expr ess VCLIntroduction
page 6
Introduction
Add-in Express VCL is a development tool designed to simplify and speed up the
development of Office COM Add-ins, Run-Time Data servers (RTD servers), Smart
Tags, and Excel Automation Add-ins in Delphi 5, 6, 7, 2005, 2006 through the
consistent use of the RAD paradigm. It provides a number of specialized
components that allow the developer to walk through the interface-programming
phase to the functional programming phase with a minimal loss of time
.
-
7/31/2019 adxvcl
7/77
Add-in Expr ess VCLWhy Add-in Express?
page 7
Why Add-in Express?
Microsoft supplied us with another term Office Extensions. This term covers all the customization
technologies provided for Office applications. The technologies are:
COM Add-ins
Smart Tags
Excel RTD Servers
Excel Automation Add-ins
Add-in Express allows you to overcome the basic problem when customizing Office applications building
your solutions into the Office application. Based on the True RAD paradigm, Add-in Express saves the time
that you would have to spend on research, prototyping, and debugging numerous issues of any of the
above-said technologies in all versions and updates of all Office applications. The issues include safe
loading / unloading, host application startup / shutdown, as well as user-interaction-related and deployment-related issues.
-
7/31/2019 adxvcl
8/77
Add-in Expr ess VCLAdd-in Express Extensions
page 8
Add-in Express Extensions
Depending on a product package, Add-in Express includes plug-ins that allow a deeper customization of
Office applications using Add-in Express COM Add-ins.
The Add-in Express Extensions VCL for Microsoft Outlook
The Add-in Express Extensions allows Outlook COM Add-in developers to embed VCL forms into Outlook
windows. See the product description at our web-site http://www.add-in-express.com/outlook-extension/.
Outlook Security Manager
This is a standalone product designed for Outlook solution developers. It allows controlling Outlook Security
by turning it off and on in order to suppress unwanted Outlook Security warnings.
http://www.add-in-express.com/outlook-extension/http://www.add-in-express.com/outlook-extension/ -
7/31/2019 adxvcl
9/77
Add-in Expr ess VCLSyst em Requir ements
page 9
System Requirements
Supported Delphi Versions
Delphi 5 Architect with Update Pack 1
Delphi 5 Enterprise with Update Pack 1
Delphi 5 Professional with Update Pack 1
Delphi 6 Architect with Update Pack 2
Delphi 6 Enterprise with Update Pack 2
Delphi 6 Professional with Update Pack 2
Delphi 7 Architect with Update Pack 1
Delphi 7 Enterprise with Update Pack 1
Delphi 7 Professional with Update Pack 1
Delphi 2005 for VCL Architect with Update Pack 3
Delphi 2005 for VCL Enterprise with Update Pack 3
Delphi 2005 for VCL Professional with Update Pack 3
Delphi 2006 for VCL Architect with Update Pack 2
Delphi 2006 for VCL Enterprise with Update Pack 2
Delphi 2006 for VCL Professional with Update Pack 2
Note
You should have Microsoft Office 2000 Sample Automation Server Wrapper Components installed.
Host Applications
COM Add-ins
Microsoft Excel 2000 and higher
Microsoft Outlook 2000 and higher
Microsoft Word 2000 and higher
Microsoft FrontPage 2000 and higher
-
7/31/2019 adxvcl
10/77
Add-in Expr ess VCLSyst em Requir ements
page 10
Microsoft PowerPoint 2000 and higher
Microsoft Access 2000 and higher
Microsoft Project 2000 and higher
Microsoft MapPoint 2002 and higher
Microsoft Visio 2002 and higher
Microsoft Publisher 2003 and higher
Microsoft InfoPath 2007
Real-Time Data Servers
Microsoft Excel 2002 and higher
Smart Tags
Microsoft Excel 2002 and higher
Microsoft Word 2002 and higher
Microsoft PowerPoint 2003 and higher
Off ice edi t ions, servi ce packs and updates
Add-in Express supports all Microsoft Office service packs and updates for all Microsoft Office
edit ions including Student, Basic, Standard, Professional, Small Business, Enterprise, etc.
-
7/31/2019 adxvcl
11/77
Add-in Expr ess VCLTechnical Support
page 11
Technical Support
Add-in Express is developed and supported by the Add-in Express Team, a branch of Add-in Express Ltd.
You can get technical support using any of the following methods.
Add-in Express Web Site
The Add-in Express web-site at www.add-in-express.com provides a wealth of information and software
downloads for Add-in Express developers, including:
TheHOWTOs section that contains sample projects answering most common "how to" questions.
Add-in Express Toys contains entire and "open sourced" add-ins for popular Office applications.
Forums. We are actively participating in these forums. Really.
Internet E-mail Support
For technical support through the Internet, e-mail us at [email protected].
Technical Support via Instant Messengers
If you are a subscriber of our Premium Support Service and need help immediately, you can request
technical support via an instant messenger, e.g. Windows/MSN Messenger or ICQ. Please ask us at
http://www.add-in-express.com/premium-area/contact-us.php.
http://www.add-in-express.com/http://www.add-in-express.com/support/add-in-express-howto.phphttp://www.add-in-express.com/support/add-in-express-howto.phphttp://www.add-in-express.com/free-addins/http://www.add-in-express.com/forum/mailto:[email protected]://www.add-in-express.com/premium-area/contact-us.phphttp://www.add-in-express.com/premium-area/contact-us.phpmailto:[email protected]://www.add-in-express.com/forum/http://www.add-in-express.com/free-addins/http://www.add-in-express.com/support/add-in-express-howto.phphttp://www.add-in-express.com/ -
7/31/2019 adxvcl
12/77
Add-in Expr ess VCLInstall ing and Acti vating
page 12
Install ing and Act ivat ing
What follows below is a brief guide on activating your copy of Add-in Express.
Activation Basics
During software registration, the registration wizard prompts you to enter your license key. The key is a 25
character alphanumeric code shown in five groups of five characters each (for example, GBFTK-3UN78-
MKF8G-T8GTY-NQS8R). Keep the license key in a safe location and do not share it with others. This
product key forms the basis for your ability to use the software.
For purposes of product activation only, a non-unique hardware identifier is created from general information
that is included in the system components. At no time are files on the hard drive scanned, nor is personally
identifiable information of any kind used to create the hardware identifier. Product activation is completely
anonymous. To ensure your privacy, the hardware identifier is created by what is known as a "one-way
hash". To produce a one-way hash, information is processed through an algorithm to create a new
alphanumeric string. It is impossible to calculate the original information from the resulting string.
Your product key and a hardware identifier are the only pieces of information required to activate the
product.
If you choose the Automatic Activation Process option of the Activation Wizard, the wizard attempts to
establish an online connection to the activation server, www.activatenow.com. If the connection is
established, the wizard sends both the license key and the hardware identifier over the Internet. The
activation service generates an activation key using this information and sends it back to the activation
wizard. The wizard saves the activation key to the registry.
If an online connection cannot be established (or you choose the Manual Activation Process option), you
can activate the software using your web-browser. In this case, you will be prompted to enter the product
key and a hardware identifier on a Web page, and will get an activation key in return. This process finishes
with saving the activation key to the registry.
Activation is completely anonymous; no personally identifiable information is required. The activation key
can be used to activate the product on that computer an unlimited number of times. However, if you need to
install the product on several computers, you will need to perform the activation process again on every PC.
Please refer to your end-user license agreement for information about the number of computers you can
install the software on.
Setup Package Contents
The Add-in Express setup program installs the following folders on your PC:
Packages Add-in Express design-time packages for Delphi 5, 6, 7, 2005, 2006
http://www.activatenow.com/http://www.activatenow.com/ -
7/31/2019 adxvcl
13/77
Add-in Expr ess VCLInstall ing and Acti vating
page 13
Demo Projects demo projects for Delphi 7
Docs Add-in Express documentation
Docs \ Samples sample documentation projects
Sources Add-in Express VCL source code
Sources \ DesignTime design-time source code.
Where is the Add-in Express source code?
Please note we include the source code of Add-in Express .NET according to the product package
you pur chased. See t hePackages & Pricing pagefor det a i ls.
Add-in Express setup program installs the following text files on your PC:
licence.txt EULA
readme.txt short description of the product, support addresses and such
whatsnew.txt this file describes the latest information on the product features added and bugs fixed.
http://www.add-in-express.com/add-in-delphi/pricing.phphttp://www.add-in-express.com/add-in-delphi/pricing.php -
7/31/2019 adxvcl
14/77
Add-in Expr ess VCLGetting Started
page 14
Gett ing Started
In this chapter, we guide you through the following steps of developing Add-in Express Projects:
Create an Add-in Express project
Add an Add-in Express Module to the project
Add Add-in Express components to the Add-in Express Module
Add some business logics
Build, register, and debug the Add-in Express project
Deploy your project to a target PC
For the sake of time, in our support emails we use the ADX.VCL acronym when referring to Add-in Express
.VCL.
You find all the below described samples in the following folder on your PC:
C:\Program Files\Add-in Express\Add-in Express VCL \Docs\Samples
-
7/31/2019 adxvcl
15/77
Add-in Expr ess VCLCreat ing Add-in Expr ess Proj ects
page 15
Creating Add-in Express Projects
Add-in Express VCL adds several project templates to the Extensibility folder of the New Project dialog. To
see the dialog, choose the File | New | Project menu.
Whichever Add-in Express Project template you use, it starts the Add-in Express Project Wizard that allows
selecting Add-in Express project options. The Add-in Express Project Wizard creates the Add-in Express
project and adds an appropriate Add-in Express Module to the project (see Add-in Express Modules).
Add-in Express Modules are the core components of Add-in Express. They allow adding other Add-in
Express components and setting their properties at design-time as well as at run-time (see Add-in Express
Components).
Add-in Express ModulesThere are several Add-in Express Module types responsible for common tasks in automating Office. Below
we list the Office automation tasks. Each task includes an introductory description, the Add-in Express
Module type available for the task, and Add-in Express Components available.
COM Add-ins - TadxCOMAddinModule
RTD Servers TadxXLRTDServerModule
-
7/31/2019 adxvcl
16/77
Add-in Expr ess VCLAdd-in Express Modul es
page 16
Smart Tags - TadxSmartTagModule
Excel Automation Add-ins - TadxCOMAddinModule
Excel Workbooks - TadxExcelSheetModule
Word Documents - TadxWordDocumentModule
COM Add-ins
COM Add-ins have been around since Office 2000 when Microsoft allowed Office applications to extend
their features with COM DLLs supporting the IDTExtensibility2 interface (it is a COM interface, of course).
Since then thousands of developers have racked their brains over this interface and the Office Object Model
that provided COM objects representing command bars, command bar controls, etc. These were the
sources of Add-in Express.
TadxCOMAddinModule represents a COM Add-in in any Office application. To add another add-in to your
assembly, add another TadxCOMAddinModule to your project. For the add-in, you specify its name, host
application(s) and load behavior. The typical value for the LoadBehavior property is Connected &
LoadAtStartup. For See add-ins, you specify the Options page and Folder Property pages (see Outlook
Property Page). Look the following chapters for the Add-in Express components you add onto the
TadxCOMAddinModule: Office 2007 Ribbon Components, Command Bars, Command Bar Controls, Built-in
Control Connector, Keyboard Shortcut, Outlook Bar Shortcut Manager, Outlook Forms Manager, and
Application-level Events.
Use the AddinStartupComplete and AddinBeginShutdown events to handle add-in startup and shutdown.
RTD Servers
RTD Server is a technology introduced in Excel XP. It is a great way to display constantly changing data
such as stock quotes, currency exchange rates, inventory levels, price quotes, weather information, sports
scores, and so on.
A short terminology list follows below:
An RTD server is a Component Object Model (COM) Automation server that implements the IRtdServer
interface. Excel uses the RTD server to communicate with a real-time data source on one or more
topics.
A real-time data source is any source of data that you can access programmatically.
A topic is a string (or a set of strings) that uniquely identifies a piece of data that resides in a real-time
data source. The RTD server passes the topic to the real-time data source and receives the value of the
topic from the real-time data source; the RTD server then passes the value of the topic to Excel for
display. For example, the RTD server passes the topic "New Topic" to the real-time data source, and the
-
7/31/2019 adxvcl
17/77
Add-in Expr ess VCLAdd-in Express Modul es
page 17
RTD server receives the topic's value of "72.12" from the real-time data source. The RTD server then
passes the topic's value to Excel for display.
TadxXLRTDServerModule represents an RTD Server. The only Add-in Express component allowed for this
designer is the RTD Topic. The module provides the Interval property that indicates the time interval
between updates (in milliseconds).
You refer to an existing RTD Server using the RTD worksheet function in Excel:
=RTD(ProgID, Server, String1, String2, ... String28)
The ProgID parameter is a required string value representing the programmatic ID (ProgID) of the RTD
server. See attributes of the RTDServerModule class for the ProgId of your RTD Server. The current version
of Add-in Express requires the Server parameter to be an empty string. Use two quotation marks (""). The
String1 through String28 parameters represent topics of the RTD server. Only the String1 parameter is
required; the String2 through String28 parameters are optional. In most cases, the String1 parameter will be
enough for you. The actual values for the String1 through String28 parameters depend on the requirementsof the real-time data server.
Smart Tags
Office XP bestowed Smart Tags upon us in Word and Excel. Office 2003 added PowerPoint to the list of
smart tag host applications. This technology provides Office users with more interactivity for the content of
their Office documents. A smart tag is an element of text in an Office document having custom actions
associated with it. Smart tags allow recognizing such text using either a dictionary-based or a custom-
processing approach. An example of such text might be an e-mail address you type into a Word document
or an Excel workbook. When smart tag recognizes the e-mail address, it allows the user to choose one ofthe actions associated with the text. For e-mail addresses, possible actions are to look up additional contact
information or send a new e-mail message to that contact.
TadxSmartTagModule lies at the base of the Add-in Express Smart Tags. It represents a set or a library of
smart tag recognizers in Excel, Word, and PowerPoint. The only Add-in Express component you add to the
designer is Smart Tag.
Excel Automat ion Add-ins
Excel 2002 brought in Automation Add-ins a technology that allows writing user-defined functions for usein Excel formulas. Add-in Express .NET provides you with a specialized module, COM Excel Add-in Module,
that reduces this task to just writing one ore more user-defined functions. A typical function accepts one or
more Excel ranges and/or other parameters. Excel shows the resulting value of the function in the cell where
the user calls the function.
-
7/31/2019 adxvcl
18/77
Add-in Expr ess VCLAdd-in Express Modul es
page 18
Add-in Express provides developing Excel Automation Add-ins using the COM Add-in Module that has the
XLAutomationAddin Boolean property. Set the property to true, add a method to the add-in module's type
library, and write the methods code.
Excel Workbooks
Sometimes you need to automate a given Excel workbook (template). You can do it with
TadxExcelSheetModule that represents one worksheet of the workbook. For the module to recognize the
workbook, you need to fill the following properties: Document, Worksheet, PropertyID, and PropertyValue.
When you fill the PropertyID and PropertyValue properties, the design-time code of the module creates the
property in the workbook and specifies its value.
A typical scenario of the module usage includes creating the workbook and designing it with MS Forms
controls. Accordingly, in the IDE, you set up the PropertyID and PropertyValue properties, add Add-in
Express MSForms control components to the module and bind them to the MS Forms controls on the
worksheet. The module provides a full set of events available for the Excel Workbook class.
For the Add-in Express components available for the module see the following chapters: Command Bars,
Command Bar Controls, Built-in Control Connector, MSForms Controls, and Application-level Events.
Note
We regard TadxExcelSheetModule and TadxWordDocumentModule as deprecated and do not
recommend using t hem.
Word Documents
To automate a given Word document, you use the TadxWordDocumentModule. You can do it with
TadxExcelSheetModule that represents a document. For the module to recognize the document, you need
to fill the following properties: Document, PropertyID, and PropertyValue. When you fill the PropertyID and
PropertyValue properties, the design-time code of the module creates the property in the document and
specifies its value.
A typical scenario of the module usage includes creating the document and designing it with MS Formscontrols. Accordingly, in the IDE, you set up PropertyID and PropertyValue properties, add Add-in Express
MSForms control components to the module and bind them to the MS Forms controls on the document. The
module provides a full set of events available for the Word Document class.
For the Add-in Express components available for the module see the following chapters: Command Bars,
Command Bar Controls, Built-in Control Connector, MSForms Controls, and Application-level Events. The
module provides the full set of events available for Word document.
-
7/31/2019 adxvcl
19/77
Add-in Expr ess VCLAdd-in Express Modul es
page 19
Note
We regard TadxExcelSheetModule and TadxWordDocumentModule as deprecated and do not
recommend using t hem.
-
7/31/2019 adxvcl
20/77
Add-in Expr ess VCLAdd-in Express Components
page 20
Add-in Express Component s
How to Add an Add-in Express Component to Add-in Express Designer
You find all the Add-in Express components in the Add-in Express category on the Tool Palette.
Office 2007 Ribbon Components
Office 2007 presented a new Ribbon user interface. Microsoft states that the interface makes it easier and
quicker for users to get the results they want. The developers extend this interface by using the XML markup
that the COM add-in should return to the host through the appropriate interface.
Add-in Express provides some 20 Ribbon-related components to give you the full power of the Ribbon UI
customization features. You start with TadxRibbonTab, TadxRibbonOfficeMenu and TadxRibbonQAT (QuickAccess Toolbar) that get the task of creating the markup upon them. You add controls to a tab or menu
using the convenient tree-view-like editor that allows you to see all the items of the tab or menu at a glance.
Please, note Microsoft require developers to use the StartFromScratch parameter (see the
StartFromScratch property of AddinModule) when customizing Quick Access Toolbar.
TadxRibbonTab and TadxRibbonOfficeMenu support all types of Ribbon controls including regular and
button groups; regular, edit, combo and check boxes; buttons and split buttons; labels and dropdown lists;
galleries and menus; separators and dialog launchers.
Also, note, to use pre-Office2007 command bars in the Office 2007 add-ins, you must explicitly set to True
the UseForRibbon property of the appropriate command bar components. In this case, your toolbars areadded to the Add-ins ribbon tab.
Office 2007 Custom Task Panes
To allow further customization of its applications, Office 2007 provides custom task panes. Add-in Express
supports task panes by providing the appropriate window in the Add-in Express project wizard and
equipping the COM Add-in module with the TaskPanes property. Use the Add-in Express COM Add-in
project wizard to add a task pane(s) to your project. Add your reaction to the OnTaskPaneXXX event series
of the COM Add-in module and the OnDockPositionStateChange and OnVisibleStateChange events of the
task pane.
Command Bars
Microsoft Office 2000-2003 supplied us with a common term for Office toolbars, menus, and context menus.
This term is Command Bar. While look-n-feel of all Office command bars is the same, Outlook command
bars are different from command bars of other Office applications. They are different for the two main
-
7/31/2019 adxvcl
21/77
Add-in Expr ess VCLAdd-in Express Components
page 21
Outlook window types for Outlook Explorer and Outlook Inspector windows. Additionally, different Outlook
Inspector window types show different command bars. Accordingly, Add-in Express provides you with
TadxCommandBar, TadxOlExplorerCommandBar, ad TadxOlInspectorCommandBar components.
The main property of any command bar component is CommandBarName. If its value is not equal to the
name of any built-in command bar of the host application, then you are creating a new toolbar. If its value isequal to any built-in command bar of the host application, then you are connecting to a built-in command
bar. To find out the built-in command bar names, use the free Built-in Controls Scanner utility
(http://www.add-in-express.com/downloads/controls-scanner.php).
To position your command bar, use the Position, Left, Top, and RowIndex properties.
To speed up add-in loading when connecting to an existing command bar, set the Temporary property to
False. To make the host application remove the command bar when the host application quits, set the
Temporary property to true.
Outlook-specific toolbars provide the FolderName, FolderNames, and ItemTypes properties that add
context-sensitive features to the toolbar.
Command Bars in Office 2007
To see a pre-Off ice2007 command bar in the Ribbon UI, set the UseForRibbon property of the
appropri ate Add-in Express command bar component t o t rue.
Command Bar Controls
The Office Object Model (OOM) includes the following command bar controls CommandBarButton,
CommandBarComboBox, and CommandBarPopup. Using the correct property settings of the
CommandBarComboBox component, you can extend the list with edits and dropdowns.
What follows below is a list of controls available for Add-in Express command bars:
TadxCommandBarButton
TadxCommandBarComboBox
TadxCommandBarEdit
TadxCommandBarPopup
TadxCommandBarDropDownList
TadxCommandBarControl (you use this item to add built-in controls to your command bars)
TadxCommandBarAdvancedControl (reserved for future use).
http://www.add-in-express.com/downloads/controls-scanner.phphttp://www.add-in-express.com/downloads/controls-scanner.php -
7/31/2019 adxvcl
22/77
Add-in Expr ess VCLAdd-in Express Components
page 22
Please, note that due to the nature of command bars (remember a 'command bar' stands for toolbar, menu,
and context menu), [context] menu items can be buttons, combo boxes, and pop-ups.
Populate your command bar using the Controls collection both at run-time and at design-time. Every control
(built-in and custom) added to this collection will be added to the corresponding toolbar at your project
startup.
The main property of any command bar control is the Id property. To add a built-in control to your toolbar,
specify its Id in the Id property of the command bar control.
To find out the Ids of every built-in control in the host application, use the free Built-in Controls Scanner
utility (http://www.add-in-express.com/downloads/controls-scanner.php). To add a custom control to the
toolbar, leave the Id property unchanged.
Set up a control's appearance using a great number of its properties, such as Enabled and Visible, Style and
State, Caption and ToolTipText, DropDownLines and DropDownWidth, etc. You also control the size (Top,
Left, Height, Width) and location (Before, AfterId, and BeforeId) properties. To provide your command bar
buttons with a default list of icons, drop an ImageList component to the Add-in Express Module and specify
the ImageList in the Images property of the Add-in Express Module. Dont forget to set the button's Style
property to either adxMsoButtonIconAndCaption or adxMsoButtonIcon. Use the DisableStandardAction
property available for command bar buttons.
Use the OlExplorerItemTypes, OlInspectorItemTypes, and OlItemTypesAction properties to add context-
sensitivity to controls on Outlook-specific command bars. The OlItemTypesAction property specifies an
action that Add-in Express will perform on the control when the current item's type coincides with that
specified by you.
Use the Click event for Button and the Change event for Edit, ComboBox and DropDownList controls.
Built-in Control Connector
Built-in controls of an Office application have predefined IDs. You find the IDs using the free Built-in Controls
Scanner utility (http://www.add-in-express.com/downloads/controls-scanner.php).
The Built-in Control Connector component allows overriding the standard action for any built-in control
without the necessity to add it onto any command bar.
Add TadxBuiltInControl onto TadxCOMAddinModule. Set its Id property to the command bar control ID from
your host application. To connect the component to the command bar control, leave its CommandBar
property empty. To connect the component to the control on a given toolbar, specify the toolbar in the
CommandBar property. To override the default action of the control, use the Action event. The component
traces the context and when the context changes, it reconnects to the currently active instance of the
command bar control with the given Id taking away this task from you.
http://www.add-in-express.com/downloads/controls-scanner.phphttp://www.add-in-express.com/downloads/controls-scanner.phphttp://www.add-in-express.com/downloads/controls-scanner.phphttp://www.add-in-express.com/downloads/controls-scanner.php -
7/31/2019 adxvcl
23/77
Add-in Expr ess VCLAdd-in Express Components
page 23
Keyboard Shortcut
Every Office application provides built-in keyboard combinations that allow shortening the access path for
commands, features, and options of the application. Add-in Express allows adding custom keyboard
combinations and processing both custom and built-in ones.
Add the component onto TadxCOMAddinModule, choose the keyboard shortcut you need in the
ShortcutText property, set the HandleShortCuts property of the Add-in Express Module to true and process
the Action event of the KeyboardShortcut component.
Out look Bar Shortcut Manager
Outlook provides us with the Outlook Bar (Navigation Pane in Outlook 2003). The Outlook Bar displays
Shortcut groups consisting of Shortcuts that you can target to a Microsoft Outlook folder, a file-system
folder, or a file-system path or URL. You use the Outlook Bar Shortcut Manager to customize the Outlook
Bar with your shortcuts and groups.
This component is available for TadxCOMAddinModule. Use the Groups collection of the component to
create a new shortcut group. Use the Shortcuts collection of a short group to create a new shortcut. To
connect to an existing shortcut or shortcut group, set the Caption properties of the corresponding
TadxOlBarShortcut and/or TadxOlBarGroup components equal to the caption of the existing shortcut or
shortcut group. Please note, there are no other ways to identify the group or shortcut.
That is why your shortcuts and shortcut groups must be named uniquely for Add-in Express to remove them
(and not those with the same names) when the add-in is uninstalled. That is why you have to do this
yourself. Depending on the type of its value, the Target property of the TadxOlBarShortcut component
allows you to specify different shortcut types. If the type is MAPIFolder, the shortcut represents a Microsoft
Outlook folder. If the type is a String, the shortcut represents a file-system path or a URL. No events, thanks
to MS.
Out look Forms Manager
Customizing Outlook has a long-dated history. To customize Outlook forms you can use the built-in tools
providing for designing and publishing the form. You can use HTML and VBScript to customize folder views,
and Outlook Today is an example of this approach. Now you can embed custom VCL forms into the Outlook
Explorer and Inspector windows and replace folder views with custom VCL forms.
The Outlook Forms Manager component is available for TadxCOMAddinModule only. It is the core
component of the Add-in Express Extensions VCL for Microsoft Outlook which is a plug-in for Add-in
Express VCL. You find the detailed information on this product at http://www.add-in-express.com/outlook-
extension/. Once again, you don't have this component if you don't have this product bought as part of any
Add-in Express product packages.
http://www.add-in-express.com/outlook-extension/http://www.add-in-express.com/outlook-extension/http://www.add-in-express.com/outlook-extension/http://www.add-in-express.com/outlook-extension/ -
7/31/2019 adxvcl
24/77
Add-in Expr ess VCLAdd-in Express Components
page 24
Outlook Property Page
Outlook allows extending its Options dialog with custom pages. You see this dialog when you choose Tools
| Options menu. In addition, Outlook allows adding such a page to the Folder Properties dialog. You see this
dialog when you choose the Properties item in the folder context menu. You create such pages in the Add-in
Express Outlook Add-in project wizard.
Note, the FolderName, FolderNames, and ItemTypes properties of the Add-in Express Outlook folder pages
work in the same way as those of Outlook-specific command-bars.
Specify reactions required by your business logics in the Apply event handler. In the page controls' event
handlers, use the UpdatePropertyPageSite method to mark the page as Dirty.
Smart Tag
The Kind property of the TadxSmartTag component allows you to choose one of two text recognitionstrategies: either using a list of words in the RecognizedWords string collection or implementing a custom
recognition process based on the Recognize event of the component. Use the ActionNeeded event to
change the Actions collection according to the current context. The component raises the PropertyPage
event when the user clicks the Property button in the Smart Tags tab (Tools / AutoCorrect Options menu) for
your smart tag.
RTD Topic
Use the String## properties to identify the topic of your RTD server. To handle RTD Server startup situations
nicely, specify the default value for the topic and, using the UseStoredValue property, specify, if the RTDfunction in Excel returns the default value (UseStoredValue = false) or doesn't change the displayed value
(UseStoredValue = true). The RTD Topic component provides you with the Connect, Disconnect, and
RefreshData events. The last one occurs (for enabled topics only) whenever Excel calls the RTD function.
Application-level Events
Add-in Express provides event components for all Office applications on the Tool Palette: Just add
appropriate Add-in Express event components to the module, and use their event handlers to respond to the
host application's events.
MSForms Controls
Add-in Express provides MS Forms control components on the Tool Palette These components are to be
used on the TadxExcelSheetModule and TadxWordDocumentModule. Add an appropriate MS Forms
Control Connector to the module. Use the Control Name property of the connector to specify the underlying
control on the Excel worksheet or Word document. Respond to the events provided by the control
connector.
-
7/31/2019 adxvcl
25/77
Add-in Expr ess VCLAdd-in Express Components
page 25
Note
We regard TadxExcelSheetModule and TadxWordDocumentModule as deprecated and do not
recommend using t hem.
-
7/31/2019 adxvcl
26/77
Add-in Expr ess VCLYour First Micr osoft Off ice COM Add-in
page 26
Your First Microsoft Off ice COM Add-in
This chapter highlights almost every aspect of creating COM Add-ins for Microsoft Office applications. You
find this sample in the Docs \ Samples folder of the Add-in Express install folder. This sample shows an
Add-in Express COM Add-in project implementing a COM add-in for Excel and Word.
Out look and Add-in Express
Please note, Add-in Express provides addit ional components for COM Add-ins in Outlook. See Your
First Microsoft Outlook COM Add-in.
Step #1 Creating an Add-in Expr ess COM Add-in Proj ect
Add-in Express adds the Add-in Express COM Add-in project template to the New Item dialog of Borland
Delphi for Microsoft Windows.
When you select the template and click OK, the MS Office COM Add-in Wizard starts. In the wizard
windows, you choose the project options.
-
7/31/2019 adxvcl
27/77
Add-in Expr ess VCLYour First Micr osoft Off ice COM Add-in
page 27
The Add-in Express Project Wizard creates and opens the COM Add-in project in the IDE.
The add-in project includes the following items:
The project source files (ProjectName.*);
The type library files: binary (ProjectName.tlb) and Object Pascal unit (ProjectName_TLB.pas);
The COM add-in module (ProjectName_IMPL.pas and ProjectName_IMPL.dfm) discussed in the
following step.
-
7/31/2019 adxvcl
28/77
Add-in Expr ess VCLYour First Micr osoft Off ice COM Add-in
page 28
Step #2 Add-i n Express COM Add-in Module
The COM Add-in Module (MyAddin1_IMPL.pas and MyAddin1_IMPL.dfm) is the core component of the
COM add-in project (see COM Add-ins). It is the container of the Add-in Express components, which allow
you to concentrate on functionality of your add-in. You specify the add-in properties in the module's
properties, add the Add-in Express components to the module's designer, and write the functional code of
your add-in in this module.
The code for MyAddin1_IMPL.pas is as follows:
unit MyAddin1_IMPL;
interface
uses
SysUtils, ComObj, ComServ, ActiveX, Variants, adxAddIn, MyAddin1_TLB;
type
TcoMyAddin1 = class(TadxAddin, IcoMyAddin1)
end;
TAddInModule = class(TadxCOMAddInModule)
private
protected
public
end;
implementation
{$R *.dfm}
initialization
TadxFactory.Create(ComServer, TcoMyAddin1, CLASS_coMyAddin1,
TAddInModule);
end.
The add-in module contains two classes: the interfaced class (TcoMyAddin1 in this case) and the add-in
module class (TAddInModule). The interfaced class is a descendant of the TadxAddIn class that
implements the IDTExtensibility2 interface required by the COM Add-in architecture. Usually, you don't need
to change anything in the TadxAddIn class.
The add-in module class implements the add-in functionality. It is an analogue of the Data Module, but
unlike the Data Module, the add-in module allows you to set all properties of your add-in, handle its events,
and create toolbars and controls.
-
7/31/2019 adxvcl
29/77
Add-in Expr ess VCLYour First Micr osoft Off ice COM Add-in
page 29
Step #3 Add-i n Express COM Add-in Designer
The designer of COM Add-in Module allows setting add-in properties and adding components to the module.
In the Object Inspector for the module, choose the SupportedApps property and select Excel and Word.
To add an Add-in Express component to the AddinModule designer, you select it in the Tool Palette and
drag-n-drop onto the designer.
You can add the following Add-in Express components to the designer:
TadxRibbonTab represents a Ribbon tab in your add-in (see Office 2007 Ribbon Components)
TadxRibbonQAT represents the Ribbon Quick Access Toolbar your add-in (see Office 2007 Ribbon
Components)
TadxRibbonOfficeMenu represents the Ribbon Office Menu in your add-in (see Office 2007 Ribbon
Components)
TadxCommandBar represents a command bar in your add-in (see Command Bars)
TadxOlExplorerCommandBar represents an Outlook Explorer command bar in your add-in (see
Command Bars)
TadxOlInspectorCommandBar represents an Outlook Inspector command bar in your add-in (see
Command Bars)
TadxBuiltInControl allows intercepting the action of a built-in control of the host application(s) (see
Built-in Control Connector)
TadxKeyboardShortcut allows intercepting application-level keyboard shortcuts (see Keyboard
Shortcut)
-
7/31/2019 adxvcl
30/77
Add-in Expr ess VCLYour First Micr osoft Off ice COM Add-in
page 30
TadxOlBarShortcutManager allows adding Outlook Bar shortcuts and shortcut groups (see Outlook
Bar Shortcut Manager)
TadxOlFormsManager embedding custom VCL forms into Outlook windows (see Outlook Forms
Manager)
Application Events adds or deletes components that provide access to application-level events of theadd-in host applications (see Application-level Events)
Step #4 Adding a New Command Bar
To add a command bar to your add-in, find the TadxCommandBar component in the Tool Palette and drag-
n-drop it onto the TadxCOMAddinModule designer (see Command Bars).
Select the command bar component and, in the Object Inspector window, specify the command bar name
using the CommandBarName property. Also, you select its position in the Position property.
-
7/31/2019 adxvcl
31/77
Add-in Expr ess VCLYour First Micr osoft Off ice COM Add-in
page 31
Command Bars in Office 2007
To display a command bar i n Off ice 2007 you must expl i c i t ly set t he UseForRibbon proper t y of t he
command bar component t o True.
Step #5 Adding a New Command Bar Button
To add a new button to the command bar, in the Object Inspector window, you select the Controls property
of an appropriate command bar component and click the property editor button (the button in the property
value field).
In the Editing window, you select the command bar control type in
the Add button (see also Command Bar Controls).
Specify the button's Caption property and set the Style property
to adxMsoButtonIconAndCaption (default value =
adxMsoButtonCaption). To handle the Click event of the button,
in the Object Inspector window, switch to the Events tab and add
the Click event handler: The code of the event handler follows
below (it's empty as you can see)
-
7/31/2019 adxvcl
32/77
Add-in Expr ess VCLYour First Micr osoft Off ice COM Add-in
page 32
procedure TAddInModule.adxCommandBar1Controls0Click(Sender: TObject);
begin
end;
Step #6 Accessing Host Appli cat ion Obj ects
The Add-in Module provides the HostApplication property that returns the Application object (of the
OleVariant type) of the host application the add-in is currently running in. For your convenience, Add-in
Express provides the App properties, say ExcelApp of the TExcelApplication type and
WordApp of the TWordApplication type. Together with the HostType property, this allows us to write the
following code to the Click event of the button just added.
procedure TAddInModule.adxCommandBar1Controls0Click(Sender: TObject);
begin
case Self.HostType ofohaExcel:
ShowMessage('The current cell is '
+ Self.ExcelApp.ActiveCell.AddressLocal
[False, False, xlA1, EmptyParam, EmptyParam]);
ohaWord:
if Self.WordApp.Selection nilthen
ShowMessage('There are '
+ IntToStr(Self.WordApp.Selection.Words.Count)
+ ' words currently selected');
else
ShowMessage(Self.AddInName
+ ' doesn`t support the current host application');
end;
end;
Step #7 Handling Host Application Events
Add-n Express provides several components that provide the application-level events for the COM Add-in
Module (see Application-level Events). To add Excel events to the add-in, find the TadxExcelAppEvents
component in the Tool Palette and drag-n-drop it onto the module. The TadxWordAppEvents component
supplies the module with Word events.
-
7/31/2019 adxvcl
33/77
Add-in Expr ess VCLYour First Micr osoft Off ice COM Add-in
page 33
With the Events components, you handle any application-level events of the host application. You might see
that the Click event handler in the previous step will fire an exception when there are no workbooks ordocuments open. To prevent this, you disable the button when a window deactivates and enable it when a
window activates. This covers the situations mentioned above.
The code is as follows:
procedure TAddInModule.adxExcelAppEvents1WindowActivate(ASender: TObject;
const Wb: _Workbook; const Wn: Window);
begin
adxCommandBar1.Controls[0].Enabled := true;
end;
procedure TAddInModule.adxExcelAppEvents1WindowDeactivate(ASender: TObject;
const Wb: _Workbook; const Wn: Window);
begin
adxCommandBar1.Controls[0].Enabled := false;
end;
procedure TAddInModule.adxWordAppEvents1WindowActivate(ASender: TObject;
const Doc: _Document; const Wn: Window);
begin
adxCommandBar1.Controls[0].Enabled := true;
end;
procedure TAddInModule.adxWordAppEvents1WindowDeactivate(ASender: TObject;
const Doc: _Document; const Wn: Window);
begin
adxCommandBar1.Controls[0].Enabled := false;
end;
-
7/31/2019 adxvcl
34/77
Add-in Expr ess VCLYour First Micr osoft Off ice COM Add-in
page 34
Step #8 Handling Excel Worksheet Events
In the Tool Palette, find the Servers tab and add an instance of TExcelWorksheet to the add-in module. Now
you can connect the instance to a worksheet, e.g. the active one.
Find the code for handling worksheet events in the code of this add-in.
Step #9 Customizing the Off ice 2007 Ribbon User Interface
To add a new tab to the Ribbon, you add the TadxRibbonTab component to the module.
In the Object Inspector window, run the editor for the Controls collection of the tab. In the editor, use the
toolbar buttons or context menu to add or delete Add-in Express components that form the Ribbon interface
of your add-in. First, you add a Ribbon tab and change its caption to My Ribbon Tab. Then, you select the
tab component, add a Ribbon group, and change its caption to My Ribbon Group. Next, you select the
-
7/31/2019 adxvcl
35/77
Add-in Expr ess VCLYour First Micr osoft Off ice COM Add-in
page 35
group, and add a button group. Finally, you select the button group and add a button. Set the button caption
to My Ribbon Button. Use the ImageList and Image properties to set the icon for the button.
Now add the event handler to the Click event of the newly added Ribbon button. Write the following code:
procedure TAddInModule.adxRibbonTab1Controls0Controls0Controls0Click(
Sender: TObject; const RibbonControl: IRibbonControl);
begin
adxCommandBar1Controls0Click(nil);
end;
Remember, the TadxRibbonTab Controls editor performs the XML-schema validation automatically, so from
time to time you will run into the situation when you cannot add a control to some Ribbon level. It is a
restriction of the Ribbon XML-schema.
See also Office 2007 Ribbon Components.
Step #10 Running the COM Add-in
Choose the Register ActiveX Server item in the Run menu, restart the host application(s) you selected, find
your toolbar and click the button.
-
7/31/2019 adxvcl
36/77
Add-in Expr ess VCLYour First Micr osoft Off ice COM Add-in
page 36
-
7/31/2019 adxvcl
37/77
Add-in Expr ess VCLYour First Micr osoft Off ice COM Add-in
page 37
You find your add-in in the COM Add-ins dialog:
See also Add the COM Add-ins Command to a Toolbar or Menu.
Step #11 Debugging the COM Add-in
To debug your add-in, just indicate the add-in host application in the Host Application field in the Project
Options window.
-
7/31/2019 adxvcl
38/77
Add-in Expr ess VCLYour First Micr osoft Off ice COM Add-in
page 38
Step #12 Deploying the COM Add-in
Make sure your setup project registers the add-in DLL. Say, in Inno Setup projects you use the 'regserver'
command.
-
7/31/2019 adxvcl
39/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 39
Your First Microsoft Outlook COM Add-in
Add-in Express provides the Outlook-specific COM add-in module and two Outlook-specific command bars:
TadxOlExplorerCommandBar and TadxOlInspectorCommandBar. The first adds a command bar to the
Outlook Explorer window and solves many problems with custom Outlook command bars. The latter adds acommand bar to the Outlook Inspector window. Both command bar components have the FolderName(s)
and ItemTypes properties that add context-sensitivity to Outlook command bars. The olExplorerItemTypes,
olInspectorItemTypes, and olItemTypeAction properties add context-sensitivity to Outlook command bar
controls.
Additionally, Add-in Express Outlook Add-in wizards allows creating property pages to be added to the
Options (Tools | Options menu) and folder Properties dialogs.
Step #1 Creating an Add-i n Expr ess Out look COM Add-in Proj ect
Add-in Express adds the Add-in Express COM Add-in project template to the New Item dialog of Borland
Delphi for Microsoft Windows.
When you select the template and click OK, the MS Outlook COM Add-in Wizard starts. In the wizard
windows, you choose the project options and create option pages for your add-in.
-
7/31/2019 adxvcl
40/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 40
The Add-in Express Project Wizard creates and opens the COM Add-in project in the IDE.
-
7/31/2019 adxvcl
41/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 41
The add-in project includes the following items:
The project source files (ProjectName.*);
The type library files: binary (ProjectName.tlb) and Object Pascal
unit (ProjectName_TLB.pas);
The Outlook COM add-in module (ProjectName_IMPL.pas and
ProjectName_IMPL.dfm) discussed in the following step.
The Outlook Property Page (PropertPage_IMPL.pas and
PropertPage_IMPL.dfm) discussed in the Step #10 Adding
Folder Property Pages.
Step #2 Add-i n Express COM Add-in Module
The COM Add-in Module (MyOutlookAddin1_IMPL.pas and MyOutlookAddin1_IMPL.dfm) is the core part of
the COM add-in project (see COM Add-ins). It is the container of the Add-in Express components, which
allow you to concentrate on the functionality of your add-in. You specify add-in properties in the module's
properties, add Add-in Express components to the module's designer, and write the functional code of your
add-in in this module.
The code for MyAddin1_IMPL.pas is as follows:
unit MyOutlookAddin1_IMPL;
interface
uses
SysUtils, ComObj, ComServ, ActiveX, Variants, adxAddIn,
MyOutlookAddin1_TLB, Outlook2000;
type
TcoMyOutlookAddin1 = class(TadxAddin, IcoMyOutlookAddin1)
end;
TAddInModule = class(TadxCOMAddInModule)
procedure adxCOMAddInModuleAddInInitialize(Sender: TObject);
procedure adxCOMAddInModuleAddInFinalize(Sender: TObject);private
protected
procedure NameSpaceOptionsPagesAdd(ASender: TObject;
const Pages: PropertyPages; const Folder: MAPIFolder); override;
public
end;
-
7/31/2019 adxvcl
42/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 42
var
adxcoMyOutlookAddin1: TAddInModule;
implementation
{$R *.dfm}
procedure TAddInModule.adxCOMAddInModuleAddInInitialize(Sender: TObject);
begin
adxcoMyOutlookAddin1 := Self;
end;
procedure TAddInModule.adxCOMAddInModuleAddInFinalize(Sender: TObject);
begin
adxcoMyOutlookAddin1 := nil;
end;
procedure TAddInModule.NameSpaceOptionsPagesAdd(ASender: TObject;
const Pages: PropertyPages; const Folder: MAPIFolder);
function GetFullFolderName(const AFolder: MAPIFolder): string;
var
IDisp: IDispatch;
Folder: MAPIFolder;
begin
Result := '';
Folder := AFolder;
while Assigned(Folder) do begin
Result := '\' + Folder.Name + Result;
IDisp := Folder.Parent;
IDisp.QueryInterface(IID_MAPIFolder, Folder);
end;
if Result ''then Delete(Result, 1, 1);
end;
begin
Pages.Add('MyOutlookAddin1.coPropertyPage1', 'My Property Page');
end;
initialization
TadxFactory.Create(ComServer, TcoMyOutlookAddin1, CLASS_coMyOutlookAddin1,
TAddInModule);
end.
-
7/31/2019 adxvcl
43/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 43
The add-in module contains two classes: the interfaced class (TcoMyOutlookAddin1 in this case) and the
add-in module class (TAddInModule). The interfaced class is a descendant of the TadxAddIn class that
implements the IDTExtensibility2 interface required by the COM Add-in architecture. Usually, you don't need
to change anything in the TadxAddIn class.
The add-in module class implements the add-in functionality. It is an analogue of the Data Module, butunlike the Data Module, the add-in module allows you to set all properties of your add-in, handle its events,
and create toolbars and controls.
Step #3 Add-i n Express COM Add-in Designer
The designer of Outlook COM Add-in Module allows setting add-
in properties and adding components to the module.
To add an Add-in Express component to the AddinModule
designer, you select it in the Tool Palette and drag-n-drop onto
the designer.
You can add the following Add-in Express components to the
designer:
TadxRibbonTab represents a Ribbon tab in your add-in (see Office 2007 Ribbon Components)
TadxRibbonQAT represents the Ribbon Quick Access Toolbar your add-in (see Office 2007 Ribbon
Components)
TadxRibbonOfficeMenu represents the Ribbon Office Menu in your add-in (see Office 2007 Ribbon
Components)
TadxCommandBar represents a command bar in your add-in (see Command Bars)
TadxOlExplorerCommandBar represents an Outlook Explorer command bar in your add-in (see
Command Bars)
TadxOlInspectorCommandBar represents an Outlook Inspector command bar in your add-in (see
Command Bars)
TadxBuiltInControl allows intercepting the action of a built-in control of the host application(s) (see
Built-in Control Connector)
TadxKeyboardShortcut allows intercepting application-level keyboard shortcuts (see Keyboard
Shortcut)
-
7/31/2019 adxvcl
44/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 44
TadxOlBarShortcut allows adding Outlook Bar shortcuts and shortcut groups (see Outlook Bar
Shortcut Manager)
TadxOlFormsManager embedding custom VCL forms into Outlook windows (see Outlook Forms
Manager)
Application Events adds or deletes components that provides access to application-level events of theadd-in host applications (see Application-level Events)
Step #4 Adding a New Explorer Command Bar
To add a command bar to the Outlook Explorer window, use the TadxOlExplorerCommandBar component
from the Add-in Express group in the Tool Palette.
Select the Add-in Express Outlook Explorer
Command Bar component, and, in the Object
Inspector window, specify the command bar name
using the CommandBarName property and choose its
position (see the Position property). Outlook-specific
versions of Add-in Express Command Bar component
provides context-sensitive properties. They are
FolderName, FolderNames, and ItemTypes (see
Outlook Command Bar Visibility Rules).
In the screenshot, you see the Outlook Explorer
command bar that will be shown for every Outlook
folder (FolderName = '') the default item types of
which are Mail or Task.
See also Command Bars.
-
7/31/2019 adxvcl
45/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 45
Step #5 Adding a New Command Bar Button
To add a new button to the Explorer command bar, in the Object
Inspector window, you select the Controls property and click the
property editor button (the button in the property value field).
In the Editing window, you select the command bar control type in
the Add button (see also Command Bar Controls).
Specify the button's Caption property and set the Style property
to adxMsoButtonIconAndCaption (default value =
adxMsoButtonCaption). To handle the Click event of the button,
In the Object Inspector window, switch to the Events tab and add
the Click event handler: The code of the event handler follows
below (it's empty as you can see)
procedure TAddInModule.adxCommandBar1Controls0Click(Sender: TObject);begin
end;
Step #6 Accessing Out look Objects
The Add-in Module provides the App properties that return the Application object (of the
OleVariant type) of the host application the add-in is currently running in. For your convenience, Add-in
Express provides the OutlookApp property of the TOutlookApplication type. This allows you to write the
following code to the Click event of the button just added.
procedure TAddInModule.adxOlExplorerCommandbar1Controls0Click(Sender:
TObject);
begin
ShowMessage('The subject is ' +
OleVariant(Self.OutlookApp.ActiveExplorer.Selection.Item(1)).Subject);
end;
Step #7 Handling Outlook Events
Add-n Express provides several components that provide the application-level events for the COM Add-in
Module (see Application-level Events). To add Outlook events to the add-in, find the TadxOutlookAppEvents
component in the Tool Palette and drag-n-drop it onto the module.
-
7/31/2019 adxvcl
46/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 46
With the Outlook Events component, you handle any application-level events of the Outlook. For instance,
the following code handles the BeforeFolderSwitch event of the Outlook Explorer class:
procedure TAddInModule.adxOutlookAppEvents1ExplorerBeforeFolderSwitch(
ASender: TObject; const NewFolder: IDispatch; var Cancel: WordBool);
begin
ShowMessage('You are switching to the '
+ (NewFolder as MAPIFolder).Name + ' folder');
end;
Step #8 Adding a New Inspector Command Bar
To add a command bar to Outlook Explorer window, use the TadxOlExplorerCommandBar component from
the Add-in Express group in the Tool Palette.
-
7/31/2019 adxvcl
47/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 47
The Inspector command bar component provides the same properties as the Explorer command bar
component. In the screenshot below you see the default values for the Inspector command bar.
Add a new command bar button to the command bar (see
Step #5 Adding a New Command Bar Button for details).
Now you can show the subject of the currently open mail
item using the following code that handles the Click event of
the button:
procedure TAddInModule.adxOlInspectorCommandBar1Controls0Click(Sender:
TObject);
begin
ShowMessage('The subject is ' +
OleVariant(Self.OutlookApp.ActiveInspector.CurrentItem).Subject);
end;
Outlook Inspector Command Bars in Outlook 2007
To display an Inspector command bar in Off ice 2007 you must expl ic i t ly set the UseForRibbon
proper ty of the command bar component t o True.
See also Command Bars and Outlook Command Bar Visibility Rules.
Step #9 Handling Events of Out look Items Object
The Outlook2000 unit provides the TItems component (of the TOleServer type). This component provides
the following events: OnItemAdd, OnItemChange, and OnItemRemove. To process these events, you add
the following declarations and code to the Add-in Module:
-
7/31/2019 adxvcl
48/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 48
TAddInModule = class(TadxCOMAddInModule)
...
private
Items: TItems;
procedure ItemsAdd(ASender: TObject; const Item: IDispatch);
function GetItemsConnected(): boolean;public
procedure ConnectItems;
procedure DisconnectItems;
property AreItemsConnected: boolean read GetItemsConnected;
end;
...
procedure TAddInModule.adxCOMAddInModuleAddInStartupComplete(Sender:
TObject);
begin
ConnectItems;
end;
procedure TAddInModule.adxCOMAddInModuleAddInBeginShutdown(Sender: TObject);
begin
DisconnectItems;
end;
procedure TAddInModule.ConnectItems;
begin
Items := TItems.Create(nil);
Items.OnItemAdd := ItemsAdd;
Items.ConnectTo(
Self.OutlookApp.GetNamespace('Mapi').
GetDefaultFolder(olFolderInbox).Items);
end;
procedure TAddInModule.DisconnectItems;
begin
if not Assigned(Items) then exit;
Items.Disconnect;
Items.Free();
Items := nil;
end;
function TAddInModule.GetItemsConnected: boolean;
begin
Result := false;
if Assigned(Items) then
Result := Items.DefaultInterface nil;
end;
-
7/31/2019 adxvcl
49/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 49
procedure TAddInModule.ItemsAdd(ASender: TObject; const Item: IDispatch);
begin
ShowMessage('The item with subject "'
+ OleVariant(Item).Subject
+ '" has been added to the Inbox folder');end;
Step #10 Adding Folder Proper ty Pages
Outlook allows you to add custom option pages to the Options dialog box (the Tools | Options menu) and /
or to the Properties dialog box of any folder. To automate this task, the Add-in Express wizard provides you
with the Option Pages window (see Step #1 Creating an Add-in Express Outlook COM Add-in Project).
By default, an option page contains two controls only: a label and an edit box.
The edit box shows how to handle the OnChange event and update the corresponding option page.
procedure TcoPropertyPage1.Edit1Change(Sender: TObject);
begin
GetPropertyPageSite;
// TODO - put your code here
UpdatePropertyPageSite;
end;
You add the TCheckBox component to the Property page, handle its OnClick event following the code
template above, and connect or disconnect the TItems component in the Apply method. You initialize the
check box using the OnCreate event of the property page:
procedure TcoPropertyPage1.ActiveFormCreate(Sender: TObject);
begin
CheckBox1.Checked := adxcoMyOutlookAddin1.AreItemsConnected;
end;
function TcoPropertyPage1.Apply: HResult;
begin
if CheckBox1.Checked then
adxcoMyOutlookAddin1.ConnectItemselse
adxcoMyOutlookAddin1.DisconnectItems;
FDirty := False;
Result := S_OK;
end;
-
7/31/2019 adxvcl
50/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 50
Finally, you change the NameSpaceOptionsPagesAdd event handler in the AddinModule code as follows:
...
procedure TAddInModule.NameSpaceOptionsPagesAdd(ASender: TObject;
const Pages: PropertyPages; const Folder: MAPIFolder);
...begin
if Folder.EntryID =
Self.OutlookApp.GetNamespace('Mapi').
GetDefaultFolder(olFolderInbox).EntryID
then
Pages.Add('MyOutlookAddin1.coPropertyPage1', 'My Property Page');
end;
See also Outlook Property Page.
Step #11 Intercept ing Keyboard Shortcut
To intercept a keyboard shortcut, you add an ADXKeyboardShortcut component to the COM Add-in Module
using the Add Keyboard Shortcut command of the module.
In the Object Inspector window you select (or enter) the desired shortcut in the ShortcutText property. We
chose the shortcut for the Send button in the mail Inspector's Standard command bar. It is Ctrl+Enter.
HandleShortcuts property
To use keyboard short cuts, you need t o set t he HandleShort cuts propert y of AddinModule t o t rue.
Now you handle the Action event of the component:
-
7/31/2019 adxvcl
51/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 51
procedure TAddInModule.adxKeyboardShortcut1Action(Sender: TObject);
begin
ShowMessage('You`ve pressed ' +
TadxKeyboardShortcut(Sender).ShortcutText);
end;
Step #12 Customizing the Out look 2007 Ribbon User Interface
To add a new tab to the Ribbon, you add the TadxRibbonTab component to the module.
In the Object Inspector window, run the editor for the Controls collection of the tab. In the editor, use the
toolbar buttons or context menu to add or delete Add-in Express components that form the Ribbon interface
of your add-in. First, you add a Ribbon tab and change its caption to My Ribbon Tab. Then, you select the
tab component, add a Ribbon group, and change its caption to My Ribbon Group. Next, you select the
group, and add a button group. Finally, you select the button group and add a button. Set the button caption
to My Ribbon Button. Use the ImageList and Image properties to set the icon for the button.
Now add the event handler to the Click event of the button. Write the following code:
-
7/31/2019 adxvcl
52/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 52
procedure TAddInModule.adxRibbonTab1Controls0Controls0Controls0Click(Sender:
TObject; const RibbonControl: IRibbonControl);
begin
adxOlInspectorCommandBar1Controls0Click(nil);
end;
Remember, the TadxRibbonTab Controls editor perform the XML-schema validation automatically, so from
time to time you will run into the situation when you cannot add a control to some Ribbon level. It is a
restriction of the Ribbon XML-schema.
Note, unlike other Ribbon-based applications, Outlook has numerous ribbons. Please use the Ribbons
property of your TadxRibbonTab components to specify the ribbons you customize with your tabs.
See also Office 2007 Ribbon Components.
Step #13 Running the COM Add-inChoose the Register ActiveX Server item in the Run menu, then restart Outlook and find your option
page(s), command bars, and controls.
You find your add-in in the COM Add-ins dialog:
See also Add the COM Add-ins Command to a Toolbar or Menu.
-
7/31/2019 adxvcl
53/77
Add-in Expr ess VCLYour First Microsoft Outlook COM Add-in
page 53
Step #14 Debugging the COM Add-in
To debug your add-in, just indicate the add-in host application in the Host Application field in the Project
Options window.
Step #15 Deploying the COM Add-in
Make sure your setup project registers the add-in DLL. Say, in Inno Setup projects you use the 'regserver'
command.
-
7/31/2019 adxvcl
54/77
Add-in Expr ess VCLYour Fir st Excel RTD Ser ver
page 54
Your First Excel RTD Server
Step #1 Creating a New Add-in Expr ess RTD Server Project
Add-in Express adds the Add-in Express RTD Server project template to the New Item dialog of Borland
Delphi for Microsoft Windows.
When you select the template and click OK, the RTD Server Project wizard starts. In the wizard windows,
you choose the project options.
-
7/31/2019 adxvcl
55/77
Add-in Expr ess VCLYour Fir st Excel RTD Ser ver
page 55
The Add-in Express Project Wizard creates and opens the RTD Server project in the IDE.
The RTD server project includes the following items:
-
7/31/2019 adxvcl
56/77
Add-in Expr ess VCLYour Fir st Excel RTD Ser ver
page 56
The project source files (ProjectName.*);
The type library files: binary (ProjectName.tlb) and Object Pascal
unit (ProjectName_TLB.pas);
The RTD server module (ProjectName_IMPL.pas and
ProjectName_IMPL.dfm) discussed in the following step.
Step #2 Add-i n Express RTD Server Module
The RTD server module (MyRtdServer1_IMPL.pas and MyRtdServer1_IMPL.dfm) is the core part of the
RTD Server project. The module is a container for TadxRTDTopic components.
The code of MyRtdServer1_IMPL.pas is as follows:
unit MyRtdServer1_IMPL;
interface
uses
SysUtils, Classes, ComServ, MyRtdServer1_TLB, adxRTDServ;
type
TcoMyRtdServer1 = class(TadxRTDServer, IcoMyRtdServer1);
TRTDServerModule = class(TadxXLRTDServerModule)
private
protected
public
end;
implementation
{$R *.dfm}
initialization
TadxRTDFactory.Create(ComServer, TcoMyRtdServer1, CLASS_coMyRtdServer1,
TRTDServerModule);
end.
-
7/31/2019 adxvcl
57/77
Add-in Expr ess VCLYour Fir st Excel RTD Ser ver
page 57
Step #3 Add-in Express RTD Server Designer
The module designer allows setting RTD Server properties and adding components to the module.
You set the properties of your RTD server module in the Object
Inspector window (see RTD Servers).
The only Add-in Express component available for the module is
the TadxRTDTopic component (s