FILEDLG
A user file selection accessory for use with r4™

Categories:

visual accessory, user file selection accessory

Description:

The FILEDLG accessory is used by r4™ programs to acquire a system file name. Since multiple r4™ programs can be active at the same time, the name of a system registry subkey is passed as a value in the command line. This allows each r4™ program to receive an independent file name response value.

Usage:

  FILEDLG registrySubkey

Arguments:

 registrySubkey .. a system registry subkey

The FILEDLG program's main system registry key is:
  HKEY_LOCAL_MACHINE\Software\Kilowatt Software\FileDlg

The following registry values are initially passed by the r4™ program to FILEDLG. See the registry extract below to better understand the format of these values.

1. Title
The caption of the file selection window

+2. Filter (optional)
A set of pairs of file patterns separated by vertical bars. The first value within the pair is displayed to the user in a drop-down list. The second value of the pair identifies a file pattern that selects available files within the current directory. The filter value must be concluded with two vertical bar characters. If this value is not set the following default filter string is used:
 Text Files (*.txt)|*.txt|All Files (*.*)|*.*||

+3. InitialPath (optional)
The initial file name path. If this value is not set the following default path is used:
 *.txt

+4. Write (optional)
Is a value of 'Yes' or 'No', only the leading character is required, case is insignificant. When the value is 'Yes', a prompt is displayed if an existing file will be replaced. A similar prompt is produced if a new file will be created.

+5. Select (optional)
Is a value of 'Yes' or 'No', only the leading character is required, case is insignificant. When the value is 'Yes', a prompt is displayed if the file does not exist. When selecting a file it must exist beforehand.

+6. InitialDirectory (optional)
Identifies the initial directory for file selection. This value is automatically revised when the user presses the OK button. The directory is derived from the selected file.

The following registry values are revised when the FILEDLG program returns.

File
The name of the selected file. This will be empty if the user pressed the Cancel button.

InitialDirectory
The name of the directory that contains the selected file.

Returns:

Buttons:

OK
Concludes FILEDLG operation. The file name value is stored in the system registry.

Cancel
Concludes FILEDLG operation, without revising the system registry value.

Example registry values

Here is a registry extract associated with an invocation by the FileDlg.rex example program.

 [HKEY_LOCAL_MACHINE\SOFTWARE\Kilowatt Software\FileDlg\Test]
 Title=Select output file
 Filter=CSV Files (*.csv)|*.csv|All Files (*.*)|*.*||
 InitialPath=*.csv
 Select=No
 Write=Yes
 InitialDirectory=G:\\r4
 File=G:\\r4\\bb.CSV

The plain values are passed to the FILEDLG program.

The BOLD values are returned.

Example:

The following is the r4™ program that interacted with the FILEDLG program with the registry values shown above.

 /* FileDlg.rex
   this program is an example
 
   this program communicates with FileDlg.EXE via the registry
 */
 
 trace off /* ignore nonzero return codes */
 
 tab = d2c( 9 )
 
 /* prepare FileDlg request entries -- using the 'Test' subkey */
 
 'set R4REGISTRYWRITE=Y' /* enable registry writing */
 
 call value 'HKLM\Software\Kilowatt Software\FileDlg\Test[Filter]', 'CSV Files (*.csv)|*.csv|All Files (*.*)|*.*||', 'Registry'
 
 call value 'HKLM\Software\Kilowatt Software\FileDlg\Test[InitialPath]', '*.csv', 'Registry'
 
 /* existing file selection */
 
 if translate( left( arg(1)'S', 1 ) ) = 'S' then do
   call value 'HKLM\Software\Kilowatt Software\FileDlg\Test[Title]', 'Select a file to read', 'Registry'
   call value 'HKLM\Software\Kilowatt Software\FileDlg\Test[Select]', 'Yes', 'Registry'
   call value 'HKLM\Software\Kilowatt Software\FileDlg\Test[Write]', 'No', 'Registry'
   end
 
 /* file creation or replacement */
 
 else do
   call value 'HKLM\Software\Kilowatt Software\FileDlg\Test[Title]', 'Select output file', 'Registry'
   call value 'HKLM\Software\Kilowatt Software\FileDlg\Test[Select]', 'No', 'Registry'
   call value 'HKLM\Software\Kilowatt Software\FileDlg\Test[Write]', 'Yes', 'Registry'
   end
 
 'FileDlg Test' /* show FileDlg -- using the 'Test' subkey */
 
 say rc
 
 /* get FileDlg response */
 
 if rc = 1 then do
   fileName = value( 'HKLM\Software\Kilowatt Software\FileDlg\Test[File]', , 'Registry' )
   'MsgBox' 'You selected file' DoubleSlash( fileName )
   end
 
 exit 0
 
  /* procedure DoubleSlash
   * converts single backward slash characters to double backward slash characters
   */
 
 DoubleSlash : procedure
   r = ''
   s = arg( 1 )
   do while s <> ''
     parse var s front '\' s
     r = r || front
     if s <> '' then
       r = r'\\'
     end
   return r

FILEDLG
An r4™ auxiliary rogram.
Version 1.0
Copyright © 2001-2007
All Rights Reserved.
Web: http://www.kilowattsoftware.com/
E-Mail: support@kilowattsoftware.com