Using Common Dialogs

Common dialog boxes make it easier for you to develop
applications. These dialog boxes provide common, consistent functions that applications can use to help the end user increase his productivity. Although a wide range of function is available, the simplest applications can make use of these to provide a consistent look-and-feel with a minimal coding effort.

The Open Class Class Library provides several classes to enable you to use common dialog boxes. This chapter covers these classes that provide access to the Open Filename dialog, the Save As Filename dialog, and the Font Selection dialog.

A dialog box is a special, short-lived window that you use to display information and receive input from the user in a structured dialog format. The information is typically related to a particular action being performed by the application.

If you develop portable applications, use a canvas for dialog windows.

Specifying File Dialog Information

Many applications work with information stored in files.
Whenever a user wants to retrieve information stored in a file, the user must select the name of the file from which to get the data. The same holds true when the user wants to save any work that is in progress for future reference.

The file dialog enables a user to specify a file to be opened or
a file name in which current work is to be saved. It provides basic functions that you can extend to meet the requirements of your application. These basic functions give users the ability to:

Display and select from a list of drives, directories, and files.
Enter a file name directly.
Filter the file names before they are displayed.
Display active network connections.
Interact with a single-selection or multiple-selection file dialog.
Interact with a modal or modeless file dialog.

The Open Class Library provides the IFileDialog and
IFileDialog::Settings classes to create and display file dialogs
in your application.

IFileDialog::Settings is a settings type class,
which defines data, styles, and attributes of a file dialog. You create IFileDialog::Settings objects and use them to create an IFileDialog object. This object governs the usage and appearance of the file dialog, as well as returning the file name choice (or choices in the case of multiple selection) that the user made.

Before you can create an IFileDialog, you first need to create an IFileDialog::Settings object. To create this settings object, follow these steps.

Create a default IFileDialog::Settings object, as shown in the following example:
```
    IFileDialog::Settings   fsettings;
```

Initialize this settings object using the member functions available. While the default settings may be suitable for many applications, most application developers modify one of more these settings. Some of the more common settings that you can change are the following:

Dialog type

The setOpenDialog and setSaveAsDialog member functions are used to specify the type of file dialog that will be displayed.

Note:

The default type of the file dialog is an Open dialog. If you want a Save As dialog, use the setSaveAsDialog member function.

Initial file name displayed

The setFileName member function is used to specify the initial file name that is shown when the file dialog is displayed.

Dialog position

The setPosition member function is used to specify the placement of the file dialog, relative to the window that owns the dialog.

Dialog title

The setTitle member function is used to specify the text that is displayed in the title bar of the dialog.

The following example shows some of these being initialized for the object created in the previous example:

    
    fsettings.setSaveAsDialog();            // The dialog type is Save As,
    fsettings.setFileName( "example.txt" ); // the initial filename displayed is example.txt,
    fsettings.setTitle( STR_MYAPP );        // and the title is loaded from a resource file

Now that you have a settings object created, you can create an IFileDialog object. There are several ways to construct an IFileDialog object, but in general you need to provide the owner and parent windows and a settings object. Optionally, you can provide different dialog styles to control the appearance and functionality of the dialog, but these have defaults and do not need to be modified for many applications. The IFileDialog object can be constructed using the following statements:

