IupFileDlg

IupFileDlg

Creates the File Dialog element. It is a predefined dialog for selecting files or a directory. The dialog can be shown with the IupPopup function only.

Creation

Ihandle* IupFileDlg (void); [in C]
iupfiledlg() -> (elem: ihandle) [in IupLua3]
iup.filedlg() -> (elem: ihandle) [in IupLua5]
filedlg() [in LED]

This function returns the identifier of the created dialog, or NULL if an error occurs.

Attributes

DIALOGTYPE: Type of dialog (Open, Save or GetDirectory)

Can have values "OPEN", "SAVE" or "DIR". Default: "OPEN".

TITLE: Dialog's title.

FILE: Name of the file initially shown in the "File Name" field in the dialog. If the user clicks OK, this attribute will contain the filename selected by the user.

FILTER: String containing a list of file filters valid in the native system, separated by ';' without spaces. Example: "*.C;*.LED;teste.*".

FILTERINFO: Filter's description.

EXTFILTER: (Windows Only) Defines several file filters. It has priority over FILTER and FILTERINFO. Must be a text with the format "Description1|filter1|Description2|filter2;filter3". The amount of descriptions and of filters is unlimited.
Example: "Text files|*.txt;*.doc|Image files|*.gif;*.jpg;*.bmp".

DIRECTORY: Initial directory. If not defined the dialog opens in the current directory. In Windows, if the current directory does not have files corresponding to the chosen filter, the directory opened will be "My Documents".

PARENTDIALOG: Makes the dialog be treated as a child of the specified dialog.

ALLOWNEW: Indicates if non-existent file names are accepted. If equals "NO" and the user specifies a non-existing file, an alert dialog is shown. Default: if the dialog is of type "OPEN", default is "NO"; if the dialog is of type "SAVE", default is "YES".

NOCHANGEDIR:  Indicates if the initial working directory must be restored after the user navigation. Default: "YES".

FILEEXIST: Indicates if the file defined by the FILE attribute exists or not. It is only valid if the user has pressed OK in the dialog.

STATUS: Indicates the status of the selection made:

"1": New file.
"0": Normal, existing file.
"-1": Operation cancelled.

VALUE: Name of the selected file(s), or NULL if no file was selected. In Windows there is a limit of 32Kb for this string.

NOOVERWRITEPROMPT do not prompt to overwrite an existant file when in "SAVE" dialog. Default is "NO", i.e. prompt before overwrite.

MULTIPLEFILES (Windows Only)

When "YES", this attribute allows the user of IupFileDlg in fileopen mode to select multiple files. 

The value returned by VALUE is to be changed the following way: the directory and the files are passed separately, in this order. The character used for separating the directory and the files is '|'. The file list ends with character '|' followed by NULL.

When the user selects just one file, the directory and the file are not separated by '|'.

Ex.: 
"C:\users\sab|a.txt|b.txt|" or
"C:\users\sab\a.txt" (only one file is selected)

The maximum size allowed by IupFiledlg for file return is 2000 characters. If the size exceeds 2000 characters, VALUE will return NULL.

FILTERUSED (Windows Only)

In a IupFileDlg, this attribute allows the user to select which EXTFILTER to use. It is also possible to retrieve the selection made by the user. Value: a string containing the number of the filter. 

SHOWPREVIEW (Windows Only)

A preview area is show inside the File Dialog. Can have values "YES" or "NO". Default: "NO". When this attribute is set you must use the "FILE_CB" callback to retreive the file name and the necessary attributes to paint the preview area. You must link with the "iup.rc" resource file so the preview area can be enabled.

PREVIEWDC, PREVIEWWIDTH and PREVIEWHEIGHT (Windows Only)

Read only attributes that are updated during the "PAINT" status of the "FILE_CB" callback. Return the Device Context (HDC), the width and the height of the client rectangle for the preview area.

Callbacks

FILE_CB: (Windows Only) Action generated when a file is selected.

int function(Ihandle *self, const char* file_name, const char* status); [in C]
elem:file(file_name, status: string) -> (ret: number) [in IupLua3]
elem:file_cb(file_name, status: string) -> (ret: number) [in IupLua5]

self: identifier of the element that activated the function.
file_name: name of the file selected.
status: describes the currect action. Can be:

"INIT" - when the dialog has started. file_name is NULL.
"FINISH" - when the dialog is closed. file_name is NULL.
"SELECT" - a file has been selected.
"OK" - the user pressed the OK button. If the callback returns IGNORE the action is refused and the dialog is not closed.
"PAINT" - the preview area must be repainted. This is used only when the preview area is active.

Notes

In the Windows driver, the FileDialog is not altered by IupSetLanguage.

To show the dialog, use function IupPopup. In Lua, use the popup function.

Example in C

filedlg = IupFileDlg();
IupPopup(filedlg, IUP_ANYWHERE, IUP_ANYWHERE);

Example in IupLua 3

filedlg = iupfiledlg{}
filedlg:popup(IUP_ANYWHERE, IUP_ANYWHERE)
  

Examples

See Also

IupMessage, IupScanf, IupListDialog, IupAlarm, IupGetFile, IupPopup