### 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.

~IFileDialogHandler

      public:
      virtual ~IFileDialogHandler()

Supported Platforms

  Windows | OS/2 | AIX
  Yes | Yes | Yes

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.

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.

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

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

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.

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

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

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.

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

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

  -     virtual ~IHandler()

  -     virtual IString asDebugInfo() const

  -     virtual IString asString() const

  -     virtual IHandler& disable()

  -     virtual IHandler& enable(bool enable = true)

  -     IHandler()

  -     bool isEnabled() const

#### Inherited Public Data

  - None

#### Inherited Protected Functions

  IHandler

  -     virtual IEventResult defaultProcedure(IEvent& event)

  -     virtual bool dispatchHandlerEvent(IEvent& event) = 0

#### Inherited Protected Data

  - None