FileLists

Functions
int	mdlDialog_defFileCreate (BeFileNameR fileName, RscFileHandle rFileH, RscId dlogBoxId, WCharCP suggestedFileName, WCharCP filterString, WCharCP defaultDirectory, WCharCP titleString, int defaultFileId, RscFileHandle userPrefH)
	An extension to mdlDialog_fileCreate which lets the user choose a file through a Dialog Box for creating. More...
int	mdlDialog_defFileOpen (BeFileNameR fileName, RscFileHandle rFileH, RscId dlogBoxId, WCharCP suggestedFileName, WCharCP filterString, WCharCP defaultDirectory, WCharCP titleString, int defaultFileId, RscFileHandle userPrefH)
	An extension to mdlDialog_fileOpen which lets the user choose a file through a Dialog Box for opening. More...
int	mdlDialog_fileCreate (BeFileNameR fileName, RscFileHandle rFileH, RscId resourceId, WCharCP suggestedFileName, WCharCP filterString, WCharCP defaultDirectory, WCharCP titleString)
	Displays a Dialog Box that lets the user choose a file to create. More...
int	mdlDialog_fileCreateFromSeed (BeFileNameR fileName, RscFileHandle rFileH, RscId resourceId, WCharCP suggestedFileName, WCharCP filterString, WCharCP defaultDirectory, WCharCP titleString, WCharP seedFile, WCharCP seedDirectory, WCharCP seedFilter)
	Displays a Dialog Box that lets the user choose an existing seed file and a new file name for creating a design file. More...
int	mdlDialog_fileOpen (BeFileNameR fileName, RscFileHandle rFileH, int resourceId, WCharCP suggestedFileName, WCharCP filterString, WCharCP defaultDirectory, WCharCP titleString)
	Displays a Dialog Box that lets the user choose a file to open. More...
StringListP	mdlFileList_edit (FileListInfo *lastInfoP, StringListP stringListP, long attributes, WCharCP dialogTitle, WCharCP listLabel, WCharCP fileFilter, WCharCP defaultDirectory)
	Displays a dialog box that allows the user to create and edit a list of files, directories or drives. More...
int	mdlFileList_get (StringListP stringListP, int attributes, WCharCP defaultDirectory, WCharCP fileFilter)
	Gets a list of files/directories/drives as specified by attributes, defaultDirectory and fileFilter. More...
int	mdlFileList_fromString (StringListP *fileList, WCharCP fileName)
	Searches the specified directories for files matching the criteria in fileName. More...

Detailed Description

Function Documentation

int mdlDialog_defFileCreate	(	BeFileNameR	fileName,
		RscFileHandle	rFileH,
		RscId	dlogBoxId,
		WCharCP	suggestedFileName,
		WCharCP	filterString,
		WCharCP	defaultDirectory,
		WCharCP	titleString,
		int	defaultFileId,
		RscFileHandle	userPrefH
	)

An extension to mdlDialog_fileCreate which lets the user choose a file through a Dialog Box for creating.

However, if the defaultFileId parameter is provided, this function will also "remember" the suggestedFileName and fileFilter parameters used to create the last file of the same type. These remembered parameters will then be used in place of the current suggestedFileName and fileFilter parameters. The defaultDirectory parameter will also be set to the directory where suggestedFileName was last loaded.

Remarks

Since users generally group files of a given type in the same directory, using these functions in place of mdlDialog_fileOpen and mdlDialog_fileCreate will reduce the amount of directory changes required by the user in the file selection Dialog Box.

Parameters

[out]	fileName	returns the name of the file to be opened or created. On Open, filename is guaranteed to list a valid existing file. On Create, if the file already exists, an alert will display asking the user if the existing file should be overwritten. If the user chooses CANCEL, the user can choose another file name. If the user chooses OK, the filename will be returned.
[in]	rFileH	offers users the functionality of standard file open/ create Dialog Boxes in their own Dialog Boxes. rFileH is a handle to the resource file to use for loading a user-specified Dialog Box. If rFileH is NULL, the default resource file will be used.
[in]	dlogBoxId	is the ID of the Dialog Box to use within the resource file. If resourceId is 0, the default Dialog Box will be used. The first six items in the Dialog Box that the user creates should match these same items in the standard file open/create Dialog Box; offers users the functionality of standard file open/ create Dialog Boxes in their own Dialog Boxes.
[in]	suggestedFileName	is overridden if the defaultFileId parameter is provided and resource information for this parameter exists in the file specified by userprefH.
[in]	filterString	is overridden if the defaultFileId parameter is provided and resource information for this parameter exists in the file specified by userprefH.
[in]	defaultDirectory	contains the directory where the selection process starts, but can also be an environment variable. In the latter case, the directory associated with the variable is used. This argument can be overwritten with the suggestedFileName argument. If defaultDirectory is NULL, the current working directory will be used.
[in]	titleString	contains the title of the Dialog Box
[in]	defaultFileId	identifies a resource in a user preferences file. This resource is used in two ways. First, it will be loaded just prior to the display of the file open or file creation Dialog Box to obtain the suggestedFileName and fileFilter used during the last execution of this Dialog Box (using the same defaultFileId). If the user successfully chooses the same or some other file in the Dialog Box (indicated by clicking OK), the new filename and filter are saved back to the resource in the user preference file.
[in]	userPrefH	is the handle of a user preference resource file opened by the calling application or NULL if the MicroStation User Preferences file is to be used. This is where the default file information is loaded from and saved after the user makes a new file selection.

