The quickest way to introduce yourself to Scrplus is to write an application. This tutorial guides you through the creation of a "Hello World" saver, that bounces the text around the screen. You may wish to print out this tutorial.
Do File | New, and choose the New Saver expert. The expert is shown to the right.
The new saver project will be created. If you're curious, you can read more about the expert's options.
Have a quick glance at the components in Scrplus. You can hover your cursor over
a component to see its name, and click on it for more information. The Scrplus
tab of components has general system ones. Only the first five relate to screen savers
directly — the others are for DirectDraw and OpenGL.
The ScrControls tab contains special 'value-aware' controls. You'll use these
in your configuration dialog:
Settings make a saver fun. Think of the 'Flying Toasters' screen saver. At first glance it just has pieces of toast flying around the screen. But the configuration dialog has an option for how burnt the toast is! And it's this setting, pointless and amusing as it is, that turns the screen saver into a work of genius.
Ranges make settings fun. It would be dull just to specify the number of toasts on-screen. But if you can choose between lonesome-toastsome, light-breakfast, lots-of-toast and humongous-toast-nightmare then it becomes funny.
Scrplus makes it easy to put in settings, and easy to describe ranges. Most of the work can be done visually. In this tutorial we will have a piece of text bouncing around the screen, with a setting for how fast it bounces.
Scrplus uses automated variables. These go on the Main control form. They automatically load and save themselves from and to the registry, and they have other features to make them link easily to the configuration dialog and to the main saver form. We will use an integer automated-variable to represent the speed of the thing, and give it some ranges of values.
ScrVariable component on
your main control form. (From the Scrplus component tab)In fact, the ScrVariable isn't a real component. It's only there as a stand-in for
the different types of automated-variable you can have. These include
integers, booleans, doubles, strings, fonts and more.
This automated-variable will have three ranges of speeds. We're going to use a ScrTrackbar in the configuration dialog to alter the speed, and also have a text label underneath it naming the range it's in.
The next task is to put in a trackbar control in the configuration-dialog, to change the Speed.
ScrTrackbar component
on the form, and two normal Labels.
We will link up this ScrTrackbar to the Speed value on the main control form. The ScrTrackbar is a sort of data-aware component. Any changes to the value will be reflected in the trackbar; and any changes in the trackbar will also change the underlying value.
All controls on the ScrControls page have this Controller property. In the drop-down list, they show whichever values are acceptable for 'controlling' this control. For instance, the trackbar could be controller by an integer (as we're doing here) or by a double, but can't be controlled by a string or a font.
Next we're going to make the bottom text label display the currently selected range. This isn't quite as easy, because the standard BCB Label control does not have a Controller property! We're going to do it with a ScrViewerController component. This component has a property to say which automated-variable it should get its data from, and which label it should display to.
ScrViewerController
component from the ScrControls tab.
There are several different viewer-controllers. Each one accepts input from a certain type of value, and outputs to a certain type of control. So the DoubleText viewer-controller links a double automated-variable to a text-control such as a Label or a Panel or a Button. The IntegerRangeText that we are using displays not the integer value itself, but rather the range that it's in.
One final thing, before finishing with the configuration dialog, is to put in a little preview. This will give the user instant feedback on the effect of changing speed. This is done with a ScrPreview control.
ScrPreview
component from the Scrplus tab.
When the configuration dialog is started, Scrplus will automatically create an instance of your Saver Form inside this little preview. If you wanted to be fancy you could have first put a ScrMonitor control down, and then put the preview inside that.
Now that we've done the configuration dialog, it's time to put our animated effect in the saver form.
This saver is going to display a piece of text which bounces around the screen. In the constructor we're going to create this text as a bitmap. There will be a timer component. Every timer tick, the bitmap will be bounced around a little.
The Image is going to contain a bitmap, which we're going to move around the screen ever Timer tick. The bitmap will be of a piece of text.
Recall that the same Saver form is going to be used both for the miniature preview, and also for full-screen saver operation. We're going to have to write code that scales well for the different sizes. In particular, we'll choose a font-height that is a given fraction of the form's ClientHeight. (If scaling is too difficult, it's also possible to use an entirely different form for the previews).
Notice how we refer to MainForm->Speed->Value, to get the current speed. If the user is in the configuration dialog and they change the trackbar, then the Speed automated variable will get updated instantly. And our timer code will use this updated value immediately. That's how we get instant feedback in the preview window.
And that's it! Actually, before testing it, we're going to make one further change: we'll let the user change the font.
We now add a 'font' setting to the saver, so that the user can choose a font for the Hello World message.
ScrVariable component.
We're going to have to add a little code for setting the font in the configuration dialog. That's because there isn't a 'font-setter' automated control. (There was a trackbar-automated control which we used for the speed: that's why we didn't need to write any code before).
The code is straightforward. When you click on the button it retrieves the currently selected font. Then it runs the dialog. Then it stores the new font back in the automated variable.
Remember that these automated variables will save themselves into the registry automatically for you, and load themselves from the registry, even for things as complicated as a font. You don't need to worry about registry problems at all.
There's a slight complication with changing the font. In our saver form we created a bitmapped image of the text in the constructor. But if what if the user changes the font? Then our bitmapped image will be out of date. We need a 'notify' mechanism, to notify us of any changes to the font, so we can recreate a new bitmapped image.
(This complication didn't arise before with MainForm->Speed->Value. That's because then we just referred to the automated variable every time we need it. But it does crop up now. In general, whenever you have any sort of internal data structure used by your saver form, you'll need to use the technique described below. Our image is one such internal data structure. Another internal data structure is when you precalculate some sort of lookup table based on a user setting.)
We use a ScrValueController non-visual component. You link it up to an automated variable, such as MainForm->Font. Whenever the automated variable changes, the ScrValueController fires an OnChange event. In response, we will recreate our bitmap image.
ScrValueController component.
The saver is now finished. All that remains is testing, debugging and publishing it.
A windows screen saver is expected to run in several different modes. The important ones are outlined below. You should check that your saver does all of them correctly.
Scrplus has some built-in debugging aids. Most important of all is the DebugLevel. Normally, a saver is expected to run as a full-screen topmost window, and to ignore everything else. If your program crashes, or you encounter a breakpoint, then you'd be stuck! Because you couldn't get back to C++Builder, and you couldn't terminate the saver.
Therefore, Scrplus savers are created to run at dlFull DebugLevel. That means that it runs full-screen, but is not topmost and is not exclusive. This makes it easier to debug.
The ScrControl component also has properties DebugLog and DebugLogLevel, for keeping a log of the saver's execution. You can read more about debugging facilities.
There are a number of blank icons provided in the Scrplus\lib directory. You might want to start with one of these. They are:
Hippy age: strange visions of the future.
Industrial age: block machinery.
Information age: clean, simple, elegant.
Telepathic age: single-minded focus.
As long as you are programming savers for hobby or for fun, you may distribute any Scrplus screen saver that you create with no restrictions. I keep a web page of screen savers. If you'd like me to add your saver, I'd be glad to! Email me..
If you're distributing savers for commercial gain, or as corporate advertising, then you must have purchased a Scrplus license. This and the previous paragraph are informal guidelines only. For the formal statement of what's free and what's not, and for purchasing information, visit Scrplus homepage.