4

IupFileDlg

@serial = 735

dialog

Description

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.

Include

iup.e

Namespace

iup

Signature

public function IupFileDlg()

Creation

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

Attribute

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 new dialog does not have the Help button neither filters. Also this new dialog needs CoInitializeEx with COINIT_APARTMENTTHREADED (done in IupOpen), if the COM library was initialized with COINIT_MULTITHREADED prior to IupOpen then the new dialog will have limited functionality. In Motif or GTK the dialog is the same, but it only allows the user to select a directory.

DIRECTORY: Initial directory. When consulted after the dialog is closed and the user pressed the OK button, it will contain the directory of the selected file.

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, for example "All Files|*.*".

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

FILEEXIST (read-only): 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;test.*". 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 [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: When "YES", this attribute allows the user to select multiple files when DIALOGTYPE=OPEN. 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)

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

NOOVERWRITEPROMPT: do not prompt to overwrite an existent file when in "SAVE" dialog. Default is "NO", i.e. prompt before overwrite. (GTK 2.8)

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

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

SHOWPREVIEW: A preview area is shown inside the file dialog. Can have values "YES" or "NO". Default: "NO". In Windows, you must link with the "iup.rc" resource file so the preview area can be enabled (not necessary if using "iup.dll"). Valid only if the FILE_CB callback is defined, use it to retrieve the file name and the necessary attributes to paint the preview area. (in Motif since 3.0)

Read only attributes that are valid inside the FILE_CB callback when status="PAINT": PREVIEWDC: Returns the Device Context (HDC in Windows and GC in UNIX) PREVIEWWIDTH and PREVIEWHEIGHT: Returns 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.

If the attribute PREVIEWGLCANVAS is defined then it is used as the name of an existent IupGLCanvas control to be mapped internally to the preview canvas. Notice that this is not a fully implemented IupGLCanvas that inherits from IupCanvas. This does the minimum necessary so you can use IupGLCanvas auxiliary functions for the preview canvas and call OpenGL functions. No IupCanvas attributes or callbacks are available. (since 3.0)

STATUS (read-only): Indicates the status of the selection made:

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

TITLE: Dialog's title.

VALUE (read-only): 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. When MULTIPLEFILES=Yes it contains the path and several file names separated by the '|' character.

MULTIVALUECOUNT(read-only): number of returned values when MULTIPLEFILES=Yes. It includes the path. (Since 3.14)

MULTIVALUEid (read-only): the same sequence returned in VALUE when MULTIPLEFILES=Yes but split in several attributes. VALUE0 contains the path (same as DIRECTORY), and VALUE1,VALUE2,... contains each file name without the path. (Since 3.14)

Callback

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. (Windows only in 2.x) 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. "SELECT" - a file has been selected. "OTHER" - an invalid file or a directory is selected. file_name is the one selected. (Since 3.0) "OK" - the user pressed the OK button. If returns IUP_IGNORE, the action is refused and the dialog is not closed, if returns IUP_CONTINUE does the same, but if the FILE attribute is defined the current filename is updated (since 3.8). "PAINT" - the preview area must be redrawn. Used only when SHOWPREVIEW=YES. If an invalid file or a directory is selected, file_name is NULL. "FILTER" - when a filter is changed. (Windows Only) (since 3.6) FILTERUSED attribute will be updated to reflect the change. If returns IUP_CONTINUE, the FILE attribute if defined will update the current filename.

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.

In Windows, the FILE and the DIRECTORY attributes also accept strings containing "/" as path separators, but the VALUE attribute will always return strings using the "\" character.

In Windows, the dialog will be modal relative only to its parent or to the active dialog.

In Windows, when using UTF-8 strings (UTF8MODE=Yes), attributes that return file names are still using the current locale, because the standard file I/O functions, like fopen, use ANSI file names. To use UTF-8 filenames (that can be lately be converted to UTF-16) set the global attribute UTF8MODE_FILE to Yes. In a specific case, the application can set before popup, and unset after, so for just that call will return in UTF-8.

When saving a file, the overwrite check is done before the FILE_CB callback is called with status=OK. If the application wants to add an extension to the file name inside the FILE_CB callback when status=OK, then it must manually check if the file with the extension exits and asks the user if the file should be replaced, if not then the callback can set the FILE attribute and returns IUP_CONTINUE, so the file dialog will remain open and the user will have an opportunity to change the file name now that it contains the extension.

Example

only partial success

include iup/iup.e  
IupOpen(NULL)  
  
atom dlg = IupFileDlg()  
 
function help_cb() 
	IupMessage("Help","Help Text") 
return IUP_DEFAULT 
end function 
 
IupSetAttribute(dlg, "DIALOGTYPE", "OPEN")  
IupSetAttribute(dlg, "TITLE", "IupFileDlg Test")  
IupSetAttributes(dlg, "FILTER = \"*.*\", FILTERINFO = \"All Files\"")  
IupSetCallback(dlg, "HELP_CB", Icallback("help_cb"))  
  
IupPopup(dlg, IUP_CURRENT, IUP_CURRENT)  
  
if not equal(IupGetInt(dlg, "STATUS"), -1) then  
  IupMessage("Filename",IupGetAttribute(dlg, "VALUE")) 
   
else  
  IupMessage("Cancel","Action cancelled") 
end if  
 
IupDestroy(dlg)  
   
IupMainLoop()  
IupClose()  

See Also