FILESAVE() Function - Create File Save Dialog

Syntax

FILESAVE(prompt,path,name,ext[,filters[,mode]])

Syntax (BBj 7.0 and higher)

FILESAVE(prompt,path,name,ext[,filters[,mode[,MODE="CLIENT,STYLE=name,EXISTS=option"]])

Description

The FILESAVE function activates the standard File Save dialog.

Parameter

Description

prompt

Text to display in the title bar of the dialog.

path

Default directory for the file to be saved in the dialog.

name

Default name for the file to be saved in the dialog. Use the empty string ("") to avoid setting a default filename.

ext

Default extension (usually 3 characters, do not include the dot) for the file to be saved in the dialog. Use the empty string ("") to avoid setting a default extension.

filters

One or more filters in the following format:

"text description" + $0a$ + "mask" [+$0a$ + "text description" + $0a$ + "mask" …]

The mask specifies an extension, in the format "*.ext" or "*.*"; two or more masks are separated with semicolons. The filter, if included, indicates which files will appear in the list.

For example:

REM Illustrate the use of the FILESAVE() function

 REM Build filters for brc/arc and all files
 FILTER$="Binary Resource Files"+$0a$+"*.brc;*.brf"
 FILTER$=FILTER$+$0a$+"ASCII Resource Files"+$0a$+"*.arc"
 FILTER$=FILTER$+$0a$+"All Files (*.*)"+$0a$+"*.*"

 REM Starting directory is the default Directory
 FILE_DIR$=""

 REM Use FILESAVE() to get name of file to save
 FILE_NAME$=FILESAVE("Save Resource File",FILE_DIR$,"","",FILTER$)

 REM display file name returned
 PRINT FILE_NAME$

mode

In BBj 5.0 and higher, select whether file, directories, or files and directories are selectable using the file dialog. The available options for mode are:

0 only files may be selected

1 only directories may be selected

2 files or directories may be selected

Note: The default setting is 0. When setting mode to 1 or 2, the filters option is ignored.

For example:

REM Illustrate the use of the FILESAVE() function to select only directories

 

 REM Set the mode to directories only

 MODE=1

 

 REM The filters parameter is ignored when selecting directories only

 FILTER$=""

 

 REM Starting directory is the default Directory

 FILE_DIR$=""

 

 REM Use FILESAVE() to get name of directory

 FILE_NAME$=FILESAVE("Save Directory",FILE_DIR$,"","",FILTER$,MODE)

 

 REM display file name returned

 PRINT FILE_NAME$

MODE="CLIENT"

In BBj 7.0 and higher - if this option is present, the FILESAVE dialog will show files on the client's filesystem instead of the server's system. If this option is omitted, the FILESAVE dialog will show files on the server's filesystem.

MODE="STYLE=name"

In BBj 14.0 and higher, this sets a FILESAVE style name, equivalent to BBjControl::addStyle. This can be used to apply custom CSS styling to a BUI FILESAVE.

MODE="EXISTS=option"

In BBj 15.0 and higher, this mode specifies what should happen when the user selects a file that already exists. The available options are:

0 The selection is accepted with no additional user action.
1 The user is presented with an error dialogue; the selection is not allowed.
2 The user is presented with a dialogue requesting confirmation. This is the default.
MODE="RESTRICTED" In BBj 21.11 and higher, this mode restricts a server-side file chooser to the directory specified in the default directory (path).
MODE="attr=value"

DWC logoIn BBj 23.00 and higher, the mode string can specify selected DWC dialog attributes (e.g. "theme=primary,blurred=true").

Server filesave() can specify DWC file-chooser attributes.

Client filesave() can specify DWC file-save attributes.

The user can create a dynamic filter by typing a simple pattern (containing at least one * or ?) into the filename text box (e.g. *.pdf).

When the dialog is dismissed, this returns  "::BAD::" (error encountered), "::CANCEL::" (user clicked Cancel), or the fully qualified path of the selected file. If the user chooses a name that already exists, overwrite is confirmed. This dialog does not actually cause any files to be saved but returns the name the user has selected.

In BBj 2.02 and higher, the FILESAVE function and mnemonic is localized according to current STBL("!LOCALE") setting. For more information, see Localization.

For more information, see FILESAVE Mnemonic - Create File Save Dialog.

BUI logoCSS

The visual appearance of BUI controls is defined using CSS (cascading style sheets) rules. Easily change the default colors, border, and other settings by customizing these rules, all without changing any application code. See CSS API for a high-level overview of BUI CSS.

See BUI: Interacting with client files for a discussion of the BUI FILESAVE() function with MODE="CLIENT".

The FILESAVE() function defines the following style names:

.BBjFileSave (the top level of the dialog window)

.BBjFileSave-title (the title bar)

.BBjFileSave-panel (the body area)

The body contains a .BBjFileChooser structure as defined for the BBjFileChooser control.

Sample

rem ' filesave
precision 6
tc! = bbjapi().getThinClient()
fs! = tc!.getClientFileSystem()
filter$ = ""
filter$ = filter$ + "Text Files (*.txt)"+$0a$+"*.txt"+$0a$
filter$ = filter$ + "HTML Files (*.htm;*.html)"+$0a$+"*.htm;*.html"+$0a$
filter$ = filter$ + "Image Files (*.png;*.jpg;*.jpeg;*.bmp;*.gif)"+$0a$+"*.png;*.jpg;*.jpeg;*.bmp;*.gif"+$0a$
filter$ = filter$ + "All Files (*.*)"+$0a$+"*.*"+$0a$
i = msgbox("Test client fileopen + copy file from client to server",mode="theme=info")
clientfile$ = fileopen("Pick a client file","","","",filter$,mode="client,theme=primary")
i = msgbox(clientfile$,0,"Selected client file",mode="theme=info")
if pos("::"=clientfile$) then goto eoj
cf! = fs!.getClientFile(clientfile$)
i = msgbox("Copy "+clientfile$+" to the server",mode="theme=primary")
t = tim
serverfile$ = cf!.copyFromClient()
t = tim - t
t = t * 3600
serverfile = unt
open (serverfile)serverfile$
serverfile$ = fid(serverfile)(9)
bytes = dec(fin(serverfile)(1,4))
close (serverfile)
i = msgbox("Copied client file "+clientfile$+" to server file "+serverfile$+" ("+str(bytes)+" bytes; "+str(t)+" seconds)",0,"Copied from client to server",mode="theme=primary")
i = msgbox("Test server fileopen + copy file from server to client",mode="theme=info")
serverfile$ = fileopen("Pick a server file","","","",filter$,mode="theme=primary,sort=+name")
i = msgbox(serverfile$,0,"Selected server file",mode="theme=info")
if pos("::"=serverfile$) then goto eoj
clientfile! = new java.io.File(serverfile$)
clientfile$ = clientfile!.getName()
clientfile$ = filesave("Save to client","",clientfile$,"",filter$,mode="client,theme=primary")
if pos("::"=clientfile$) then goto eoj
i = msgbox("Copy server file "+serverfile$+" to client file "+clientfile$,mode="theme=primary")
cf! = fs!.getClientFile(clientfile$)
cf!.copyToClient(serverfile$)
i = msgbox("Copied server file "+serverfile$+" to client file "+clientfile$,0,"Copied from server to client",mode="theme=success")
eoj:
release

See Also

Functions - Alphabetical Listing