IFileDialog

The IFileDialog class displays a file dialog for the user to choose a file. Once the user has chosen a file, you can use member functions of this class to retrieve information about the chosen file. You can use the following handlers to process the appropriate events for this control:

OS/2 Considerations

In OS/2 Presentation Manager, you can have modal windows that do not use the desktop as their parent. However, Presentation Manager can change the owner window of your dialog to something other than what you specified to prevent your application from being hung. See the Presentation Manager Programming Reference Volume 2 for more information under the topic WinLoadDlg.

The easiest way to ensure that your dialog is modal is to use the desktop as the parent and an application window as the owner. Presentation Manager only disables the owner window and its child windows (the child windows of the child windows, and so forth) while a modal dialog is displayed. If you specify 0 for parent, the desktop automatically becomes the parent of the dialog.


IFileDialog - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class. You cannot copy or assign IFileDialog objects. Constructing the IFileDialog object also shows the dialog. If there is a system error when constructing the object, showing the dialog, or in the use of the dialog, an exception is thrown. The error id in the exception is the system return code. You can also obtain this return code by calling the returnValue function.


[view class]
~IFileDialog
public:
virtual ~IFileDialog()

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IFileDialog


Overload 1
public:
IFileDialog( IWindow* parent, IWindow* owner, IHandler* handler, const Style& style = defaultStyle ( ), const Settings& settings = Settings ( ) )

You can construct an object of this class by using this constructor, which accepts a parent, owner, handler, style, and settings as parameters.

To add a IFileDialogHandler to a modal IFileDialog, you must specify the handler on the constructor. Once you create a modal IFileDialog, the dialog does not return control to the application until the user closes the dialog. At that time, it is too late to add a handler.

The parameters for this constructor are the following:

parent
The parent of the dialog box. If you specify 0, the desktop becomes the parent of the dialog.
owner
The owner window.
handler
A pointer to an IHandler object.
style
Use the styles provided by IFileDialog to specify the style. The default creates a modal dialog. To construct a modeless dialog, specify the modeless style. This parameter is optional.
settings
Use the settings provided by IFileDialog::Settings to specify the setting. This parameter is optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 2
public:
IFileDialog( IWindow* parent, IWindow* owner, const Settings& settings, const Style& style = defaultStyle ( ) )

You can construct an object of this class by using this constructor, which accepts a parent, owner, settings, and style as parameters.

The parameters for this constructor are the following:

parent
The parent of the dialog box. If you specify 0, the desktop becomes the parent of the dialog.
owner
The owner window.
settings
Use the settings provided by IFileDialog::Settings to specify the setting.
style
Use the styles provided by IFileDialog::Styles to specify the style. The default creates a modal dialog. To construct a modeless dialog, specify the modeless style. This parameter is optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 3
public:
IFileDialog( IWindow* parent, IWindow* owner, const Style& style, const Settings& settings )

You can construct an object of this class by using this constructor, which accepts a parent, owner, style, and settings as parameters.

The parameters for this constructor are the following:

parent
The parent of the dialog box. If you specify 0, the desktop becomes the parent of the dialog.
owner
The owner window.
style
Use the styles provided by IFileDialog to specify the style. The default creates a modal dialog. To construct a modeless dialog, specify the modeless style.
settings
Use the settings provided by IFileDialog::Settings to specify the setting.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Overload 4
public:
IFileDialog( IWindow* parent, IWindow* owner, const Style& style = defaultStyle ( ) )

You can construct an object of this class by using this constructor, which accepts a parent, owner, and style as parameters.

The parameters for this constructor are the following:

parent
The parent of the dialog box. If you specify 0, the desktop becomes the parent of the dialog.
owner
The owner window.
style
Use the styles provided by IFileDialog to specify the style. The default creates a modal dialog. To construct a modeless dialog, specify the modeless style. This parameter is optional.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Getting Information about the Chosen File

Use these members to get information about the file that was selected in the file dialog.


[view class]
fileName
public:
IString fileName(unsigned fileNumber = 0) const

Returns the fully qualified file name selected by the user.

fileNumber
The number indicating which file name you want. The default is 0. When you specify the style multiSelection for your IFileDialog object, set fileNumber to selectedFileCount minus 1 to ensure the correct number of files is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
saveAsEAType
public:
IString saveAsEAType() const

Returns the extended attribute (EA) for a Save As dialog. This is the type the user chose from the drop-down list box of EA types. If the user chose the EA type , a 0-length IString object is returned.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored

AIX Considerations

This function always returns an empty string.


[view class]
selectedFileCount
public:
unsigned selectedFileCount() const

Returns the number of files selected by the user.
Note: If you create the dialog with the style multiSelection, this number can be more than 1.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Getting Information about the Dialog

Use these members to get specific information about the dialog.


[view class]
backgroundColor
public:
virtual IColor backgroundColor() const

Gets the background color currently set for the file dialog frame window.

Supported Platforms

Windows OS/2 AIX
Yes Yes No


[view class]
buttonPressedId
public:
unsigned long buttonPressedId() const

Returns the ID of the push button used to close the dialog.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
id
public:
virtual unsigned long id() const

Returns the window identifier of the IFileDialog window.

Supported Platforms

Windows OS/2 AIX
Yes Ignored Yes


[view class]
isModeless
public:
bool isModeless() const

