/ 
IUP-0.304
River stage zero No dependents
/ IUP::FileDlg

NAME

IUP::FileDlg - [pre-defined dialog] selecting files or a directory

DESCRIPTION

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

GTK
Motif
Windows

USAGE

CREATION - new() method

$filedlg = IUP::FileDlg->new( DIALOGTYPE=>"OPEN" );

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

NOTE: You can pass to new() other ATTRIBUTE=>'value' or CALLBACKNAME=>\&func pairs relevant to this element - see IUP::Manual::02_Elements.

ATTRIBUTES

For more info about concept of attributes (setting/getting values etc.) see IUP::Manual::03_Attributes. Attributes specific to this element:

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 IUP::Open), if the COM library was initialized with COINIT_MULTITHREADED prior to IUP::Open 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 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)

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 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. (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 iup-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
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 IUP::GLCanvas control to be mapped internally to the preview canvas. Notice that this is not a fully implemented IUP::GLCanvas that inherits from IUP::Canvas. This does the minimum necessary so you can use IUP::GLCanvas auxiliary functions for the preview canvas and call OpenGL functions. No IUP::Canvas attributes or callbacks are available.

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 undef 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

For more info about concept of callbacks (setting callback handlers etc.) see IUP::Manual::04_Callbacks. Callbacks specific to this element:

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)

Callback handler prototype:

sub file_cb_handler {
  my ($self, $file_name, $status) = @_;
  #...
}

    $self: reference to the element (IUP::FileDlg) 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 undef.

    • "FINISH" - when the dialog is closed. $file_name is undef.

    • "SELECT" - a file has been selected.

    • "OTHER" - an invalid file or a directory is selected. $file_name is the one selected. (Since iup-3.0)

    • "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 redrawn. Used only when SHOWPREVIEW=YES. If an invalid file or a directory is selected, file_name is undef.

HELP_CB

Action generated when the Help button is pressed.

NOTES

The IUP::FileDlg is a native pre-defined dialog that is not altered by SetLanguage.

To show the dialog, use function Popup.

The dialog is mapped only inside Popup, Map does nothing.

The GetFile function simply creates and popup a IUP::FileDlg.

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.

EXAMPLES

The element IUP::FileDlg is used in the following sample scripts:

SEE ALSO

Message, IUP, ListDialog, Alarm, GetFile, Popup

The original doc: iupfiledlg.html