Functions

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]fileNamereturns 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]rFileHoffers 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]dlogBoxIdis 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]suggestedFileNameis overridden if the defaultFileId parameter is provided and resource information for this parameter exists in the file specified by userprefH.
[in]filterStringis overridden if the defaultFileId parameter is provided and resource information for this parameter exists in the file specified by userprefH.
[in]defaultDirectorycontains 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]titleStringcontains the title of the Dialog Box
[in]defaultFileIdidentifies 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]userPrefHis 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]fileNamereturns 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]rFileHoffers 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]dlogBoxIdis 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]suggestedFileNameis overridden if the defaultFileId parameter is provided and resource information for this parameter exists in the file specified by userprefH.
[in]filterStringis overridden if the defaultFileId parameter is provided and resource information for this parameter exists in the file specified by userprefH.
[in]defaultDirectorycontains 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]titleStringcontains the title of the Dialog Box
[in]defaultFileIdidentifies 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]userPrefHis 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]fileNamereturns 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]rFileHoffers 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]resourceIdis 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]suggestedFileNamesuggests 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]filterStringcontains 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]defaultDirectorycontains 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]titleStringcontains 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]fileNamereturns 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]rFileHrFileH 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]resourceIdis 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]suggestedFileNamesuggests 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]filterStringcontains 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]defaultDirectorycontains 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]titleStringcontains the title of the Dialog Box.
[in,out]seedFileseedFile, 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]seedDirectorysee seedFile
[in]seedFiltersee 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]fileNamereturns the name of the file to be opened. The filename is guaranteed to list a valid existing file.
[in]rFileHoffers 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]resourceIdis 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]suggestedFileNamesuggests 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]filterStringcontains 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]defaultDirectorycontains 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]titleStringcontains 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]lastInfoPpointer to a FileListInfo structure returning the "state" of the file list dialog box upon termination of the box.
[in]stringListPCan 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]attributesspecifies 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]dialogTitlethe dialog box title.
[in]listLabelthe 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]fileFilterthe 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]defaultDirectorythe 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]fileLista 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]fileNamea 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]stringListPshould be created before this call. All current members are deleted, and the files matching the parameters are added.
[in]attributesaccepts 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]defaultDirectorythe directory where the selection process starts.
[in]fileFilterto 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

Copyright © 2017 Bentley Systems, Incorporated. All rights reserved.