|
WSupported on Windows
|
|
|
NSupported in Synergy .NET
|
status = %SYNMSW_GETFILENAME(filename, title, filters, [default_name], [extension] [, option])
Return value
status
The filter index (1-based) that is returned by the Microsoft Open or Save As dialog box, or false if the Cancel button is pressed in the dialog box or the dialog box returns an error. (^VAL)
Arguments
filename
Returned with the entered or selected filename. (a)
title
The title for the input window or dialog box. (a)
filters
A filter description followed by a list of filters. (a)
default_name
(optional) The default filename. (a)
extension
(optional) The default extension. (a)
option
(optional) One or more of the following option flags, which are defined in tools.def. For traditional Synergy, you can pass more than one option by combining options with .BOR. or the vertical bar ( | ) operator. For Synergy .NET, only D_OFN_SAVEAS is supported. (n)
Center dialog box over application window.
No Network button.
Save as, instead of Open.
Don’t translate logicals.
Discussion
The %SYNMSW_GETFILENAME function pops up a dialog box or window that enables the user to select a file either by entering a filename in a field or by browsing and then selecting a filename from a list. Note that to actually open the selected file, your program must call U_OPEN.
%SYNMSW_GETFILENAME calls the standard file “Open” or “Save as” dialog box, and users can change directories as they browse.
%SYNMSW_GETFILENAME does not time out.
Filename is returned with the name of the selected file—whether entered directly into the “File (Name)” field or selected from the file browse box. If the user entered the filename into the “File (Name)” field, the returned filename also will contain any path specification explicitly typed. Native path specification or standard Synergy DBL logical translation (in the form of LOGICAL:filename) is supported.
If the variable passed as filename is not big enough to hold the full path specification, %SYNMSW_GETFILENAME returns false, and filename will be blank. We recommend a variable size of 256.
If the user enters a filename but no path, the current path of the dialog box will be prefixed to the returned filename. When the user first enters the dialog box, the initial path will be
- the path contained in default_name.
- the current working directory if no path is specified in default_name or if default_name is not passed.
(Remember, however, that the user may change the directory of the dialog box.)
title
Title becomes the title for the “Open” or “Save as” dialog box.
filters
Filters is a delimited alpha argument that consists of a filter description followed by the filters themselves. All items are separated by a null (%CHAR(0) in traditional Synergy or a vertical bar (|) in Synergy .NET). In addition, the entire string must be terminated by a null. For example,
filters = "Text Files (*.txt)" + %char(0) + "*.txt" + %char(0) & + "INI Files (*.ini)" + %char(0) + "*.ini" + %char(0) & + "All Files (*.*)" + %char(0) + "*.*" + %char(0)
Be sure to use the appropriate form for your application’s system when specifying filters.
default_name
If default_name is passed, filename will be returned with the contents of default_name if the user doesn’t select a filename.
If default_name is not passed and the user doesn’t select a filename, the contents of filename will be blank.
Default_name can include a complete path name (directory and filename). If no path is specified, %SYNMSW_GETFILENAME searches for the default filename in the current working directory. You can use native path specification or standard Synergy DBL logical translation (in the form of LOGICAL:filename) as the path specification in default_name. See filename above for ramifications of including a path name.
extension
If extension is passed, when the user enters a filename without an extension into the “File (Name)” field, %SYNMSW_GETFILENAME will append a period (“.”) followed by extension to the returned filename. If the user selects a file from the file browse box, extension is ignored.
option
D_OFN_CENTER centers the dialog box over the application window. Default positioning is determined by Windows Common Dialogs and is generally in the upper left-hand corner of the screen. (traditional Synergy only)
D_OFN_NONETWORK suppresses the inclusion of the “Network” button in the dialog box. This button is included by default. If included, it enables the user to browse other file systems connected to the current system. (traditional Synergy only)
D_OFN_SAVEAS indicates that the standard “Save as” dialog box should be used instead of the “Open” dialog box. %SYNMSW_GETFILENAME uses the “Open” dialog box by default.
D_OFN_NOTRANS indicates that any logicals entered by the user should not be translated in the filename that is returned. (traditional Synergy only)
|
if Toolkit is not already in use in the application, tools.def should be included like this: .define D_DEFINES_ONLY .include "WND:tools.def" .undefine D_DEFINES_ONLY This will prevent all of the UI Toolkit’s global data being added to the non-Toolkit application. |
