CScreenSaver v1.08

Welcome to CScreenSaver, a collection of freeware MFC classes to encapsulate screen savers.

The screen saver library provided in the Windows SDK namely SCRSAVE.LIB is designed for SDK apps and cannot be used with traditional MFC apps. CScreenSaver provides an MFC class framework to allow screen savers to be built using "normal" MFC code.

Features

• Simple and clean C++ interface.
• The code uses standard MFC concepts to allow screen savers to be created. This includes CWinApp and CWnd derived classes and C++ virtual functions.
• The code is fully Unicode compliant, compiles cleanly at level 4, is /analyze clean and includes full SAL annotations.
• The code is multi-monitor aware.

Usage

• Create a standard MFC dialog based app using AppWizard.
• Add screensaver.cpp and screensaver.h to the project.
• Remove all the InitInstance code in your main applications cpp and h file.
• Also remove all the code related to the about dialog "CAboutDlg" which the App wizard will have created. Also removed all the document, view, frame and dialog classes which AppWizard will have created.
• Derive a class from CScreenSaverWnd and implement your specific screen saver drawing code by overriding CScreenSaverWnd::OnPaint (WM_PAINT). If your screen saver is going to use animations then override OnCreate (WM_CREATE) as you would usually do in MFC and create a WM_TIMER timer. Also override the OnTimer (WM_TIMER) message to handle the animation. Don't forget to release the timer in an override of OnDestroy (WM_DESTROY).
• Change your main app to be derived from CScreenSaverApp instead of CWinApp. Changes will need to be made in both you main applications cpp and h file.
• Call SetScreenSaverTemplate in your apps constructor to tell the framework what window to use for the screen saver. This is similar to the DocTemplate concept used in standard MFC SDI or MDI apps.
• Add a string to your rc file with a numeric value of 1. This is used as the name of your screen saver in the drop down selection combo in the control panel.
• That should be it, do a build of your exe, rename it to a .SCR extension and drop it into your Windows system directory. You should now be able to see it appear in the "Display" control panel applet.
• To see the code in action, have a look at the code in the sample screen saver in the module "app.cpp".

History

v1.08 (25 April 2022)

• Updated copyright details.
• Updated the code to use C++ uniform initialization for all variable declarations.

v1.07 (25 March 2020)

• Updated copyright details.
• Fixed more Clang-Tidy static code analysis warnings in the code.

v1.06 (23 December 2019)

• Fixed various Clang-Tidy static code analysis warnings in the code.

v1.05 (3 June 2019)

• Updated copyright details.
• Updated the code to clean compile on VC 2019

v1.04 (29 October 2018)

• Updated copyright details.
• Fixed a number of C++ core guidelines compiler warnings. These changes mean that the code will now only compile on VC 2017 or later.

v1.03 (30 January 2016)

• Updated copyright details.
• Remove VC 6 style classwizard style comments from the code
• Removed the code in the classes which supports Windows 9x.
• Updated the code to compile cleanly in VC 2005 - 2015.
• Updated the sample apps main icon.
• Added SAL annotations to all the code.
• CScreenSaverApp::InitInstance now calls the base class InitInstance implementation
• Removed unnecessary CScreenSaverWnd::m_bDialogUp member variable

v1.02 (18 July 2006)

• Code now uses new C++ style casts rather than old style C casts where necessary.
• Replaced calls to ZeroMemory with memset
• Reviewed TRACE statements for correctness
• Verified code compiles cleanly on VC 2005
• Addition of CSCREENSAVER_EXT_CLASS preprocessor macro to allow the classes to be easily added to an extension dll.

v1.01 (6 January 2006)

• Updated the copyright details and general code cleanup.
• CScreenSaverApp::ChangePassword method now returns a BOOL to indicate success.
• Fixed a number of issues when code is compiled using the "Detect 64 bit portability issues" in Visual Studio .NET 2003. To address this issue, it does mean that you require the Platform SDK to be installed and configured if you want to compile the code in Visual C++ 6.
• Removed some unnecessary comments from CScreenSaverApp::ShowConfigureDialog.
• Fixed a bug in CScreenSaveWnd::OnClose where it would incorrectly prompt for a password when the screen saver preview was being displayed and you were running on Windows 9x. Thanks to Jason Yang for reporting this bug.
• Updated the documentation to use the same style as the web site.

v1.0 (5 May 2000)

• Initial public release.

API Reference

The API consists of the following member functions of the classes CScreenSaverApp & CScreenSaverWnd

CScreenSaverApp::CScreenSaverApp
CScreenSaverApp::SetScreenSaverTemplate
CScreenSaverApp::ParseCommandLine
CScreenSaverApp::ProcessShellCommand
CScreenSaverApp::InitInstance
CScreenSaverApp::ShowConfigureDialog
CScreenSaverWnd::CScreenSaverWnd
CScreenSaverWnd::Create
CScreenSaverWnd::SetPreviewFlag
CScreenSaverWnd::GetBoundingRect
CScreenSaverWnd::GetWindowStyle
CScreenSaverWnd::GetExtendedWindowStyle

CScreenSaverApp::CScreenSaverApp

CScreenSaverApp::CScreenSaverApp();

Remarks