Remarks

To access filenames and filters saved internally by MicroStation, you must provide one of the resourceIDs listed in the MDL system header file deffiles.h and set userprefH to NULL to indicate MicroStation's User Preferences file.

A "user preference" resource file is a file created by the calling application for the purpose of storing user-defined operating parameters. Such a file is reused by the application in later sessions. The MicroStation User Preferences file is automatically created by MicroStation.

Returns

true if the CANCEL button is pressed, false if the OK button is pressed, and ERROR if an error occurred while the Dialog Box was being created.

See also

mdlDialog_fileOpenExt mdlDialog_fileOpen mdlDialog_fileCreate mdlResource_createFile mdlResource_openFile

int mdlDialog_defFileOpen	(	BeFileNameR	fileName,
		RscFileHandle	rFileH,
		RscId	dlogBoxId,
		WCharCP	suggestedFileName,
		WCharCP	filterString,
		WCharCP	defaultDirectory,
		WCharCP	titleString,
		int	defaultFileId,
		RscFileHandle	userPrefH
	)

An extension to mdlDialog_fileOpen which lets the user choose a file through a Dialog Box for opening.

However, if the defaultFileId parameter is provided, this function will also "remember" the suggestedFileName and fileFilter parameters used to open the last file of the same type. These remembered parameters will then be used in place of the current suggestedFileName and fileFilter parameters. The defaultDirectory parameter will also be set to the directory where suggestedFileName was last loaded.

Remarks

Since users generally group files of a given type in the same directory, using these functions in place of mdlDialog_fileOpen and mdlDialog_fileCreate will reduce the amount of directory changes required by the user in the file selection Dialog Box.

Parameters

[out]	fileName	returns the name of the file to be opened or created. On Open, filename is guaranteed to list a valid existing file. On Create, if the file already exists, an alert will display asking the user if the existing file should be overwritten. If the user chooses CANCEL, the user can choose another file name. If the user chooses OK, the filename will be returned.
[in]	rFileH	offers users the functionality of standard file open/ create Dialog Boxes in their own Dialog Boxes. rFileH is a handle to the resource file to use for loading a user-specified Dialog Box. If rFileH is NULL, the default resource file will be used.
[in]	dlogBoxId	is the ID of the Dialog Box to use within the resource file. If resourceId is 0, the default Dialog Box will be used. The first six items in the Dialog Box that the user creates should match these same items in the standard file open/create Dialog Box; offers users the functionality of standard file open/ create Dialog Boxes in their own Dialog Boxes.
[in]	suggestedFileName	is overridden if the defaultFileId parameter is provided and resource information for this parameter exists in the file specified by userprefH.
[in]	filterString	is overridden if the defaultFileId parameter is provided and resource information for this parameter exists in the file specified by userprefH.
[in]	defaultDirectory	contains the directory where the selection process starts, but can also be an environment variable. In the latter case, the directory associated with the variable is used. This argument can be overwritten with the suggestedFileName argument. If defaultDirectory is NULL, the current working directory will be used.
[in]	titleString	contains the title of the Dialog Box
[in]	defaultFileId	identifies a resource in a user preferences file. This resource is used in two ways. First, it will be loaded just prior to the display of the file open or file creation Dialog Box to obtain the suggestedFileName and fileFilter used during the last execution of this Dialog Box (using the same defaultFileId). If the user successfully chooses the same or some other file in the Dialog Box (indicated by clicking OK), the new filename and filter are saved back to the resource in the user preference file.
[in]	userPrefH	is the handle of a user preference resource file opened by the calling application or NULL if the MicroStation User Preferences file is to be used. This is where the default file information is loaded from and saved after the user makes a new file selection.

