III
TC I II III IV V

ACT!TM Scripting Support

with and

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


Text Box: 1

 

CHAPTER

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

Conventions used in this manual

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.

Parameter types

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
bParameter

Boolean

vParameter

Variant (VARIANT in Visual C++)

System requirements

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

Overview

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.


Text Box: 2

 

CHAPTER

Creating Scripts

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.

Adding a VBScript script file to ACT!

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.

Using ACT! Scripting Support with the OLE Application Object

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
Sub ShowMessageBox(ByVal strMsg)

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
'This script demonstrates the calculation of User fields. It adds the values 'in the User1 and User2 fields and places the result in the User3 field.

'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

 

 

Text Box: 3

 

CHAPTER

Event Notification Support

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.

Registering the custom control

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.

Using event control in Visual Basic

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.

Using event control in Visual C++

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.

Event control methods

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

Register Method

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

UnRegister Method

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

IsActRunning Method

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.


Event control events

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.

OnContactAdd Event

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

OnContactChange Event

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

OnContactDelete Event

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

OnContactListChange Event

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

OnContactLookupChange Event

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

OnContactPosChange Event

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

OnDatabaseClose Event

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

OnDatabaseOpen Event

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

OnGroupAdd Event

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

OnGroupChange Event

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

OnGroupDelete Event

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

OnGroupListChange Event

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

OnGroupPosChange Event

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

OnActUserWantsToClose Event

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