Standard constructor for the app class. This class is derived from the standard MFC class CWinApp and handles all the command line parsing for screen savers as well as the creation of the screen saver window. You should call SetScreenSaverTemplate in your derived instances. constructor

CScreenSaverApp::SetScreenSaverTemplate

void CScreenSaverApp::SetScreenSaverTemplate(CRuntimeClass* pRuntimeScreenSaverWnd);

Parameters

pRuntimeScreenSaverWnd a pointer to the RUNTIME_CLASS of the screen saver window class you want to use.

Remarks

You should call this function in your apps constructor to inform the framework what derived class of CScreenSaverWnd to use. To see an example of this, see the code in the sample screen savers app.cpp module.

CScreenSaverApp::ParseCommandLine

virtual void CScreenSaverApp::ParseCommandLine(CScreenSaverCommandLineInfo& rCmdInfo);

Parameters

rCmdInfo a reference to a simple derived class from CCommandLineInfo used to hold the results of the command line when it is parsed.

Remarks

This function parses the command line. It handles all the command line options appropriate for a screen saver (The command line to the screen saver is in fact the API used by screen savers) plus a few undocumented ones. This function is automatically called for you in the InitInstance method of CScreenSaverApp, so there should be no need to override this.

The command line parameters supported are:

CScreenSaverApp::ProcessShellCommand

virtual BOOL CScreenSaverApp::ProcessShellCommand(CScreenSaverCommandLineInfo& rCmdInfo);

Return Value

The return value should be used as the return value from the InitInstance method.

Parameters

rCmdInfo a reference to a the parsed command line info.

Remarks

Internally this function takes the command line information as parsed using ParseCommandLine and uses them to create the screen saver window as appropriate. It also handles bringing up the configure dialog and the change password dialog as appropriate. This function is automatically called for you in the InitInstance method of CScreenSaverApp, so there should be no need to override this.

CScreenSaverApp::InitInstance

virtual bool CScreenSaverApp::InitInstance();

Return Value

As per CWinApp::InitInstance.

Remarks

This derived method handles all the command line parsing and creation of the screen saver window for you. You should only need to override this function if you need to do something special in your app's initialisation.

CScreenSaverApp::ShowConfigureDialog

void CScreenSaverApp::ShowConfigureDialog(CWnd* pParentWnd);

Parameters

pParentWnd The window that any dialogs / window which this method shows should be modal with respect to.

Remarks

You need to override this function in your derived version of CScreenSaverApp to display some dialog to allow the settings specific of your screen saver to be configured. You also need to handle the persistence of the values. If you forget to override this function, then a simple message box will be shown to remind you to implement it. Normally what you should do here is display some type of CDialog or CPropertySheet derived window.

CScreenSaverWnd::CScreenSaverWnd

CScreenSaverWnd::CScreenSaverWnd();

Remarks

Standard constructor for the screen saver window class. Internally this just initializes protected member variables needed by the class.

CScreenSaverWnd::Create

virtual BOOL CScreenSaverWnd::Create(bool bChild, CWnd* pParentWnd);

Return Value

TRUE if the window was created successfully otherwise FALSE.

Parameters

bChild TRUE if the screen saver window should be created as a child (WS_CHILD). This is required when the screen saver is run in preview mode.

pParentWnd The parent window which the screen saver should use.

Remarks

This function creates the screen saver window. It is modelled on the CWnd method of the same name. The default implementation creates a screen saver of the appropriate size, window styles and the correct parent. It also initializes the window with an appropriate cursor and a black background.

CScreenSaverWnd::SetPreviewFlag

void CScreenSaverWnd::SetPreviewFlag(bool bPreview);

Parameters

bPreview TRUE if the screen saver window is being run in preview mode else FALSE.

Remarks

This function is used to inform the screen saver window that it is in preview mode rather than running for real. This function is called automatically for you in CScreenSaverApp. The window needs to be able to differentiate between the two modes of the screen saver so that it does not close down when you move the mouse over it when in preview mode.

CScreenSaverWnd::GetBoundingRect

virtual BOOL CScreenSaverWnd::GetBoundingRect(bool bChild, CWnd* pParentWnd, CRect& rRect);

Return Value

TRUE if the function succeeds otherwise FALSE.

Remarks

By default the rect returned will be the bounding rect for the virtual desktop. This ensures that in systems with multiple monitors, that the screen saver will span across all the monitors.

CScreenSaverWnd::GetWindowStyle

virtual DWORD CScreenSaverWnd::GetWindowStyle();

Return Value

The window styles to use when creating the screen saver window via the "Create" method.

Remarks

By default the style value returned will be setup depending on the command line send into the screen saver. For example when run in preview mode, the WS_CHILD style will be used while the WS_POPUP style will be used when run normally.

CScreenSaverWnd::GetExtendedWindowStyle

virtual DWORD CScreenSaverWnd::GetExtendedWindowStyle();

Return Value

The extended window styles to use when creating the screen saver window via the "Create" method.

Remarks

By default the style value returned will be setup depending on the command line sent into the screen saver. For example when in normal display mode, the WS_EX_TOPMOST will be used.

Contacting the Author

PJ Naughter
Email: pjna@naughter.com
Web: http://www.naughter.com
25 April 2022