Remarks

A "user preference" resource file is a file created by the calling application for the purpose of storing user-defined operating parameters. Such a file is reused by the application in later sessions. The MicroStation User Preferences file is automatically created by MicroStation.

Returns

true if the CANCEL button is pressed, false if the OK button is pressed, and ERROR if an error occurred while the Dialog Box was being created.

See also

mdlDialog_fileOpenExt mdlDialog_fileOpen mdlDialog_fileCreate mdlResource_createFile mdlResource_openFile

Remarks

Required Library: mdlbltin.lib

int mdlDialog_fileCreate	(	BeFileNameR	fileName,
		RscFileHandle	rFileH,
		RscId	resourceId,
		WCharCP	suggestedFileName,
		WCharCP	filterString,
		WCharCP	defaultDirectory,
		WCharCP	titleString
	)

Displays a Dialog Box that lets the user choose a file to create.

It also lets the programmer modify the standard create Dialog Box by specifying an alternate Dialog Box that uses some functionality of the standard one.

Parameters

[out]	fileName	returns the name of the file to be created. If the file already exists, an alert will display asking the user if the existing file should be overwritten. If the user chooses CANCEL, another file name can be chosen. If the user chooses OK, the filename is returned.
[in]	rFileH	offers users the functionality of standard file open/ create Dialog Boxes in their own Dialog Boxes. rFileH is a handle to the resource file to use for loading a user-specified Dialog Box. If rFileH is NULL, the default resource file will be used.
[in]	resourceId	is the ID of the Dialog Box to use within the resource file. If resourceId is 0, the default Dialog Box will be used. The first six items in the Dialog Box that the user creates should match these same items in the standard file open/create Dialog Box.
[in]	suggestedFileName	suggests a filename for creating a file. It displays in the text field of the dialog. If a directory is attached to the filename, this argument serves as the default directory and the defaultDirectory argument is ignored.
[in]	filterString	contains the filter to use for determining which files to include in the file list. It is useful for limiting files displayed to a particular type. Simple wildcarding is allowed. An asterisk '*' will match any string and a question mark '?' will match any single character. If fileFilter is NULL, the filter string will match all files (*.*).
[in]	defaultDirectory	contains the directory where the selection process starts, but can also be an environment variable. In the latter case, the directory associated with the variable is used. This argument can be overwritten with the suggestedFileName argument. If defaultDirectory is NULL, the current working directory will be used.
[in]	titleString	contains the title of the Dialog Box

Returns

true if the CANCEL button is pressed, false if the OK button is pressed, and ERROR if an error occurred while the Dialog Box was being created.

See also

mdlDialog_fileOpenExt mdlDialog_fileOpen

Remarks

Required Library: mdlbltin.lib

int mdlDialog_fileCreateFromSeed	(	BeFileNameR	fileName,
		RscFileHandle	rFileH,
		RscId	resourceId,
		WCharCP	suggestedFileName,
		WCharCP	filterString,
		WCharCP	defaultDirectory,
		WCharCP	titleString,
		WCharP	seedFile,
		WCharCP	seedDirectory,
		WCharCP	seedFilter
	)

Displays a Dialog Box that lets the user choose an existing seed file and a new file name for creating a design file.

It also lets the programmer modify the create Dialog Box by specifying a Dialog Box to use. This Dialog Box uses some functionality of the standard one.

Parameters

[out]	fileName	returns the name of the file to be opened or created. To create a file, the user must check to see if the fileName returned currently exists and handle the situation appropriately. (This often involves setting up an alert box asking the user if the desired file should be overwritten).
[in]	rFileH	rFileH and resourceId offer users the functionality of standard file open/ create Dialog Boxes in their own Dialog Boxes. rFileH is a handle to the resource file to use for loading a user-specified Dialog Box. If rFileH is NULL, the default resource file will be used.
[in]	resourceId	is the ID of the Dialog Box to use within the resource file. If resourceId is 0, the default Dialog Box will be used. The first six items in the Dialog Box that the user creates should match these same items in the standard file open/create Dialog Box.
[in]	suggestedFileName	suggests a filename for creating a file. It displays in the text field of the dialog. If a directory is attached to the filename, this argument serves as the default directory and the defaultDirectory argument is ignored. This argument should normally be NULL when it is called for opening files.
[in]	filterString	contains the filter to use for determining which files to include in the file list. It is useful for limiting files displayed to a particular type. Simple wildcarding is allowed. An asterisk `*' matches any string and a question mark `?' matches any single character. If fileFilter is NULL, the filter string will match all files (*.*).
[in]	defaultDirectory	contains the directory where the selection process starts. It can also be an environment variable. In this case, the directory associated with the variable is used. This argument can be overwritten with the suggestedFileName argument. If defaultDirectory is NULL, the current working directory will be used.
[in]	titleString	contains the title of the Dialog Box.
[in,out]	seedFile	seedFile, seedDirectory and seedFilter are identical to suggestedFileName, defaultDirectory and fileFilter except that these are used for the seed file Dialog Box. The seed file Dialog Box can be invoked from the create Dialog Box and lets the user specify which seed file to use in the creation of the design file.
[in]	seedDirectory	see seedFile
[in]	seedFilter	see seedFile

