Providing a Configuration Routine

The Screen Savers applet has a Setup button that is enabled for screen savers that support user configuration. The Screen Savers applet uses the DESCRIPTION line in your module-definition file to determine whether your screen saver supports configuration. “Creating Module-Definition and Resource Script Files,” later in this chapter, describes the required format of the DESCRPTION line.

When the user chooses the Setup button, the applet starts the screen saver with a special command-line switch. There are two ways that the screen saver is started; the command-line switches for these modes are as follows:

Switch Description

-s or /s Activates the screen saver.
-c or /c Displays the screen-saver configuration dialog box. The currently active dialog box is the parent for the configuration dialog box.

When the screen saver is started with the -c command-line switch, the WinMain function in SCRNSAVE.LIB displays the screen-saver configuration dialog box. For example, a screen saver called BOUNCER.EXE, started with the following command line, displays its configuration dialog box:

bouncer -c

If your screen saver supports user configuration, your source module must provide the following functions and dialog-box resource to handle configuration:

Name Description

ScreenSaverConfigureDialog Dialog-box function for a configuration dialog box.
RegisterDialogClasses Function that registers any special or nonstandard window classes needed for a configuration dialog box.
SCREENSAVERCONFIGURE Dialog-box template for a configuration dialog box, included in the resource-script file for the screen-saver application.

When the Screen Savers applet starts your screen saver with the configuration switch, the WinMain function in SCRNSAVE.LIB calls RegisterDialogClasses and then displays the configuration dialog box.

Summary: Defining Configuration Functions

Define the ScreenSaverConfigureDialog function as you would any dialog-box function. The Bouncer sample screen saver, included on the MDK disc, has a ScreenSaverConfigureDialog function that you can examine.

Your screen saver should save its configuration settings in the CONTROL.INI file. Use the WritePrivateProfileString and WritePrivateProfileInt functions to store your configuration information. Use the szAppName variable as your CONTROL.INI application heading.

Define the RegisterDialogClasses function as follows:

BOOL RegisterDialogClasses(HANDLE hInst)

The hInst parameter contains the instance handle for the screen saver. This is the same value contained in the hMainInstance global variable.

The following code fragment shows a RegisterDialogClasses function that registers a window class for a screen saver:

BOOL RegisterDialogClasses (HANDLE hInst)
{
    WNDCLASS wc;

        wc.hInstance = hInst;
        .
        .
        .
        return (RegisterClass(&wc));
}

If your configuration routine does not require any special window classes, your RegisterDialogClasses function can simply return TRUE.