Clarion Community Help

This page is read only. You can view the source, but not change it. Ask your administrator if you think this is wrong.
| **Navigation:**  [[introduction.htm|Language Reference]] > 13 - Built-in Functions >====== FILEDIALOGA (extended file dialog) ====== | [[filedialog  return chosen file .htm|{{btn_prev_n.gif|Previous page}}]][[introduction.htm|{{btn_home_n.gif|Return to chapter overview}}]][[fileerror  return file driver error message .htm|{{btn_next_n.gif|Next page}}]] |
|  ||

**FILEDIALOGA(** [//title//] ,//file// [,//extensions//] [,//flag//] [,//index//] **)**

{{blk2blue.jpg|blk2blue.jpg}}

| **FILEDIALOGA** | Displays Windows standard file choice dialogs to allow the user to choose a file. |
| //title// | A string constant or variable containing the title to place on the dialog. If omitted, Windows supplies a default. |
| //file// | The label of the string variable to receive the selected filename(s). |
| //extensions// | A string constant or variable containing the available file extension selections for the "List Files of Type" drop list. If omitted, the default is all files (*.*). |
| //flag// | An integer constant or variable containing a bitmap to indicate the type of file action to perform. |
| //index// | A signed integer variable used to select a different default extension by specifying the index number. |

The **FILEDIALOGA** procedure displays Windows standard file choice dialogs and returns the file chosen by the user in the //file// parameter. Any existing value in the //file// parameter sets the default file choice presented to the user in the file choice dialog.

**FILEDIALOGA** displays either the standard //Open...// dialog or the standard //Save...// dialog. By default, on the //Open...// dialog, the user is warned if the file they choose does not exist and the file is not opened. On the //Save...// dialog, the user is warned if the file does exist and the file is not saved.

The //extensions// parameter string must contain a description followed by the file mask. All elements in the string must be delimited by the vertical bar (|) character. For example, the //extensions// string:

<code>'All Files | *.* | Clarion Source | *.CLW;*.INC;*.EQU;*.INT | Clarion Templates|*.TPL;*.TPW' </code>

defines three selections for the "List Files of Type" drop list. The first extension listed in the //extensions// string is the default. Multiple extensions are separated by a semicolon (;) character.

The //flag// parameter is a bitmap that indicates the type of file action to perform (see EQUATES.CLW for symbolic constants). For bit number:

| 0 | If Zero (0000b), the //Open...// dialog displays. Default if neither FILE:Save nor FILE:Directory are specified. | Default |
| 1 | If One (0001b), the //Save...// dialog displays. | FILE:Save |
| 2 | If Two (0010b), saves and restores the current directory path. | FILE:KeepDir |
| 4 | If Four (0100b), doesn't report errors if the file does exist on //Save...// or does not exist on //Open...//. | FILE:NoError |
| 8 | If Eight (1000b), returns multiple selections when the user selects multiple files. When using long filename dialog, it returns a vertical bar (Pipe 7Ch) delimited string of filenames (with the full path on the first selection returned, unless a single file is selected, where the path and file is returned on a single selection). The string is space-delimited when using short filename dialog. Not valid when used with File:Save or File:Directory. | FILE:Multi |
| 16 | If Sixteen (0001 0000b), uses long filename dialog in 32-bit programs. Default since C8.| FILE:LongName |
| 32 | If Thirty-Two (0010 0000b), displays a directory select dialog for selecting a directory path. | FILE:Directory |
| 64 | If Sixty-Four (0100 0000b), and the specified and typed file name does not exist, the dialog displays a prompt to create a new file with the given name. If the user chooses to create the file, the FILEDIALOGA function completes and returns the typed file name; otherwise the dialog remains open. This flag can't be combined with the FILE:Directory flag. | FILE:CreatePrompt | 
| 128 | If One-Hundred Twenty Eight (1000 0000b), and the specified file name is typed without an extension, the default extension is appended. The default extension is one used in the first mask for the first filter pair (if the last parameter of FILEDIALOGA is omitted), or for the filter pair with number contained in the integer variable passed as the last parameter of FILEDIALOGA (//index//). If there are meta-characters (* or ?) in the default extension, the flag is ignored. The flag is also ignored if either or both of the FILE:Multi and FILE:Directory flags are used. To type in the file name without an extension if the FILE:AddExtension is specified, the file name //must// be enclosed in quotes (i.e., "myfile"). Due to a Windows restriction, if the default extension is longer than 3 characters, only the first 3 characters are appending to the file name. | FILE:AddExtension |

The following is a comprehensive sample of these flags simplified to equates (see EQUATES.CLW for the complete list):

| FILE:Save | EQUATE(1) |
| FILE:KeepDir | EQUATE(2) |
| FILE:NoError | EQUATE(4) |
| FILE:Multi | EQUATE(8) |
| FILE:LongName | EQUATE(10H) |
| FILE:Directory | EQUATE(20H) |
| FILE:CreatePrompt | EQUATE(40H) |
| FILE:AddExtension | EQUATE(80H) |

Finally, the //index// parameter is a SIGNED integer used to specify a different default extension other than the first one in the //extensions// list. For example:

**'All Files | *.* | Clarion Source | *.CLW;*.INC;*.EQU;*.INT | Clarion Templates|*.TPL;*.TPW'**

The extensions string consists of pairs: <;description>|<;mask>, and the index parameter references such pairs. Therefore, in the example above, an //index// value of 2 will display the '//Clarion Source//' description and associated extensions; an index value of 3 will display '//Clarion Templates//', etc.

If **FILEDIALOGA** returns a non-zero value (i.e., the dialog is completed with Open or Save button), the index parameter is set to the index of the extension pair that was used for file selection.

**FILEDIALOGA** returns zero (0) if the user pressed the Cancel button, or one (1) if the user pressed the Ok button on the file choice dialog. If the user changes directories using the file dialog, your application's current directory also changes (unless you set FILE:KeepDir). This is a feature of the Windows operating system. If you do not want users to change your application's current directory but do want them to be able look in other directories, either save the current directory with the PATH() procedure before calling **FILEDIALOGA** then restore it with the SETPATH() statement, or set FILE:KeepDir.

| **Return Data Type:** | BOOL |

**Example:**

<code>
ViewTextFile PROCEDURE
ViewQue QUEUE                   !LIST control display queue
        STRING(255)
       END
 
FileName   STRING(64),STATIC    !Filename variable
 
ViewFile  FILE,DRIVER('ASCII'),NAME(FileName),PRE(Vew)
Record     RECORD
           STRING(255)
          END
         END
 
MDIChild1 WINDOW('View Text File'),AT(0,0,320,200),SYSTEM,HVSCROLL
          LIST,AT(0,0,320,200),USE(?L1),FROM(ViewQue),HVSCROLL
         END
Fxt   SIGNED(2) !File Extension
CODE
IF NOT FILEDIALOGA('Choose File to View',FileName,'Text|*.TXT|Source|*.CLW',FILE:LongName,Fxt)
 RETURN                        !Return if no file chosen
END
OPEN(ViewFile)                 !Open the file
IF ERRORCODE() THEN RETURN END!aborting on any error
SET(ViewFile)                  !Start at top of file
LOOP
 NEXT(ViewFile)                !Reading each line of text
 IF ERRORCODE() THEN BREAK END !Break loop at end of file
 ViewQue = Vew:Record          !Assign text to queue
 ADD(ViewQue)                  !and add a queue entry
END
CLOSE(ViewFile)                !Close the file
OPEN(MDIChild1)                !and open the window
ACCEPT                         !Allow the user to read the text and
END                            !break out of ACCEPT loop only from
                               !system menu close option
FREE(ViewQue)                  !Free the queue memory
RETURN                         !and return to caller
 
!************************************************************
!This example shows using FILEDIALOGA for multi-file selection:
   PROGRAM
   MAP
   END
 
FN             STRING(260)
ExtPickInOut   SIGNED,AUTO
ExtFound       SIGNED,AUTO
   CODE
   ExtPickInOut = 2  !default to CSV
   IF ~FILEDIALOGA('Pick file to save',fn,'Text|*.TXT|Comma Delimited     |
   (*.CSV)|*.CSV|Tab Delimited (*.TSV)|*.TSV', FILE:Save+ FILE:LongName,  | 
   ExtPickInOut)
       RETURN
   END
   ExtFound = INLIST(UPPER(SUB(CLIP(FN),-4,4)),'.TXT','.CSV','.TSV')
   IF ~ExtFound    !No extension so add one based on selected file type
       ExtFound=ExtPick
       fn=clip(fn) & CHOOSE(ExtPickInOut,'.TXT','.CSV','.TSV','')
   END
 
!This code assumes a 3 byte extension. There are a other possible ways to test !for an extension.

</code>

**See Also:**

[[filedialog  return chosen file .htm|FILEDIALOG]]

[[setpath  change current drive and directory .htm|SETPATH]]

[[shortpath  return short filename .htm|SHORTPATH]]

[[longpath  return long filename .htm|LONGPATH]]

[[directory  get file directory .htm|DIRECTORY]]

[[getfont  get font information .htm|GETFONT]]

[[setfont  specify font .htm|SETFONT]]

[[prop fontdialoghook.htm|PROP:FontDialogHook]]