Returns

true if the CANCEL button is pressed, false if the OK button is pressed, and ERROR if an error occurred while the Dialog Box was being created.

See also

mdlDialog_fileOpenExt mdlFileList_edit mdlDialog_fileOpen mdlDialog_fileCreate

Remarks

Required Library: mdlbltin.lib

int mdlDialog_fileOpen	(	BeFileNameR	fileName,
		RscFileHandle	rFileH,
		int	resourceId,
		WCharCP	suggestedFileName,
		WCharCP	filterString,
		WCharCP	defaultDirectory,
		WCharCP	titleString
	)

Displays a Dialog Box that lets the user choose a file to open.

It also lets the programmer modify the standard open Dialog Box by specifying an alternate Dialog Box that uses some functionality of the standard one.

Parameters

[out]	fileName	returns the name of the file to be opened. The filename is guaranteed to list a valid existing file.
[in]	rFileH	offers users the functionality of standard file open/ create Dialog Boxes in their own Dialog Boxes. rFileH is a handle to the resource file to use for loading a user-specified Dialog Box. If rFileH is NULL, the default resource file will be used.
[in]	resourceId	is the ID of the Dialog Box to use within the resource file. If resourceId is 0, the default Dialog Box will be used. The first six items in the Dialog Box that the user creates should match these same items in the standard file open/create Dialog Box.
[in]	suggestedFileName	suggests a filename for creating a file. It displays in the text field of the dialog. If a directory is attached to the filename, this argument serves as the default directory and the defaultDirectory argument is ignored. This argument is normally set to NULL when opening files.
[in]	filterString	contains the filter to use for determining which files to include in the file list. It is useful for limiting files displayed to a particular type. Simple wildcarding is allowed. An asterisk '*' will match any string and a question mark '?' will match any single character. If fileFilter is NULL, the filter string will match all files (*.*).
[in]	defaultDirectory	contains the directory where the selection process starts, but can also be an environment variable. In the latter case, the directory associated with the variable is used. This argument can be overwritten with the suggestedFileName argument. If defaultDirectory is NULL, the current working directory will be used.
[in]	titleString	contains the title of the Dialog Box

Returns

true if the CANCEL button is pressed, false if the OK button is pressed, and ERROR if an error occurred while the Dialog Box was being created.

See also

mdlDialog_fileOpenExt mdlDialog_fileCreate mdlResource_createFile

Remarks

Required Library: mdlbltin.lib

StringListP mdlFileList_edit	(	FileListInfo *	lastInfoP,
		StringListP	stringListP,
		long	attributes,
		WCharCP	dialogTitle,
		WCharCP	listLabel,
		WCharCP	fileFilter,
		WCharCP	defaultDirectory
	)

Displays a dialog box that allows the user to create and edit a list of files, directories or drives.

Parameters

