|
III TC I II III IV V |
ACT!TM Scripting Support
|
CONTENTS
Section III ACT!
Scripting Support
Chapter 1 Getting
Started with ACT! TM Scripting Support.......................................... 427
Conventions used in this manual......................................................................... 427
Parameter types................................................................................................ 428
System requirements......................................................................................... 428
Overview........................................................................................................... 429
Chapter 2 Creating
Scripts............................................................................................ 431
Adding a VBScript script file to ACT!................................................................... 431
Using ACT! Scripting Support with the OLE Application Object.............................. 432
Chapter 3 Event
Notification Support........................................................................... 433
Registering the custom control............................................................................ 433
Using event control in Visual Basic...................................................................... 433
Using event control in Visual C++........................................................................ 434
Event control methods........................................................................................ 434
Register Method.......................................................................................... 434
UnRegister Method...................................................................................... 435
IsActRunning Method................................................................................... 435
Event control events........................................................................................... 436
OnContactAdd Event.................................................................................... 437
OnContactChange Event.............................................................................. 437
OnContactDelete Event................................................................................ 437
OnContactListChange Event......................................................................... 438
OnContactLookupChange Event.................................................................... 438
OnContactPosChange Event......................................................................... 438
OnDatabaseClose Event............................................................................... 439
OnDatabaseOpen Event............................................................................... 439
OnGroupAdd Event...................................................................................... 439
OnGroupChange Event................................................................................. 440
OnGroupDelete Event................................................................................... 440
OnGroupListChange Event............................................................................ 440
OnGroupPosChange Event........................................................................... 441
OnActUserWantsToClose Event.................................................................... 441
Getting Started with ACT! TM Scripting Support
This section consists of three chapters that describe the ACT!TM Scripting Support component of the ACT! Software Development Kit (SDK). This component consists of this set of instructions on how to create scripts that can be notified of events in the ACT! application.
This document assumes that you are familiar with and using the following:
· ACT! 4.0 or later for Windows
· Microsoft Windows 95, Windows 98, Windows 2000, or Windows NT 4.0
To help you easily identify information, the following conventions are used:
bold Command names, function names, events, methods, and other text you need to type are shown in bold.
ALL CAPITALS File names and messages are shown in all CAPITAL letters.
Courier Example code is shown in a monospaced Courier font. Comments in the code are preceded by an apostrophe (' Comment). If a line of code does not fit on a single line of the page, the remaining code is indented on the next line. Code examples are not case sensitive.
italic Parameters, return variables, data structure names, and text that represent the type of text to be entered rather than a literal series of characters are shown in italic.
[brackets] Optional items in syntax statements are enclosed in brackets ([ ]). For example, [password] indicates that a password can be used with the command, but is not required. In commands, include the information within the brackets without the brackets.
Parameter1|Parameter2 Parameters are separated by a vertical bar (|) to indicate a mandatory choice between two items. Only one of the items can be specified.
... Items that you can repeat are indicated by an ellipsis (… ) For example, devicename [...] indicates that you can optionally specify more than one device, separating the device names with a space.
The following table lists the data types that are referenced in this section. Parameter names follow Hungarian notation, beginning with a lowercase letter or letters that indicate the data type.
|
Parameter syntax |
Data type |
|
date |
Date and time in Short Date style and Time style from Windows Regional Settings (DATE in Visual C++) |
|
fParameter |
Float (Single in Visual C++) |
|
iParameter |
Short integer |
|
lParameter |
Long integer |
|
szString |
String, terminated by a null character (BSTR in Visual C++) |
|
True|False or |
Boolean |
|
vParameter |
Variant (VARIANT in Visual C++) |
ACT! scripting support requires:
· ACT! 4.0 or later for Windows
· Microsoft Windows 95, Windows 98, Windows 2000, or Windows NT 4.0
· Microsoft Internet Explorer version 3.0 or later
Third-party applications developed in any language with container support for ActiveX controls (such as VBScript, Visual Basic, and Visual C++) can receive immediate notification of ACT! events and act on them. The ACT! events include opening and closing an ACT! database as well as changing records in the Contact and Group views and the Contact and Group lists.
You can use all objects, methods, and properties in the ACT! OLE Application Object in a script; however, the objects, methods, and properties in the ACT! OLE Database Object are not available for use in scripts. For additional information about using the features of the Application Object, see “Using ACT! Scripting Support with the OLE Application Object” on page 10.
CHAPTER
ACT! 4.0 or later supports execution of VBScripts inside the ACT! application through the ACT! toolbar. You can use all objects, methods, and properties of the ACT! OLE Application Object inside the environment of VBScripts when executing inside ACT! This will help developers who want to use the scripting in conjunction with the OLE Application Object. (You cannot use the ACT! OLE Database Object in a script.) The script support is provided through Microsoft VBScript Engine. The capabilities and limitations of using VBScript inside the ACT! application depends upon the version of the VBScript engine installed on the computer running ACT!
Microsoft Internet Explorer 3.0.2 or later includes the required VBScript scripting engine. If Internet Explorer version 3.0.2 or later is installed, a separate installation of the VBScript scripting engine is not required. If you encounter an error trying to execute a script file, make sure you have the correct version of VBScript scripting engine. The latest version of the VBScript scripting engine is available at: http://msdn.microsoft.com/scripting/default.htm.
The following steps describe how to add a VBScript file to ACT!
1 Create a text file containing your VBScript code, named with an extension of .VBS, such as MYFILE.VBS. ACT! requires the extension name of .VBS to recognize the file as a VBScript file.
2 Using toolbar customization feature of ACT!, add a new command and specify the name of the VBScript file on the command line. Then add a button to the toolbar and associate the newly created command with that button. If you are not familiar with toolbar customization features of ACT!, see Chapter 17 of the ACT! 2000 User’s Guide for more information.
3 After you have completed adding the button, it will appear on the ACT! toolbar. Click the added button to execute you script.
You can use all ACT! OLE Application Object objects, methods, and properties in a script. To use the objects, methods, and properties of the ACT! Application Object, include the word “Application” in the script. For example, you can include the following in the script to create the Views object and a Contact view object:
objViews = Application.Views
objViews.Create(1,”CV”)
Note: Additional examples of Scripting Support are available in ACT! SDK samples in the Event_Script Samples\Scripts folder.
Following is an example script that shows how the ACT! OLE Application object can be used inside a VBScript added to the ACT! application.
|
'VB Msgbox strMsg End Sub 'Display current ACT! caption to user ShowMessageBox Application.Caption 'Now change the ACT! application caption Application.Caption = "My Copy of ACT!" 'Now display the new ACT! caption to the user ShowMessageBox Application.Caption |
The following sample script illustrates how to perform
calculations on field values. It adds the values in two User fields and places
the result in a third User field.
|
'VB 'It assumes that User1, User2, and User3 are all Currency fields. 'If either the User1 or the User2 field is blank, it is assumed to be 0. 'You can use a similar script to perform any other calculation. Set objViews = Application.Views Set objContactView = objViews.Create(1, "CV") objContactView.SetActiveTab "User Fields" 'Assuming that User1, User2 and User 3 are Currency fields 'If User1 or User2 is blank then calculate as if 0 Val1 =objContactView.GetField(50) If Val1 = "" then Val1 = 0 Val2 = objContactView.GetField(51) If Val2 = "" then Val2 = 0 'Calculate User1 + User2 Val3 = CCur(Val1) + CCur(Val2) 'Set User3 as the result objContactView.SetField 52, Val3
|
CHAPTER
Event notification support enables users to get notification of events from the ACT! application. This chapter contains a list of the supported events. Event notification support is provided through ActiveX controls.
Applications developed in any language with container support for ActiveX controls can receive notification of a variety of ACT! events. An ActiveX control is a software component that incorporates ActiveX technology. For additional information on ActiveX controls, visit http://www.download.com/PC/Activex/ or www.microsoft.com.
In ACT! 2000 or later, when you delete a lookup of contacts or groups, or multiple contacts from the ContactList view, import contacts or groups into the current database, or perform a sort, event notifications are turned off until the process completes. Then the ContactListChange and GroupListChange events are called, which return updated counts of the contacts and groups.
When ACT! for Windows is installed, the OLE custom control ACTEVENT.OCX is automatically installed and registered in the folder containing the ACT! executable file. If ACTEVENT.OCX is not registered, you can register it by executing ACTREG.EXE. ACTREG.EXE is automatically installed in the folder containing the ACT! executable file.
To get notification of ACT! events in a Visual Basic application:
1 Start Visual Basic.
2 Select Custom Controls from the Tools menu (Visual Basic 4) or Components from the Project menu (Visual Basic 5).
3
Click Browse and select ACTEVENT.OCX in the ACT
folder.
The ACT! icon is added to the Visual Basic Toolbox.
4 Drag the ACT! icon onto the Visual Basic Form.
By default, the name is ActEvent1. The object has no visible properties.
To get notification of ACT! events in a C++ application:
1 Start C++ and create a new MFC project.
2 In the Dialog Editor, select Insert OLE Control.
3 In the Insert OLE Control dialog box, select ActEvent Control and click OK.
A control appears with no visible properties.
To include a notification of an ACT! event:
In the ClassWizard, select an ACT! event in the Messages scroll list and click Add Function.
The following methods are included for setting up event control to begin or end notification of ACT! events or to verify that ACT! is running. You must call Register to receive notification of ACT! events. Use UnRegister when you no longer want notification of events and IsActRunning to verify that ACT! is still running.
Methods
|
Method Name |
Parameter(s) |
Parameter Type(s) |
Return Type |
|
Register |
lparam |
Long Integer |
Long Integer |
|
UnRegister |
None |
¾ |
Long Integer |
|
IsActRunning |
None |
¾ |
Boolean |
Description Enables the reception of ACT! event notification. This method is typically called at the beginning of the program to enable the reception of messages. ACT! should be running when you call this method.
Syntax object.Register(lparam)
Parameters lparam A long integer. This parameter is ignored.
Return type Long Integer
Comments This
method returns one of the following values:
> 0 Any positive integer
indicates that ACT! is running.
0 ACT!
is not running.
-1 The
event is already registered. An event cannot be registered more than once.
<-1 An undefined error occurred.
Example Dim i as long
i = ActEvent1.Register(0)
If i < 1 Then
If ActEvent1.IsActRunning = False Then
MsgBox "Please bring up ACT! and start again."
Else
MsgBox "Problem registering ACT! Event."
Please run actreg.exe and try again!"
End If
End If
Description Disables the receipt of ACT! event notifications. Call this method when you no longer want to receive notification of ACT! events.
Syntax object.UnRegister
Return type Long Integer
Example ActEvent1.UnRegister
Description Returns True if ACT! is running and False if ACT! is not running. Call this method to verify that the user has not exited from ACT!
Syntax object.IsActRunning
Return type Boolean
Example See Register.
The following table lists the events supported.
|
Event |
Called when the user: |
|
OnContactAdd |
Adds a new contact or saves the record for the current contact. Returns a null string if the user adds a contact or the Unique ID of the current contact when the user saves a new contact. |
|
OnContactChange |
Makes any change to the record for the current contact. Returns the Unique ID of the current contact. |
|
OnContactDelete |
Deletes a contact. Returns the Unique ID of the deleted contact. |
|
OnContactListChange |
Makes any change in the number of contacts in the Contact List. Changes to the number of contacts in the Contact List include changing the lookup, adding a contact, and deleting a contact. Returns an updated count of the contacts in the Contact List. |
|
OnContactLookupChange |
Makes a change to the current lookup, including adding or deleting a contact or performing a different lookup. |
|
OnContactPosChange |
Selects a different contact in the Contact view. Returns the Unique ID of the selected contact. |
|
OnDatabaseClose |
Closes the database. |
|
OnDatabaseOpen |
Opens a database. Returns the name of the database that is currently open. |
|
OnGroupAdd |
Adds a new group or saves the current group. Returns a null string if the user adds a group or the Unique ID of the current group when the user saves a new group. |
|
OnGroupChange |
Makes any change to the current group. Returns the Unique ID of the current group. |
|
OnGroupDelete |
Deletes a group. Returns the Unique ID of the group that was deleted. |
|
OnGroupListChange |
Changes the number of contacts in a group (such as adding or deleting a contact) or displays the Group view. Returns an updated count of the contacts in the group. |
|
OnGroupPosChange |
Selects a different group. Returns the Unique ID of the active group. |
|
OnActUserWantsToClose |
Selects Close from the File menu or clicks the Close box in the ACT! window. |
Description This event is called when the user adds a new contact or saves the record for the current contact. Returns a null string if the user adds a contact or the Unique ID of the current contact when the user saves a new contact. In ACT! 2000 or later, this event is turned off during the import of contacts into the current database.
Syntax OnContactAdd(szUniqueID)
Parameters szUniqueID A string with either of the
following values:
Null User is adding a new
contact.
Unique ID User has saved a new contact.
Example Private
Sub ActEvent1_OnContactAdd(ByVal lpszUniqueID as string)
'Initially when ContactAdd is done, a blank record is generated and
'at that time Unique ID is ""
'After Save the Unique ID gets a value.
If lpszUniqueID <> "" Then
MsgBox "Contact with Unique ID: " & lpszUniqueID & " added."
End if
End Sub
Description This event is called when the user makes any change to the record for the current contact. Returns the Unique ID of the current contact.
Syntax OnContactChange(szUniqueID)
Parameters szUniqueID A string containing the Unique ID of the current contact.
Example Private
Sub ActEvent1_OnContactChange(ByVal lpszUniqueID as string)
MsgBox "Contact with Unique ID: " & lpszUniqueID & "has changed."
End Sub
Description This event is called when the user deletes a contact. Returns the Unique ID of the deleted contact. In ACT! 2000 or later, this event is turned off while deleting a lookup of contacts or while deleting multiple contacts from the Contact List view.
Syntax OnContactDelete(szUniqueID)
Parameters szUniqueID A string containing the Unique ID of the deleted contact.
Example Private
Sub ActEvent1_OnContactDelete(ByVal lpszUniqueID as string)
MsgBox "Contact with Unique ID: " & lpszUniqueID & "deleted."
End Sub
Description This event is called when the user makes any change in the number of contacts in the Contact List. Changes to the number of contacts in the Contact List include changing the lookup, adding a contact, and deleting a contact. Returns an updated count of the contacts in the Contact List.
Syntax OnContactListChange(lCount)
Parameters lCount A long integer indicating the number of contacts now in the Contact List.
Example Private Sub ActEvent1_OnContactListChange(ByVal nCount as long)
MsgBox "The Contact List has changed. The New Contact Count is" & nCount
End Sub
Description This event is called when the user makes a change to the current lookup, including adding or deleting a contact or performing a different lookup. In ACT! 2000 or later, this event is not called while importing contacts into the database, while deleting a lookup of contacts, or while deleting multiple contacts from the Contact List view.
Syntax OnContactLookupChange
Description This event is called when the user selects a different contact in the Contact view. Returns the Unique ID of the selected contact.
Syntax OnContactPosChange(szUniqueID)
Parameters szUniqueID A string containing the Unique ID of the currently active contact.
Example Private
Sub ActEvent1_OnContactPosChange(ByVal lpszUniqueID as string)
MsgBox "The Current Contact is now: " & lpszUniqueID
End Sub
Description This event is called when the user closes the database.
Syntax OnDatabaseClose
Example Private
Sub ActEvent1_OnDatabaseClose()
MsgBox "The Database has closed."
End Sub
Description This event is called when the user opens a database. Returns the name of the database that is currently open.
Syntax OnDatabaseOpen(szDBName)
Parameters szDBName A string containing the name of the database that is now open.
Example Private Sub ActEvent1_OnDatabaseOpen(ByVal lpszDBName as string)
MsgBox lpszDBName & " database open."
End Sub
Description This event is called when the user adds a new group or saves the current group. Returns a null string if the user adds a group or the Unique ID of the current group when the user saves a new group. In ACT! 2000 or later, this event is not called while groups are being imported.
Syntax OnGroupAdd(szUniqueID)
Parameters szUniqueID A string with either of the
following values:
Null User is adding a new
contact.
Unique ID User has saved a new contact.
Example Private
Sub ActEvent1_OnGroupAdd(ByVal lpszUniqueID as string)
'Initially when GroupAdd is done, a blank record is generated and
'at that time Unique ID is ""
'After Save the Unique ID gets a value.
If lpszUniqueID <> "" Then
MsgBox "Group with Unique ID: " & lpszUniqueID & " added."
End Sub
Description This event is called when the user makes any change to the current group. Returns the Unique ID of the current group.
Syntax OnGroupChange(szUniqueID)
Parameters szUniqueID A string containing the Unique ID of the current group.
Examples Private Sub ActEvent1_OnGroupChange(ByVal lpszUniqueID as string)
If lpszUniqueID <> "" Then
MsgBox "Group with Unique ID: " & lpszUniqueID & " changed."
End if
End Sub
Description This event is called when the user deletes a group. Returns the Unique ID of the group that was deleted. In ACT! 2000 or later, this event is not called during the deletion of a group lookup.
Syntax OnGroupDelete(szUniqueID)
Parameters szUniqueID A string containing the Unique ID of the deleted group.
Example Private Sub ActEvent1_OnGroupDelete(ByVal lpszUniqueID as string)
If lpszUniqueID <> "" Then
MsgBox "Group with Unique ID: " & lpszUniqueID & " deleted."
End if
End Sub
Description This event is called when the user adds or deletes a group or changes the groups lookup. Returns an updated count of the groups in the Groups view.
Syntax OnGroupListChange(lCount)
Parameters lCount A long integer indicating the number of contacts now in the group.
Example Private
Sub ActEvent1_OnGroupListChange(ByVal nCount as long)
MsgBox "The Group List has changed. The New Group Count is " & nCount
End
Description This event is called when the user selects a different group. Returns the Unique ID of the active group.
Syntax OnGroupPosChange(szUniqueID)
Parameters szUniqueID A string containing the Unique ID of the active group.
Example Private Sub ActEvent1_OnGroupPosChange(ByVal lpszUniqueID
as string)
MsgBox "The current group is now: " & lpszUniqueID
End Sub
Description This event is called when the user selects Close from the File menu or clicks the Close box in the ACT! window.
Syntax OnActUserWantsToClose(bIsFinal)
Parameter bIsFinal A Boolean indicating whether ACT! is closed. A True value indicates that ACT! is closed; a False value indicates that it is not closed.
Comments If
ACT! is being controlled by the Application Object, when the user closes ACT!,
this event is generated twice: Once before the application actually closes (bIsFinal is False) and then again when ACT! closes (bIsFinal is True).
Example Private Sub ActEvent1_OnActUserWantsToClose(ByVal bIsFinal
As Boolean)
If bIsFinal = False Then
'ACT! is given an indication of user wanting to close.
'It is a good time to utilize the Application Object.
MsgBox "ACT! user wants to close. Uninitializing Application Object "
& vbCrLf & "Closing ACT!"
'If you are using the Application object, uninitialize it now.
'It is a good time to uninitialize any other objects you may have
'references to.
Set objApp = Nothing
Else
ActEvent1.UnRegister
End
End If
End Sub
ACT! Software Development Kit (SDK)
Technical
Reference Guide
ACT! Scripting Support section
The software described in this book is furnished
under a license agreement and may be used only in accordance with the terms of
the agreement.
Copyright Notice
Portions of this publication copyright 2000 Interact Commerce Corporation. Portions of this publication
copyright 1993 ‑ 2000 Symantec Corporation under
exclusive license to Interact Commerce Corporation.
All Rights Reserved.
Released: 6/2000 for ACT! 2000
This document may not, in whole or in part, be
copied, photocopied, reproduced, translated, or reduced to any electronic
medium or machine-readable form without prior consent in writing from Interact
Commerce Corporation, 8800 N. Gainey Center Dr. #200, Scottsdale, AZ 85258.
ALL EXAMPLES WITH NAMES, COMPANY NAMES, OR
COMPANIES THAT APPEAR IN THIS MANUAL ARE IMAGINARY AND DO NOT REFER TO, OR
PORTRAY, IN NAME OR SUBSTANCE, ANY ACTUAL NAMES, COMPANIES, ENTITIES, OR
INSTITUTIONS. ANY RESEMBLANCE TO ANY REAL PERSON, COMPANY, ENTITY, OR
INSTITUTION IS PURELY COINCIDENTAL.
Every effort has been made to ensure the
accuracy of this manual. However, Interact Commerce makes no warranties with
respect to this documentation and disclaims any implied warranties of
merchantability and fitness for a particular purpose. Interact Commerce shall
not be liable for any errors or for incidental or consequential damages in
connection with the furnishing, performance, or use of this manual or the
examples herein. The information in this document is subject to change without
notice.
Trademarks
ACT! is a registered trademark and SideACT! is a
trademark under exclusive license to Interact Commerce Corporation by their
owner, Symantec Corporation, in the United States and other countries. Interact
Commerce Corporation and not Symantec Corporation has produced this publication
and is responsible for the contents hereof. Symantec and WinFax are U.S.
registered trademarks of Symantec Corporation. WinFax PRO is a trademark of
Symantec Corporation. Microsoft, MS, Windows, Windows CE, Windows NT, Word,
Schedule+, ActiveX, FoxPro, Visual Basic, and Visual C++ are either registered
trademarks or trademarks of Microsoft Corporation in the U.S. and/or other
countries. Dale Carnegie Training is a registered trademark of Dale Carnegie
and Associates, Inc. ECCO is a trademark of NetManage Inc. ExpensAble is a
registered trademark of Managemark, Inc. Palm is a trademark of Palm, Inc.
GoldMine is a trademark of Goldmine Software Corp. Janna Contact is the
exclusive property of Janna Systems Inc. Maximizer is a registered trademark of
Modatech Systems Inc. Lotus Organizer is a trademark of Lotus Development
Corporation. Quicken is a registered trademark of Intuit, Inc. Sidekick is a
trademark of Starfish Software. Sharkware is a trademark of CogniTech
Corporation. Tracker is a trademark of Softcode Pty Ltd. Yahoo! is a registered
trademark of Yahoo! Inc. WordPerfect is a registered trademark of Novell, Inc.
CompuServe is a registered trademark of CompuServe, Inc., and its affiliates.
cc:Mail and cc:Mail Mobile are trademarks of cc:Mail, Inc., a wholly owned
subsidiary of Lotus Development Corporation. Day Runner is a registered
trademark of Day Runner, Inc. Day-Timer is a registered trademark of
Day-Timers, Inc. Netscape is a trademark of Netscape Communications
Corporation. Portions of ACT! are Copyright 1995 by Streetwise Software. All
rights reserved.
Other product names mentioned in this
manual may be trademarks or registered trademarks of their respective companies
and are the sole property of their respective manufacturers.
Printed in the United States of America.
10 9 8 7 6 5
4 3 2 1