If this is a modeless dialog, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
pressedOK
public:
bool pressedOK() const

If the user ends the dialog by selecting the OK push button, true is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
returnValue
public:
long returnValue() const

If an error occurs, the return code is returned.

Supported Platforms

Windows OS/2 AIX
Yes Yes Ignored

AIX Considerations

This function always returns 0.

OS/2 Considerations

The return value is an FDS_ERR system return code. When a dialog fails, this value tells the application the reason for the failure.

Windows Considerations

The return value is a CDERR_ or FNERR_ system return code. When a dialog fails, this value tells the application the reason for the failure.


[view class]
cancel
public:
static const unsigned long cancel

Push button ID value returned when the dialog is dismissed by pressing the Cancel button.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
ok
public:
static const unsigned long ok

Push button ID value returned when the dialog is dismissed by pressing the OK button.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Setting Information about the Dialog

Use these members to set specific information about the dialog.


[view class]
setBackgroundColor
public:
virtual IFileDialog& setBackgroundColor( const IColor& color )

Sets the background color for the file dialog frame window.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setId
public:
virtual IFileDialog& setId(unsigned long newIdentifier)

Sets the window identifier of the window.

Supported Platforms

Windows OS/2 AIX
Yes Ignored Ignored


Styles

These style members provide a set of valid file dialog styles for the IFileDialog::setDefaultStyle function and for the constructors of the IFileDialog class.


[view class]
convertToArgList
public:
virtual IArgList convertToArgList( const IBitFlag& style ) const

Converts the IFileDialog styles to a Motif argument list that can be used to set the resources of the XmFileSelectionBox widget.

Supported Platforms

Windows OS/2 AIX
No No Yes


[view class]
convertToGUIStyle
public:
virtual unsigned long convertToGUIStyle( const IBitFlag& style, bool extendedOnly = false ) const

Converts a style object into a value appropriate for the presentation system. The default action is to return the base GUI styles for the platform. Extended styles, those defined by the application and the Open Class Library, are returned if you set extendedOnly to true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
defaultStyle
public:
static Style defaultStyle()

Returns the default style. The default style is classDefaultStyle unless you changed the style using setDefaultStyle.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
setDefaultStyle
public:
static void setDefaultStyle(const Style& style)

Sets the default style for all subsequent file dialogs.

style
Dialog style. Use the styles provided by IFileDialog to specify the default style.

This member function is not thread safe. In a multithreaded application, it should only be called when a conflict is not possible. A conflict can arise if you set the default style on one thread at the same time that it is being queried on another. In this situation, the query would take place while the style is in an unknown state.

When you create a window class and do not specifically specify window styles in the constructor, the Open Class Library queries the default style. Therefore, the only safe place to call this member function is when no other application threads that create windows are active.

Another way to avoid a conflict in a multithreaded application is to specifically specify window styles on window construction, rather than calling this member function.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
applyButton
public:
static const Style applyButton

Adds an Apply push button to the dialog. The apply button is processed only in a modeless dialog.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
classDefaultStyle
public:
static const Style classDefaultStyle

Specifies the original default style for this class, which is noStyle. This style results in a modal open dialog.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
filter
public:
static const Style filter

Specifies that the dialog use the union of the string filter and the extended-attribute type filter when filtering files for the Files list box. When you do not specify this style, the list box uses the intersection of the two by default.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
helpButton
public:
static const Style helpButton

Adds a Help push button to the dialog. This push button sends a help message to the owner of the dialog.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
includeEAS
public:
static const Style includeEAS

Specifies that the dialog always queries the extended-attribute information for files as it fills the Files list box. The default is to not query the information, unless the user selects an extended-attribute type filter from the dialog.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
modeless
public:
static const Style modeless

Specifies that the dialog is modeless. The constructor for a modeless dialog returns immediately. To determine which files were chosen by the user, create an IFileDialogHandler and use IFileDialogHandler::modelessResults.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
multiSelection
public:
static const Style multiSelection

Specifies that the Files list box for the dialog is a multiple-selection list box. If you do not specify this style, the default is a single-selection list box.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
noStyle
public:
static const Style noStyle

Disables all of the valid styles. Use this style only when you are not using any other styles.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
preload
public:
static const Style preload

Specifies that the dialog do the following:

By default, the volume label is blank and the initial directory is the root directory for each drive.
Note: This is not done by default because of potential delays in retrieving this information, which can be caused by network delays (for network drives) or hardware timeouts due to unavailable media.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Ignored


[view class]
selectableListbox
public:
static const Style selectableListbox

Enables the Files list box on a Save As dialog. If you do not specify this style, it disables the Files list box for a Save As dialog. Disabling is the default.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

Windows Considerations
This style suppresses the "Do you want to overwrite?" message box that Windows provides on save as dialogs. The file list is selectable regardless of the setting of this style.

Window Display

Use the window display members to manage the visibility of the file dialog.


[view class]
show
public:
virtual IFileDialog& show(bool showWindow = true)

Shows or hides the file dialog. If the flag is true, the file dialog is shown. If the flag is false the file dialog is hidden.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IFileDialog - Inherited Member Functions and Data

Inherited Public Functions

IFrameWindow
INotifier
IWindow

Inherited Public Data

IFrameWindow
IWindow
INotifier

Inherited Protected Functions

IFrameWindow
IWindow
INotifier

Inherited Protected Data

IFrameWindow