[out]	lastInfoP	pointer to a FileListInfo structure returning the "state" of the file list dialog box upon termination of the box.
[in]	stringListP	Can contain a list of files, directories or drives. Before the list is edited, it is validated. If stringListP is NULL, a new empty list is created and edited.
[in]	attributes	specifies the types that can be selected, and can have the following values: FILELISTATTR_DRIVES Create/edit a list of drives FILELISTATTR_DIRECTORIES Create/edit a list of directories FILELISTATTR_FILES Create/edit a list of files FILELISTATTR_SORT Sort the output list alphabetically FILELISTATTR_UNIQUE Include only unique names FILELISTATTR_CASESENSITIVE Members in list are case sensitive. FILELISTATTR_MULTIPLE List can contain more than one member. FILELISTATTR_OPEN Only existing files are allowed in list. FILELISTATTR_CREATE Only non-existing files allowed in list. FILELISTATTR_OPENCREATE Allows both existing and non-existing files in list. FILELISTATTR_DEFAULT "OR" of FILELISTATTR_SORT, FILELISTATTR_UNIQUE, FILELISTATTR_MULTIPLE, FILELISTATTR_OPEN, and FILELISTATTR_FILES.
[in]	dialogTitle	the dialog box title.
[in]	listLabel	the title of the list box containing the list of files, directories, or drives to be edited if the FILELISTATTR_MULTIPLE attribute is set. Otherwise, it points to the label of the text input field.
[in]	fileFilter	the filter used to determine which files to include in the file list. It is useful when trying to limit the files displayed to a particular type. Simple wildcarding is allowed. An asterisk `*' will match any string and a question mark `?' will match any single character. If fileFilter is NULL, the filter string defaults to matching all files (*.*). This argument is valid only when the FILELISTATTR_FILES attribute is set.
[in]	defaultDirectory	the directory where the selection process starts. It can also be a configuration variable. In this case, the directory associated with that variable is used.

Returns

If successful, a pointer to a StringListP, otherwise NULL. If the input stringListP is NULL, the function returns a pointer to a newly created string list, otherwise, it fills in the stringListP passed in and returns that.

Remarks

Certain conflicts can arise and are handled as follows:

Only one of the following should be specified, but if more than one is, they take precedence in the following order:

• FILELISTATTR_DRIVES
• FILELISTATTR_DIRECTORIES
• FILELISTATTR_FILES

Only one of the following can be specified: FILELISTATTR_OPEN, FILELISTATTR_CREATE or FILELISTATTR_OPENCREATE. If none or more than one is specified, the default is FILELISTATTR_OPEN.

When a string list is passed as an argument (is not NULL), it must be validated so that it matches the attributes. Each member in the list is modified or deleted, depending on how it matches the attributes. For example, if FILELISTATTR_FILES and FILELISTATTR_OPEN are specified, all list members that are not existing files are deleted. If FILELISTATTR_UNIQUE is specified, all duplicates in the list are removed. If FILELISTATTR_CASESENSITIVE is omitted, all members are changed to lower case.

The list is edited through one of four dialog boxes. The box the user selects depends on whether the user chooses FILELISTATTR_MULTIPLE and also on whether the user is selecting files, directories, or drives. The dialog handler ensures that all selected or typed-in data fields conform to the desired attributes. If the user clicks CANCEL, the original, unchanged string list is returned.

See also

mdlDialog_fileOpenExt mdlDialog_fileCreate mdlDialog_fileOpen

int mdlFileList_fromString	(	StringListP *	fileList,
		WCharCP	fileName
	)

Searches the specified directories for files matching the criteria in fileName.

Directories are specified as paths preceding the filenames. It creates a string list in fileList that contains a list of files located from the string fileName. The individual file names can be extracted using mdlStringList_getMember.

Parameters

[out]	fileList	a pointer to a pointer to a string list. On successful return, the string list will contain the full file names of all the files that exist that satisfy the file name criteria in fileNameP. mdlFileList_fromString allocates the memory necessary to hold the string list.
[in]	fileName	a list of one or more path names (separated by semicolons), each of which may contain wildcard characters.

Returns

the number of file names contained in fileList.

Remarks

MDL programs must free the memory allocated by mdlFileList_fromString by calling mdlStringList_destroy.

See also

mdlFileList_edit

int mdlFileList_get	(	StringListP	stringListP,
		int	attributes,
		WCharCP	defaultDirectory,
		WCharCP	fileFilter
	)

Gets a list of files/directories/drives as specified by attributes, defaultDirectory and fileFilter.

Parameters

[in,out]	stringListP	should be created before this call. All current members are deleted, and the files matching the parameters are added.
[in]	attributes	accepts any (or all) of the following values: FILELISTATTR_FILES, FILELISTATTR_DIRECTORIES and FILELISTATTR_DRIVES. FILELISTATTR_FILES requests a list of files for the given directory. FILELISTATTR_DIRECTORIES requests a list of directories for the given directory. FILELISTATTR_DRIVES requests a list of drives associated with the system. If the programmer specifies more than one value on the line (by joining them with the logical OR operator), all requested information will be in the list.
[in]	defaultDirectory	the directory where the selection process starts.
[in]	fileFilter	to the filter to use for selecting files to include in the file list. It is valid only when the FILELISTATTR_FILES attribute is set.

Returns

SUCCESS if operation is successful. Otherwise, it returns a string list manager error.

Remarks

By default, the list is sorted.

See also

mdlFile_findFiles mdlFileList_edit