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]
iup.filedlg() -> (elem: ihandle) [in Lua]
filedlg() [in LED]

Returns the identifier of the created dialog, or NULL if an error occurs.

Attributes

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". Not used when DIALOGTYPE=DIR.

DIALOGTYPE: Type of dialog (Open, Save or Directory). Can have values "OPEN", "SAVE" or "DIR". Default: "OPEN".

In Windows, when DIALOGTYPE=DIR the dialog shown is not the same dialog for OPEN and SAVE, this dialog does not have the Help button neither filters. In Motif or GTK the dialog is the same, but it only allows the user to select a directory.

DIRECTORY: Initial directory.

In Motif or GTK, if not defined the dialog opens in the current directory.

In Windows, if not defined and the application has used the dialog in the past, the path most recently used is selected as the initial directory. However, if an application is not run for a long time, its saved selected path is discarded. Also if not defined and the current directory contains any files of the specified filter types, the initial directory is the current directory. Otherwise, the initial directory is the "My Documents" directory of the current user. Otherwise, the initial directory is the Desktop folder.

EXTFILTER: (Windows and GTK Only) Defines several file filters. It has priority over FILTERINFO and FILTER. Must be a text with the format "FilterInfo1|Filter1|FilterInfo2|Filter2|...". The list ends with character '|'. Example: "Text files|*.txt;*.doc|Image files|*.gif;*.jpg;*.bmp|". In GTK there is no way how to overwrite the filters, so it is recommended to always add a less restrictive filter to the filter list.

FILE: Name of the file initially shown in the "File Name" field in the dialog. If contains a path, then it is used as the initial directory and DIRECTORY is ignored.

FILEEXIST (out): 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. Not set when DIALOGTYPE=DIR or MULTIPLEFILES=YES.

FILTER: String containing a list of file filters separated by ';' without spaces. Example: "*.C;*.LED;teste.*". In Motif only the first filter is used.

FILTERINFO: (Windows and GTK Only) Filter's description. If not defined the filter itself will be used as its description.

FILTERUSED (in/out): (Windows and GTK Only) the index of the filter in EXTFILTER to use starting at 1. It returns the selection made by the user. Set only if EXTFILTER is defined.

MULTIPLEFILES: (Windows and GTK 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 '|'. When the user selects just one file, the directory and the file are not separated by '|'. For example:

"/tecgraf/iup/test|a.txt|b.txt|c.txt|" or
"/tecgraf/iup/test/a.txt" (only one file is selected)

In Windows the maximum size allowed for file name returned is 65Kb.

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

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

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

PREVIEWDC, PREVIEWWIDTH and PREVIEWHEIGHT: Read only attributes that are valid inside the FILE_CB callback when status="PAINT". Return the Device Context (HDC in Windows and GC in UNIX), the width and the height of the client rectangle for the preview area. Also the attributes WID, HWND, XWINDOW and XDISPLAY are valid and are relative to the preview area. (in Motif since 3.0)

SHOWHIDDEN: Show hidden files. Default: NO. (since 3.0)

SHOWPREVIEW: A preview area is shown inside the File Dialog. Can have values "YES" or "NO". Default: "NO". When this attribute is set you must set the "FILE_CB" callback to retreive the file name and the necessary attributes to paint the preview area. In Windows, you must link with the "iup.rc" resource file so the preview area can be enabled (not necessary if using "iup.dll"). Also the FILE_CB callback must be defined.

STATUS (out): Indicates the status of the selection made:

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

TITLE: Dialog's title.

VALUE (out): Name of the selected file(s), or NULL if no file was selected. If FILE is not defined this is used as the initial value. In Windows there is a limit of 32Kb for this string.

Callbacks

FILE_CB: Action generated when a file is selected. Not called when DIALOGTYPE=DIR. When MULTIPLEFILES=YES it is called only for one file. Can be used with SHOWPREVIEW=NO also.

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

ih: identifier of the element that activated the event.
file_name: name of the file selected.
status: describes the action. Can be:

• "INIT" - when the dialog has started. file_name is NULL.
• "FINISH" - when the dialog is closed. file_name is NULL.
• "INCLUDE" - before a file or folder is included in the list. If returns IUP_IGNORE the item is not included. (Windows Only)
• "SELECT" - a file has been selected.
• "OK" - the user pressed the OK button. If returns IUP_IGNORE the action is refused and the dialog is not closed.
• "PAINT" - the preview area must be repainted. Used only when SHOWPREVIEW=YES. If an invalid file or directory is selected, file_name is NULL.

HELP_CB: Action generated when the Help button is pressed.

Notes

The IupFileDlg is a native pre-defined dialog that is not altered by IupSetLanguage.

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

The dialog is mapped only inside IupPopup, IupMap does nothing.

The IupGetFile function simply creates and popup a IupFileDlg.

The FILE and the DIRECTORY attributes in Windows also accept string containing "/" as path separators. But the VALUE attribute will always return strings using the "\" character.

Examples

Ihandle *dlg = IupFileDlg(); 

IupSetAttribute(dlg, "DIALOGTYPE", "OPEN");
IupSetAttribute(dlg, "TITLE", "IupFileDlg Test");
IupSetAttributes(dlg, "FILTER = \"*.bmp\", FILTERINFO = \"Bitmap Files\"");
IupSetCallback(dlg, "HELP_CB", (Icallback)help_cb);

IupPopup(dlg, IUP_CURRENT, IUP_CURRENT); 

if (IupGetInt(dlg, "STATUS"))
{
  printf("OK\n");
  printf("  VALUE(%s)\n", IupGetAttribute(dlg, "VALUE")); 
}
else
  printf("CANCEL\n");

IupDestroy(dlg); 

Other: Browse Example Files

See Also

IupMessage, IupScanf, IupListDialog, IupAlarm, IupGetFile, IupPopup