Contents of this file:

What is FILEDLGS.DLL?
Installing FILEDLGS.DLL on your System
Using FILEDLGS.DLL in your ScriptTools scripts

What is FILEDLGS.DLL?
--------------------

FILEDLGS.DLL is a dynamic link library specially written to extend the
ScriptTools(TM) language supplied with Central Point PC Tools for Windows.

While ScriptTools has a very powerful script language, it lacks any easy way
of putting up a dialog to get a user-chosen file name.

FILEDLGS.DLL has been written to plug this gap. It gives you the ability to
easily get a filename from the user (via the Windows 3.1 common Open and Save
As dialogs), and then to use that filename in your script (to pass to an
application on startup, for instance).

Installing FILEDLGS.DLL on your System:
--------------------------------------

To install FILEDLGS.DLL, simply copy it into your PC Tools for Windows
directory (this is usually named c:\cps or something similar).

Using FILEDLGS.DLL in your ScriptTools scripts:
----------------------------------------------

FILEDLGS.DLL has three functions, each of which can be called from your
scripts using the ScriptTools DLLCall() function:

FileOpen - prompts for a file name via the common Open dialog box,
FileSaveAs - prompts for a file name via the common Save As dialog box,
GetFileDir - returns the fully-qualified drive and directory of any given
file.

These are described in detail in the following.

(1) FileOpen
--------

Purpose: To prompt for a file name via the File Open common dialog.
Syntax: DLLCall("filedlgs.dll", "FileOpen", , ,
, )

Description:
Put up the File Open common dialog and ask the user to choose a
file name (either an existing or new one).

FileOpen returns 0 if the user chooses the Cancel button, or 1
if a file name is chosen and the OK button pressed.

Before calling this function, all strings must be specified and
non-empty. is the string to display as the caption
of the dialog box; is a the descriptive filter name to
appear in the dialog's 'List files of type' control; ; is
the DOS wildcard filter; and is the default directory
and/or file to be selected when first displaying the dialog.

On return from the function, contains the fully-
qualified file name chosen by the user.

Example:
FName := "c:\cps\data"
If DLLCall("filedlgs.dll", "FileOpen", "Choose a script", "Scripts (*.run)",
"*.run", FName$) = 1
Then
... process file returned in FName$ ...
Endif

(2) FileSaveAs
----------

Purpose: To prompt for a file name via the File Save as common dialog.
Syntax: DLLCall("filedlgs.dll", "FileSaveAs", , ,
)

Description:
Put up the File Open common dialog and ask the user to choose a
file name (either an existing or new one).

FileOpen returns 0 if the user chooses the Cancel button, or 1
if a file name is chosen and the OK button pressed.

Before calling this function, all strings must be specified and
non-empty. is the string to display as the caption
of the dialog box; is a the descriptive filter name to
appear in the dialog's 'List files of type' control; ; is
the DOS wildcard filter; and is the default directory
and/or file to be selected when first displaying the dialog.

On return from the function, contains the fully-
qualified file name chosen by the user.

Example:
FName := "c:\"
If DLLCall("filedlgs.dll", "FileSaveAs", "Choose any file",
"All files (*.*)", "*.*", FName$) = 1
Then
... process file returned in FName$ ...
Endif

(3) GetFileDir
----------

Purpose: To obtain the fully-qualified drive and directory of a given file.
Syntax: DLLCall("filedlgs.dll", "GetFileDir", , )

Description:
Return the fully-qualified drive and directory of a given file
(for example, that returned by FileOpen or FileSaveAs) in a form
suitable for use by the ScriptTools ChangeDir() function.

GetFileDir returns 1 if successful, and 0 if not.

Before calling this function, must be set to the file
name whose drive and directory is to be determined (this file name
may contain relative a path, such as "..\temp"); and
must be set to any non-empty string.


On return from the function, contains the fully-
qualified drive and directory of the file.

Example:
FName := "c:\"
If DLLCall("filedlgs.dll", "FileOpen", "Choose any file",
"All files (*.*)", "*.*", FName$) = 1
Then
Dir$ = PadString$(Dir$,1)
DLLCall("filedlgs.dll", "GetFileDir", FName$, Dir$)
ChangeDir Dir$
...
Endif

A note to programmers:
---------------------

Also included in this package is the Borland Pascal 7.0 source code for
FILEDLGS.DLL (as file FILEDLGS.PAS). It should be a simple matter to convert
it for use with the C language and for other compilers, if you so wish. Feel
free to modify or enhance (or redistribute) the code - I would be very
interested to receive copies of enhancements, or other comments or
suggestions. Please use one of the EMail addresses below for this purpose.

--------------------------------------
Steve Hamer-Moss,
CoCo Systems Ltd., UK.
June 1993.

EMail addresses:

Compuserve: 100034,1064
CIX: shammoss

and via Internet:

[email protected] or
[email protected]

--------------------------------------
ScriptTools(TM) is a trademark of Central Point Software, Inc.
Windows(R) is a registered trademark of Microsoft Corporation.