IFileDialogHandler

The IFileDialogHandler class handles the various events that affect the file dialog.

You can create a handler derived from IFileDialogHandler and attach it to a file dialog. Call IHandler::handleEventsFor to pass the appropriate file dialog to the file dialog handler.
Note: To add a handler to a modal file dialog, you must specify a pointer to the handler using the IFileDialog constructor that accepts such a pointer as one of its parameters.

When the file dialog handler receives a file dialog event, it creates an IFileDialogEvent object and routes that object to the appropriate IFileDialogHandler virtual function. You can override these virtual functions to supply your own specialized processing of a file dialog event.

The return value from the virtual functions specifies whether the file dialog event is passed on for additional processing, as follows:

true
The file dialog event requires no additional processing. Do not pass it to another handler.
false
Pass the file dialog event to the next handler for additional processing, as follows:
  • If there is another handler for the file dialog, pass the file dialog event to the next handler.
  • If this is the last handler for the file dialog, call IWindow::defaultProcedure to process the file dialog event.


IFileDialogHandler - Member Functions and Data by Group

Constructors & Destructor

You can construct and destruct objects of this class.


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

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
IFileDialogHandler
public:
IFileDialogHandler()
You can only construct objects of this class using the default constructor, which does not accept any parameters.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Dispatch Events

These members determine if the event is one of the file dialog events. If it is, it calls the appropriate virtual function.


[view class]
dispatchHandlerEvent
protected:
virtual bool dispatchHandlerEvent(IEvent& event)

If a file dialog event is received, the appropriate virtual function is called.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


File Dialog Events

These members are called when a file dialog event occurs. Override these to provide your own processing.


[view class]
filter
protected:
virtual bool filter(IFileDialogEvent& event)

Lets you determine which file names appear in the list box. Use IFileDialogEvent::fileName to determine the file that is about to be added to the dialog's file list box. If you do not want the file to appear in the list box, call IEvent::setResult(false). If you do not want the event to be processed by any other handlers, return true.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
filterName
protected:
virtual bool filterName( const IString& fileName, IFileDialog* dialog )

Override this function to supply an easier way of filtering files. The supplied default function returns true. If you do not override it, nothing is filtered. If you do not want fileName to appear in the dialog, return false.

fileName
The name of the file you want to filter.
dialog
File dialog pointer. If you need to access the IFileDialog object itself, you can use the IFileDialog* pointer.

Supported Platforms

Windows OS/2 AIX
Ignored Yes Yes


[view class]
modelessApply
protected:
virtual bool modelessApply( IFileDialog* modelessDialog, const IString& appliedFileName )

Called when the Apply button of a modeless dialog is pressed. Allows you to update an application based on the current setting of the dialog without closing the dialog.

appliedDialog
Use the IFileDialog* pointer to get additional information about the dialog.
fileName
The name of the file that is currently selected in the dialog.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes

AIX Considerations
In a multiselection file dialog, only the "current" file name is provided.

[view class]
modelessResults
protected:
virtual bool modelessResults(IFileDialog* endingDialog)

Called when a modeless dialog is closed, even if the dialog is cancelled. This is done so that you can destroy the IFileDialog, if needed. Use IFileDialog::pressedOK to determine whether the user ended the dialog by pressing the OK push button.

If you need to destroy the IFileDialog object, do not delete the IFileDialog* pointer from within modelessResults. Instead, use the following:

endingDialog->setAutoDeleteObject(true)

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
validate
protected:
virtual bool validate(IFileDialogEvent& event)

Called when a user selects a file and presses the Enter key or double-clicks on a file in the list box. Use IFileDialogEvent::fileName to get the name selected by the user. If the name is unacceptable, call IEvent::setResult(false). In this case, the dialog is not ended. If you do not want the event to be processed by any other handlers, return true.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
validateName
protected:
virtual bool validateName( const IString& fileName, IFileDialog* dialog )

Override this function to supply an easier way of validating the user's selection. The supplied default function returns true. If you do not override it, nothing is invalidated. If fileName is unacceptable, return false.

fileName
The name of the file you want to validate.
dialog
If you want to inform the user why you rejected the name, use the IFileDialog* pointer in an IMessageBox constructor.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


Window Attachment

Use these members to attach a handler object to and detach it from a file dialog window.


[view class]
handleEventsFor
public:
virtual IFileDialogHandler& handleEventsFor( IFileDialog* fileDialog )

Attaches the handler to the specified file dialog passed in the argument.

Exception

IInvalidParameter A 0 pointer was passed instead of a valid IFileDialog*.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


[view class]
stopHandlingEventsFor
public:
virtual IFileDialogHandler& stopHandlingEventsFor( IFileDialog* fileDialog )

Detaches the handler from the specified file dialog passed in the argument.

Exception

IInvalidParameter A 0 pointer was passed instead of a valid IFileDialog*.

Supported Platforms

Windows OS/2 AIX
Yes Yes Yes


IFileDialogHandler - Inherited Member Functions and Data

Inherited Public Functions

IHandler

Inherited Public Data

Inherited Protected Functions

IHandler

Inherited Protected Data