Updated 17/8/04
MoneyWorks Gold 4.1.1 provides extensive new scripting capabilities to allow you to customise data entry behaviour.
You can write a script which MoneyWorks will send messages to every time something happens with the user interface (open window, validate window, validate field, exit field etc). This script should be named "Helper.scpt" and goes into the Scripts folder of MoneyWorks Custom or Standard plug-ins.
On Mac, the Helper.scpt script must be written in Applescript (and the .scpt extension implies that it is compiled);
On Windows, the Helper.scpt file should actually be a one-line text file containing nothing but the name of a COM object that is registered in the registry. The COM object can be implemented in VBScript or similar using a .WSC file or you can go the whole hog and implement it as a DLL with an IDispatch interface. If this is gobbledegook, don't worry—wait for the code samples, which you can just modify to do what you want.
The following messages will be sent to the Helper script:
Load - when script is loaded
Unload - when script is unloaded
OpenedDocument - when the document opens
AllowCloseDocument - when the document is about to close. You can prevent it from closing by returning false.
ClosedDocument - after the document has closed
AllowSaveDocument - just before saving the document. You must return true to allow the document to be closed. You must return true to allow saving to go ahead. You can prevent it from saving by returning false.
SavedDocument - after the document has been saved
UserLoggedIn - after a user has logged in (you won't get this if the document is not password protected)
UserLoggingOut - just before a user logs out.
WantMessages - when window opens
Before - when window opens or loads a new record
Validate - when window is about to be accepted
Cancel - when window is cancelled
After - when window is accepted
ValidateField - when field is about to be exited
ValidateCell - when detail line field is about to be exited
ExitedField - when field has been exited
ExitedCell - when detail field has been exited
And by "messages", I mean that your script implements functions with these exact names and MoneyWorks calls them.
For more details and examples of use, see the sample scripts.
Of course, having your script be notified of events like exiting a field is only useful if you can get and set field values. To this end MoneyWorks 4.1.1 now has enhanced scripting access to the user interface. You can get and set field values in dialog boxes, and add and delete detail lines.
MoneyWorks 4.1.1 adds the following classes and verbs to the Applescript dictionary. In keeping with standard Applescript terminology, the detail line entry list in a transaction window is referred to as a "table", containing "rows". Each row in turn contains "cells". You can make new rows and delete rows. You can get and set contents of cells and fields. The front window (the one you will usually be concerned with is always window 1 although you can also refer to windows by name. Likewise the detail line entry table is always table 1, but you can refer to it by it's name which is the same as the selected tab (i.e. "Service" or "Product" etc).
Class application: An application program
Plural form:
applications
Elements:
window by numeric index, by name
Properties:
properties record -- property that allows getting and setting of multiple properties
name string [r/o] -- the name of the application
frontmost boolean [r/o] -- Is this the frontmost application?
version string [r/o] -- the version of the application
Class cell:
Plural form:
cells
Properties:
name string -- the name of the cell column
index integer [r/o] -- the index of the cell column
contents text -- the contents of the cell
enclosing_row row [r/o] -- reference to the enclosing row
enclosing_table table [r/o] -- reference to the enclosing table
enclosing_window window [r/o] -- reference to the enclosing window
Class row:
Plural form:
rows
Elements:
cell by numeric index, by name
Properties:
index integer [r/o] -- the number of this row
enclosing_table table [r/o] -- reference to the enclosing table
enclosing_window window [r/o] -- reference to the enclosing window
Class table:
Plural form:
tables
Elements:
row by numeric index, by name
Properties:
name string -- the name of the table
index integer [r/o] -- the number of this row
enclosing_window window [r/o] -- reference to the enclosing window
Class window:
Plural form:
windows
Elements:
field by numeric index, by name
table by numeric index, by name
Properties:
properties record -- property that allows getting and setting of multiple properties
name string -- the name of the window
index integer [r/o] -- the number of this window
ident integer [r/o]
-- window class identifier. This is a number that identifies the kind of
MoneyWorks window you are dealing with. The transaction entry window has ident
of 20745. If you want to find out a window's ident, just run this script:
tell application
"MoneyWorks Debug" to display dialog (get ident of front window) as
text
bounds bounding rectangle -- the boundary rectangle for the window
closeable boolean [r/o] -- Does the window have a close box?
titled boolean [r/o] -- Does the window have a title bar?
floating boolean [r/o] -- Does the window float?
modal boolean [r/o] -- Is the window modal?
resizable boolean [r/o] -- Is the window resizable?
visible boolean -- Is the window visible?
frontmost boolean -- Is this the frontmost window?
count: Return the number of elements of a particular class within an object
count reference -- the object whose elements are to be counted
each type class -- the class of the elements to be counted. Keyword 'each' is optional in AppleScript
Result: integer -- the number of elements
example: count fields of window 1
delete: Delete an element from an object
delete reference -- the element to delete
example: delete row 3 of table 1 of window 1
exists: Verify if an object exists
exists reference -- the object in question
Result: boolean -- true if it exists, false if not
get:
get reference
[as a list of type class]
Result: anything
example: get contents of field named "e_desc" of window 1
make: Make a new element
make
new type class -- the class of the new element. Must be ‘row’. Keyword 'new' is optional in AppleScript
at location reference -- reference to table in which to make new row
Result: reference -- to the new object(s)
example: make new row at table named "Service" of window 1
set:
set reference
to anything
example: set contents of field named "e_desc" of front window to "blah"
Class field:
Plural form:
fields
Properties:
index integer [r/o] -- the number of this field
name string [r/o] -- the name of the field, if any
contents text
enclosing_window window [r/o] -- reference to the enclosing window
On Windows, the following functions have been added to the COM (VB) IDispatch interface. The dialogHandle and listHandle parameters get passed to your attached script by MoneyWorks. Since this is the only way to get a dialogHandle, you can only use these functions from within an attached script, not from a standalone script.
BSTR GetField([in] LONG dialogHandle, [in] LONG fieldNumber)
Get a field value from a dialog box. The dialog box handle is passed to you as a parameter to your script function.
void SetField([in] LONG dialogHandle, [in] LONG fieldNumber, [in] BSTR value)
Set a field value in a dialog box
BSTR GetListField([in] LONG listHandle, [in] LONG lineNumber, [in] LONG columnNumber)
Get a detail field value in a dialog box. lineNumber and columnNumber start at 1
void SetListField([in] LONG listHandle, [in] LONG lineNumber, [in] LONG columnNumber, [in] BSTR value)
Set a detail field value in a dialog box.
void AddListLine([in] LONG listHandle);
Add a line to a list
void DeleteListLine([in] LONG listHandle, [in] LONG line);
Delete a line from a list
LONG GetListHandle([in] LONG dialogHandle, BSTR listName);
Get a reference to a list in a dialog box. The list name should match the selected tab in the dialog box. e.g. "Service", "Product" etc.
LONG GetDialogHandle([in] LONG listhandle);
Get a reference to dialog box that a list belongs to
LONG GetListLineCount([in] LONG listHandle);
Get number of lines in list. listHandle is either passed to your attached script by MoneyWorks or you can convert a dialog handle to a list handle using GetListHandle
LONG GetFieldNumber([in] LONG dialogHandle, BSTR fieldName);
Get the index of a field whose
symbolic name you know. Thus to get the contents of the transaction description
field you would use:
mw.GetField(dialog, mw.GetFieldNumber(dialog, "e_desc"))
ImportantField numbers may change between MoneyWorks versions. You must get the field number at runtime using the symbolic name.
BSTR GetFieldName([in] LONG dialogHandle, LONG fieldNumber);
Get the symbolic name of a field
LONG GetFieldCount([in] LONG dialogHandle);
Get number of fields in a window. Use this if you need to iterate over fields (maybe to get all their names)
The Mac code sample is named Helper.scpt. Chuck it in the Scripts folder. This contains declarations for all messages you will get. The sample just has a "say" statement that will tell you each message as it is called. You can comment out or delete the messages you don't care about.
The Windows code sample consists of Helper.scpt (which contains nothing but the text "MoneyWorks.Helper"), plus the actual script which is named Helper.wsc. You need to place these in the Scripts folder, and, having done so, you need to register the Helper.wsc script. Do this by right-clicking on it and choosing Register from the contextual menu. It will not work until you do this. The reason that there is an indirection file (Helper.scpt) is so that you can have different Helper.scpt files in different Custom Plug-Ins folders that point to different registered .wsc files. Without this indirection you could not have different scripts for different documents.
You can double-click Helper.wsc to edit it in Notepad. The file is XML containing declarations of the script functions that it implements. Don't touch this stuff. The only thing that you might change here is the progid, which you will note matches the contents of Helper.scpt. To have different scripts on the same machine you need different progids. If you do this, each unique progid also needs a unique classid. You can use the Windows Script Component Wizard to create a new .wsc from scratch but probably easier to edit the sample one. You'll need the guidgen.exe tool to make a new classid, although it is probably safe to just change the last digit of the one that is in there.
Other than that, the only bit you care about is inside the <![CDATA[ ... ]]> section. This is text containing Vbscript code that actually implements the script. In most of these I have just put some script code that uses the built-in Wshell object to log to the system log. As usual, to call back into MoneyWorks you need to CreateObject("MoneyWorks.Application").
You can look at the results of the logging in Start -> Control Panels-> Administrative tools -> Event Viewer -> Application Log (in which you have to hit F5 to see new log entries)
Q. How do I know what kind of transaction it is?
A. Look at the window name.
Q. I know that in AppleScript I can get the window name using get the name of the front window. How do I do it on Windows?
A. Use the pseudo field number: -1.
GetField(dialogHandle, -1).
