14.4.3 Configuration Dialog Box

A screen saver uses the ScreenSaverConfigureDialog function to process messages sent to the configuration dialog box. (A screen saver's resource-definition file includes the dialog box template.) The configuration dialog box is displayed when the user selects the Setup button from Desktop section of Control Panel.

The ScreenSaverConfigureDialog function saves its configuration information in the CONTROL.INI file. This configuration information is largely specific to the screen saver and may include such settings as speed, color, number of objects, and position.

The configuration information may also include password protection. When a screen saver is password protected, the user cannot deactivate it and return to the Windows session without typing the password in a dialog box. Adding password protection to a screen saver requires three dialog boxes: one for setting or changing the password, one for typing the password after the screen saver has been activated, and one for informing the user when the password is incorrect. These dialog boxes can be defined as follows:

#define         ID_OLDTEXT      100
#define         ID_NEWTEXT      101
#define         ID_AGAIN        102
#define         ID_PASSWORD     103
#define         ID_ETOLD        104
#define         ID_ETNEW        105
#define         ID_ETAGAIN      106
#define         ID_ETPASSWORD   107
#define         ID_ICON         108
#define         ID_PASSWORDHELP 109





#ifdef RC_INVOKED

DLG_CHANGEPASSWORD    DIALOG      8,16,174,79
FONT 8, "MS Sans Serif"
STYLE WS_POPUP | DS_MODALFRAME | WS_CAPTION | WS_SYSMENU
CAPTION "Change Password"
BEGIN
 LTEXT "&Old Password:", ID_OLDTEXT,       4, 3,80,14
 EDITTEXT  ID_ETOLD,                      84, 3,80,14, ES_PASSWORD
 LTEXT "&New Password:", ID_NEWTEXT,       4,21,80,14
 EDITTEXT  ID_ETNEW,                      84,21,80,14, ES_PASSWORD
 LTEXT "&Retype New Password:", ID_AGAIN,  4,39,80,14
 EDITTEXT  ID_ETAGAIN,                    84,39,80,14, ES_PASSWORD
 DEFPUSHBUTTON "OK", IDOK,                 4,59,40,14
 PUSHBUTTON "&Help", ID_PASSWORDHELP,             64,59,40,14
 PUSHBUTTON "Cancel", IDCANCEL,          124,59,40,14
END


DLG_ENTERPASSWORD     DIALOG      250,175,170,96
FONT 8, "MS Sans Serif"
STYLE WS_POPUP | DS_MODALFRAME | WS_CAPTION | WS_SYSMENU
CAPTION "<name of screen saver>"
BEGIN
 LTEXT "The screen saver you are using is password protected.
     You must type the screen saver password
     to turn off the screen saver.", -1, 31,3,140,40
 LTEXT "Password:", ID_PASSWORD,          31,45,40,14
 EDITTEXT ID_ETPASSWORD,                  71,45,80,14, ES_PASSWORD
 DEFPUSHBUTTON "OK", IDOK,                31,66,40,14
 PUSHBUTTON "Cancel", IDCANCEL,          111,66,40,14
 ICON "", ID_ICON,                         3, 3,32,32
END

DLG_INVALIDPASSWORD DIALOG  8,16,174, 79
FONT 8, "MS Sans Serif"
STYLE WS_POPUP | DS_MODALFRAME | WS_CAPTION | WS_SYSMENU
CAPTION "<name of screen saver>"
BEGIN
 ICON "", ID_ICON,                         3, 3, 0, 0
 LTEXT "Incorrect password;\n\nCheck your screen saver password,
     and try again.", -1, 40,3,130,40
 DEFPUSHBUTTON "OK", IDOK,               70,50,40,14
END
#endif

The preceding example wraps long lines in the DLG_ENTERPASSWORD and DLG_INVALIDPASSWORD dialog boxes. These lines should not wrap in your resource-definition file.

The ScreenSaverConfigureDialog function typically processes a message from a check box that specifies whether the screen saver is password protected and a message specifying that the user has chosen the button to set the password, as shown in the following example:

case ID_SETPASSWORD: {
    FARPROC fpDialog;

    if ((fpDialog = MakeProcInstance(DlgChangePassword,
            hMainInstance)) == NULL)
        return FALSE;
    DialogBox(hMainInstance, MAKEINTRESOURCE(DLG_CHANGEPASSWORD),
            hDlg, fpDialog);
    FreeProcInstance(fpDialog);
    SendMessage(hDlg, WM_NEXTDLGCTL, hIDOK, 1l);
    break;
}

case ID_PASSWORDPROTECTED:
    bPassword ^= 1;
    CheckDlgButton(hDlg, wParam, bPassword);
    EnableWindow(hSetPassword, bPassword);
    break;

The DlgChangePassword function displays the DLG_CHANGEPASSWORD dialog box.