Dlg Open, Dlg Save Command

Purpose

Calls the common file selecting dialog box.

Syntax

Dlg Open form, Flags%, Title$, Dir$, DefExt$, Filter$[()], Ret$

Dlg Save form, Flags%, Title$, Dir$, DefExt$, Filter$[()], Ret$

Description

Dlg Open and Dlg Save call, like the command FileSelect, the common file selecting dialog. However, in contrast with FileSelect, Dlg Open and Dlg Save can be configured.

form is a Form object, like Me, Win_1, Dlg_1, frm1

Title$ is the title of the file dialog box.

Dir$ is the default directory (a string).

DefExt$ is a file name extension of three characters, which will automatically be appended if no extension is given.

Filter$ is a either a string array or a string declaring the file search filter. Two strings apply to each selection: the first contains descriptive text which appears in the ComboBox. The next one determines the file mask (filter) which applies to it. (It can hold multiple examples each separated by a semicolon ";"). When using an array terminate the array with an empty string, see example. Filter$ may also be a string. Use the pipe ( | ) symbol (ASCII 124) to separate the description and filter values. Don't include spaces before or after the pipe symbol, because these spaces will be displayed with the description and filter values. For instance:

flit$ = "Text (*.txt)|*.txt|Pictures (*.bmp;*.ico)|*.bmp;*.ico"

Ret$ is a string variable which receives the file name. The string will contain the full path. When the dialog box is canceled the return value is an empty string.

Flags can contain the following values:

OFN_READONLY	$00001	The Read-Only check box will be activated. Return value in _EBX.
OFN_OVERWRITEPROMPT	$00002	If a file already exists a warning appears.
OFN_HIDEREADONLY	$00004	Hide the Read-Only checkbox.
OFN_NOCHANGEDIR	$00008	Resets back to the same directory as when the Dialog was created.
OFN_NOVALIDATE	$00100	Invalid characters in the filename are allowed
OFN_EXTENSINODIFFERENT	$00400	Returns a value in _EBX if extension is different than specified.
OFN_PATHMUSTEXIST	$00800	Selected path is verified.
OFN_FILEMUSTEXIST	$01000	Selected file is verified.
OFN_CREATEPROMPT	$02000	If a file does not exist, a warning is displayed.
OFN_NOREADONLYRETURN	$08000	Does not return names of write-protected files.
OFN_NOTESTFILECREATE	$10000	With Open SAVE, the file will not be created and cancelled for the purposes of testing. This option was conceived for WORM (WriteOnce Read Many) drives, create-no-modify networks, and the like.

These bits are not allowed in GFA-BASIC:

OFN_SHOWHELP	$00010
OFN_ENABLEHOOK	$00020
OFN_ENABLETEMPLATE	$00040
OFN_ENABLETEMPLATEHANDLE	$00080
OFN_ALLOWMULTISELECT	$00200
OFN_SHAREAWARE	$04000

_AX is a null if there is an error.

File$ is selected filename and path.

_EBX is the new value for Flags.

Example

OpenW 1

Auto file$

Dim filt$(20)

filt$(0) = "BMP-Files", filt$(1) = "*.BMP;*.RLE"

filt$(2) = "PCX-Files", filt$(3) = "*.PCX"

filt$(4) = ""

file$ = "NONAME.BMP"

Dlg Open Me, 0, "This is a test", "d:\pcx", "BMP", filt$(), file$

Dlg Open Me, 0, "", "", "BMP", "BMP-Files|*.BMP;*.RLE|PCX files|*.PCX", file$

This code fragment specifies two filters. The filter with the "BMP-Files" description has two patterns. If the user selects this filter, the dialog box displays only files that have the .BMP and .RLE extensions.

Remarks