IFileDialog* fdialog = new IFileDialog( // Create file open dialog desktopWindow(), // parent is desktop this, // owner is me fsettings ); // use the settings defined above.

When the dialog is dismissed, you need to check the actions of the end user to determine if he has selected any file names to be used by your application. You can test the response from the file dialog using the pressedOK member function. This member functions returns true if the user ended the dialog by pressing the OK push button. It returns false if the user pressed Cancel or an error occurred. The test can be done with the following statement:

    if ( fdialog.pressedOK() )

If the end user pressed OK, then the file name (or names)
selected can be retrieved from the dialog using the fileName member function. This function returns the fully qualified file name, which includes drive and directory information. For a single selection style of the file dialog, the following statement is used:

    IString fname = fdialog.fileName();

For a multiple selection style of the file dialog, the following statements are used:

    
    int count = fdialog.selectedFileCount();  // Retrieve # of files selected
    int i;
    for ( i=1; i <= count; i++ )              // For each file selected,
    {                                         //  retrieve the fully-qualified
      IString fname = fdialog.fileName(i);    //  file name into a string
      ...                                     // Process it
    }                                         //  and then get the next one

For a complete code sample, see the openFile member function in the ahello6.cpp file (Hello World version 6). The Hello World samples are in the \samples\ioc directory.

Creating a File Dialog

The following example demonstrates creating both an Open file dialog and a Save As file dialog.

Define the main window and a command handler to handle menu command events, as follows:

class MyCommandHandler : public ICommandHandler {   public:
     MyCommandHandler( MyWindow* theOwner );
     virtual
        ~MyCommandHandler();
     virtual bool
        command( ICommandEvent& event );
 
  private:
     MyWindow
       *owner,
       *parent;
};
 
class MyWindow : public IFrameWindow
{
   public:
      MyWindow();
 
   private:
       ITitle title;
       IMenuBar menu;
       MyCommandHandler cmds;
};

Create the main window:

MyWindow::MyWindow() :
          IFrameWindow( ID_MAIN ),
          title( this, "File Dialog Example" ),
          menu( ID_MENU, this ),
          cmds( this )
{
  cmds.handleEventsFor( this );
  setFocus().show();
}

Create the file dialogs based on the menu command events:

bool MyCommandHandler::command( ICommandEvent& event )
{
  bool
    rv = false;
  IMessageBox
    msgbox( owner );
 
  switch ( event.commandId() )
  {
    case ID_FILE_OPEN :
    {
      IFileDialog::Settings fileSettings;
      fileSettings.setTitle( "Open the Specified File" ); // Set open dialog title
      fileSettings.setFileName( "*.cpp" );                // Set file names to *.cpp
      IFileDialog filedlg( parent, owner, fileSettings );
      if ( filedlg.pressedOK() )
      {
        msgbox.show( IString( "You selected the file '" )
                     + IString( filedlg.fileName() )
                     + IString( "'." ),
                     IMessageBox::okButton );
      }
      break;
    }
 
    case ID_FILE_SAVEAS :
    {
      IFileDialog::Settings fileSettings;
      fileSettings.setTitle( "Save to the Specified File" );  // Set save-as dialog title
      fileSettings.setFileName( "noname.txt" );              // Set file name to noname.txt
      fileSettings.setSaveAsDialog();
      IFileDialog filedlg( parent, owner, fileSettings );
      if ( filedlg.pressedOK() )
      {
        msgbox.show( IString( "You saved the file '" )
                     + IString( filedlg.fileName() )
                     + IString( "'." ),
                     IMessageBox::okButton );
      }
      break;
    }
  }
  return rv;
}

The following figure shows the file dialog created using the preceding example:

Specifying Font Dialog Information

Many applications display information to users in a variety of ways, many of them textually based. A common action that users perform is selecting a font with which to display or print this textual information. A font represents all of the characters of one style of type in one size.

The font dialog provides a dialog you can implement to enable users to view and select the font family names, styles, and sizes available in an application. It provides basic functions that you can extend to meet the requirements of your application. These basic functions give users the ability to display and select from a list of the following:

Font family names installed on the system
Styles for each font
The available sizes for each font
The emphasis styles available for each font.

In addition, users can view their selections using a sample character string in a preview area, and interact with a modal or modeless font dialog.

The Open Class Library provides the IFontDialog class to create and display font dialogs in your application.

IFontDialog::Settings is a settings type class that defines data, styles and attributes of a font dialog. You create IFontDialog::Settings objects and use them to create an IFontDialog object. This object governs the usage and appearance of the font dialog, as well as returning the font chosen by the user.

Before you can create an IFontDialog, you first need to create an IFontDialog::Settings object. To create this settings object, follow these steps:

Create an IFontDialog::Settings object, passing it the initial font to be used, as shown in the following example:

    
    IFont tempFont( &hello );        // Create a font from the hello window
    IFontDialog::Settings            // Create the initial settings object
      fsettings( &tempFont );        //  from the font

Initialize this settings object using the many member functions available. While the default settings are suitable for many applications, most application developers modify one of more these settings. Some of the more
common settings that you can change are the following:

Preview text

The setPreviewText member function is used to specify the text string that is used to demonstrate how the selected font will look if selected.

Dialog position

The setPosition member function is used to specify the placement of the font dialog, relative to the window that owns the dialog.

Dialog title

The setTitle member function is used to specify the text that is displayed in the title bar of the dialog.

The following example shows these being initialized for the object created in the previous example:
```
    fsettings.setPreviewString( "ABCDabcd" );  // Use this string to demo type,
    fsettings.setPosition( IPoint( 50, 20 ) ); // position at 50,20 in owner,
    fsettings.setTitle( "Choose font" );       // and the title is Choose font
```

Now that you have a settings object created, you can create an IFontDialog object. There are several ways you can construct an IFontDialog but in general, you need to provide the owner and parent windows and a settings object. Optionally, you can provide different dialog styles to control the appearance and functionality of the dialog, but these have defaults and do not need to be modified for many applications. The IFontDialog object can be constructed using the following statements:

    
   IFontDialog* fdialog = new IFontDialog(  // Create font dialog
      desktopWindow(),                       // Parent is desktop
      this,                                  // Owner is me
      fsettings );                           // Use the settings defined above

When the dialog is dismissed, you need to check the actions of the end user to determine if he has selected a valid font to be used by your application. You can test the response from the font dialog using the pressedOK member function. This member functions returns true if the user ended the dialog by
pressing the OK push button. It returns false if the user pressed
Cancel or an error occurred. The test can be done with the
following statement:

    if ( fdialog.pressedOK() )

If the end user did press OK, the tempFont object that was used to initialize the settings object is automatically updated to be an IFont object that reflects the users selection. Your application can now use this font to change how you display textual information to your users. This is done using either the setWindowFont member function (a function of IFont which accepts a window to apply the font to) or the setFont member function (a function of IWindow which accepts a font to apply to the window). can be used. The latter is shown in the following statement:

    hello.setFont( &tempFont );

Creating a Font Dialog

The following section describes how to create a font dialog
using the Hello World version 6 application. The following code comes from the ahellow6.cpp file:

AHelloWindow &
  AHelloWindow :: setHelloFont()                             
{                                                                        
/*------------------------------------------------------------------------|
|  Set the text in the information area from the font dialog information  |
|    string in the resource file.                                         |
|  Create a font from the current font of the hello static text object.   |
|  Create a font settings object from the tempFont object.                |
|  Set the title to be used in the font dialog from a string resource in  |
|    the resource file.                                                   |
|  Start the font dialog by creating an IFontDialog object.  The font     |
|    dialog is created as a modal dialog window with the desktopWindow    |
|    as the parent, the AHelloWindow frame as the owner, resetButton      |
|    style which supplies the user with a way to reset the fields in the  |
|    dialog, and the font settings that were just created.                |
|------------------------------------------------------------------------*/
  infoArea.setDefaultText(STR_FONTDLGT);
  IFont tempFont(&hello);                                            
  IFontDialog::Settings fontSettings(&tempFont);         
  fontSettings.setTitle(IResourceId(STR_FONTDLGT));                      
  IFontDialog fontDialog( desktopWindow(), this,                         
                          IFontDialog::resetButton, fontSettings);        

/*------------------------------------------------------------------------|
|  If the user pressed OK in the font dialog, then change the font for    |
|    the hello IStaticText object using the tempFont object that was set  |
|    by the font dialog.                                                  |
|  Reset the information area inactive text.                              |
|------------------------------------------------------------------------*/
  if (fontDialog.pressedOK())
  {
    hello.setFont(tempFont);
  }
  infoArea.setDefaultText(STR_INFO);
  return (*this);                       // Return a reference to the frame
}; /* end AHelloWindow :: setHelloFont() */

In the preceding sample, the font in an IStaticText control is changed to the font the user selects from an IFontDialog. We accomplished this by doing the following:

Creating an IFont object called tempFont that represents the font currently being used by the IStaticText control pointed to by hello
Passing a pointer to the tempFont object on the constructor to an IFontDialog::Settings object called fsettings
Passing the fsettings object on the IFontDialog constructor

Because fontSettings is constructed using tempFont, the IFontDialog initially displays the name, style, size, and emphasis associated with tempFont (for example, the font currently used by the IStaticText object). If the user dismisses the IFontDialog by pressing OK, then tempFont automatically updates itself to reflect the font the user chose via the IFontDialog. The setFont member function can be used to actually change the font of the IStaticText control to tempFont.

The following shows an example of a font dialog:

Hello World Version 4: Adding Dialogs and Push Buttons
Constructing Fonts
Layout Using Canvas Controls

ICanvas
IFileDialog
IFont
IFontDialog