Sparkle ^{*Your "Build Flash Screen Saver" function.}

Table of contents

1: What is it?

2: This Archive Contents

3: Installation

    3a: Library (DLL) installation

    3b: Delphi component installation

    3c: Sparkle ActiveX installation

4: Testing (Evaluation)

5: Software development

    5a: Functions of Sparkle.dll

    5b: Properties and methods of Borland Delphi VCL component

    5c: ActiveX properties and methods

    5d: Return values of Build* methods and functions.

6: Order (Registration) and technical support

    6a: Online registration

    6b: Source code licensing

7: System Requirements

1: What is it?

"Sparkle" is a set of plain Windows DLL and two optional components created

    either to add a "Build Flash Screen Saver" feature to your existant product

    or to be an "engine" of your standalone "screen saver builder" application.

There are three ways to use Sparkle library depending on the programming language you prefer. You can use one the folowing:

    plain Windows DLL;

    VCL component for Borland Delphi;

    Sparkle ActiveX component.

Independently of the way you choose, when you add a very simple source code to your software, it will be able to build distributable screen savers from user's Macromedia Flash movies (*.swf -> *.exe|*.scr).

Each screen saver you build, supports:

    full-screen mode with user-supplied Flash movie;

    small preview window in the Windows Desktop Settings dialog;

    system password protection functionality;

    about box with user-defined text and clickable hyperlinks;

    simple installation wizard with user's ReadMe/License and Preview button;

    complete uninstallation from "Add and Remove Programs" CP applet.

All control and window captions of the generated screen saver can be localized to another languages.

You can download a sample screen saver from this location:

http://www.VANDOG.com/scrSample.zip

 « Contents 

2: This Archive Contents

After you download the archive, you need to UnZip or UnRar it into a separate folder. Your folder will contain the folowing subfolders after extraction:

 « Contents 

3: Installation

Depending on the programming language you prefer, you can install either pure Sparkle library (DLL) or the Delphi VCL component or the supplied ActiveX. Please open the appropriate folder and click Install.bat:

3a: Library (DLL) installation

Open the \Install\DLL folder and run Install.bat. Sparkle.dll will be copied to your System32 folder to be available from any place of your computer. The same operation is necessary when your application deploying on the target computer as the library should be accessible for it.

3b: Delphi component installation

As you are working with Flash and Delphi, the Shockwave Flash ActiveX should be already imported to your Delphi IDE. If it does not, please select "Main Menu" -> "Component" -> "Import ActiveX Control" and click "Install" button.

Close all the running copies of your Delphi IDE and open the \Install\VCL folder. Run Install.bat. TSparkle component will be installed in your Delphi IDE on the VANDOG tab and Sparkle.dll will be copied into System32 folder.

3c: Sparkle ActiveX installation

Close all the running copies of your development environment and open the \Install\ActiveX folder. Run Install.bat. Sparkle ActiveX will be registered in your system and Sparkle.dll will be copied to System32 as well. You will need to register Sparkle.ocx at the user's computer when you deploy your application.

Every mentioned folder contains the Uninstall.bat file that will completely undo the installation changes.

 « Contents 

4: Testing (Evaluation)

Test directory contains usage examples for better evalustion of this product. Please install the appropriate variant of use and then take a look at examples placed in the appropriate subfolders. For instance, if you are going to use "DLL approach" then open \Test\DLL example.

 « Contents 

5: Software development

It is recommended to use classic (DLL) approach to add "Build Screen Saver" functionality to your application. Use Sparkle.dll function calls when possible.

However, if your programming language is able to work with another supplied variants, you can use either ActiveX or Delphi component. In either way, the library file should be copied to a folder that will be accessible on the target computer, as the other variants are the "extended wrappers" of Sparkle.dll.

5a: Functions of Sparkle.dll

Each function in the library has two versions which are different only by parameter passing type.

Use the "Second2( )" versions to pass the function parameters by value.

Functions with "Simple( )" names will receive patameters by reference as it usually accepted in VB by default.

C++: All the file name parameters are the pointers to "standard" null-terminated ANSI strings.

Sparkle.dll contains two basic functions and additional procedure to register (unlock) it with your personal code.

BuildScreenSaver() / BuildScreenSaver2()

BuildScreenSaver function receives 4 parameters with file names of:

    output screensaver package ( *.exe | *.scr );

    ReadMe text location ( *.rtf | *.txt );

    About text location ( *.rtf | *.txt );

    Macromedia Flash movie ( *.swf );

If the Output screen saver has *.exe extension then you get an installation package for your screen saver with Create Desktop shortcut checkmark, Preview, Install and Uninstall features. If you want to create a simple screen saver without installer features then pass to the function a file name with *.scr extension.

ReadMe and About files can be as the rich-text formatted, as the simple text files. All hyperlinks will be highlighted and click able when your user see the screen saver dialogs.

The 4th parameter represents a Macromedia Flash movie that will be linked with package and shown in the screen saver.

Visual Basic declaration:

   Private Declare Function _
   BuildScreenSaver Lib "Sparkle" ( _
      strScreenSaver As String, _
      strReadMe      As String, _
      strAbout       As String, _
      strMovie       As String  _
   ) As Boolean  
          

VB example of use:

   '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
   ' BuildScreenSaver() function: Visual Basic Example.
   '
   '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
   ' REM: Please declare BuildScreenSaver function as it is shown 
   ' above. The library should be available to your application 
   ' at least by environment %PATH% variable. You can just copy 
   ' Sparkle.dll to the system folder (C:\WINDOWS or C:\WINNT).
   '       
   Sub BuildMyScreenSaver()
       Dim strScreenSaver As String, _
           strReadMe As String, _
           strAbout As String, _
           strMovie As String
   
       ' We want an Installation package (*.exe).
       ' Use *.scr extension for simple screen savers:
       strScreenSaver = "C:\Sample\ScreenSaver.exe"

       ' All links found will be highlighted and click able!
       strReadMe = "C:\Sample\ReadMe.rtf"
   
       ' Your texts may be also "simple" *.txt files, 
       ' but we use a rich-text formatted texts:
       strAbout = "C:\Sample\About.rtf"
   
       ' Finally, this is the Movie!!!
       strMovie = "C:\Sample\Movie.swf"
   
       ' Need I say something witty here?
       If BuildScreenSaver(strScreenSaver, _
                           strReadMe, _
                           strAbout, _
                           strMovie) = False Then
          MsgBox "BuildScreenSaver ERROR"
       End If
   
   End Sub
   
          

 BuildScreenSaverEx() 

This function is an extended version of the previous one.

Use it for localization purposes as well as for changes in the screen saver windows and control captions.

BuildScreenSaverEx also receives the same 4 parameters:

    output screensaver package ( *.exe | *.scr );

    ReadMe text location ( *.rtf | *.txt );

    About text location ( *.rtf | *.txt );

    Macromedia Flash movie ( *.swf );

.. as well as an additional parameters which are the captions of:

    main installation package window;

    "Create Desktop shortcut" checkmark;

    "Preview" button in the main installation window;

    "Install" button in the main installation window;

    "Cancel" button in the main installation window;

    "Uninstall" window caption;

    "Uninstall" window text (i.e. "Are you sure you want...?");

    "About" window;

    "OK" button in the About window.

Visual Basic declaration:

   Private Declare Function _
   BuildScreenSaverEx Lib "Sparkle" ( _
      strScrenSaver As String, _
      strReadMe As String, _
      strAbout As String, _
      strMovie As String, _
       strInstallWindowCaption As String, _
       strCreateDesktopShortcutCaption As String, _
       strPreviewButtonCaption As String, _
       strInstallButtonCaption As String, _
       strCancelButtonCaption As String, _
       strUninstallWindowCaption As String, _
       strUninstallWindowText As String, _
       strAboutWindowCaption As String, _
       strOKButtonCaption
   ) As Boolean  

          

   If you want to build an example of use, please have a look at the example
   of "BuildScreenSaver" function and create an extended version using 
   captions.
       

 Register() 

This procedure receives your personal unlock code. You will get it after the secure on-line registration described below.

This operation should be executed before you create a screen saver in order to hide registration reminder. In case of the passed code is incorrect, the output package will contain a registration reminder during the slideshow rotation.

If you want to create a shareware product using this DLL, you can get an additional level of your software protection. Just DO NOT pass the code to the library when your software is not registered by user yet.

Visual Basic declaration and example of use:

   Private Declare Sub _
   Register Lib "Sparkle" ( _
      strUnlockCode As String _
   )
          

   '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
   ' Register: Visual Basic Example.
   '
   '''''''''''''''''''''''''''''''''''''''''''''''''''''''''''''
   ' REM: Please declare "Register" Sub as it shown above. This 
   ' example uses BuildMyScreenSaver() function described in the 
   ' first example of this file.
   '
   Sub BuildRegisteredScreenSaver()
       Dim strUnlockCode As String
   
       ' This is a DUMMY unlock code.
       ' Please use your real code that will be 
       ' received after online registration.
       strUnlockCode = "1234ABCD"

       ' We use the 3rd function in the Sparkle.dll:
       Register(strUnlockCode)

       ' Build it! (see BuildMyScreenSaver() example)
       BuildMyScreenSaver()

   End Sub

          

5b: Properties and methods of Borland Delphi VCL component

TSparkle class derives from TWinControl class of Delphi VCL. It has many inherited properties which are described in the Dephi help file. There are the "published" properties which are visible in Delphi Object Inspector:

TSparkle component has properties for source and destination file names and Object Inspector shows a browse "(...)" button near the appropriate fields. You see the following properties in Delphi Object Inspector:

After you have filled out "source" and "destination" file names correctly, you need to execute Build() method of this component. You will get a ready-to-install screen saver package in the file with name stored at Sparkle1.ScreenSaver property.

Delphi example:

   //////////////////////////////////////////////////////////////
   // Drop a Sparkle component on your form and assign this code 
   // to the OnClick event of a button with name "Button1":
   //////////////////////////////////////////////////////////////
   procedure TForm1.Button1Click(Sender : TObject);
   begin
        // Fill out the source file names.
        Sparkle1.About       := 'C:\Sparkle\Test\About.rtf';
        Sparkle1.ReadMe      := 'C:\Sparkle\Test\ReadMe.rtf';
        Sparkle1.Movie       := 'C:\Sparkle\Test\Movie.swf';

        // Fill out the destination file name.
        Sparkle1.ScreenSaver := 'C:\Sparkle\Test\ScreenSaver.exe';

        // Change install window caption ("Captions" property example).
        Sparkle1.Captions.InstallWindow := 'My Flash Screen Saver Setup';

        // Build and Run the generated package:
        if Sparkle1.Build then
           begin
                WinExec(PChar(Sparkle1.ScreenSaver), SW_SHOW);
           end
        else
            begin
                 ShowMessage('ERROR!');
            end;

   end;

          

5c: ActiveX properties and methods

Sparkle ActiveX control is also supports the same input and output file names as well as Build() method. Please import the installed "Sparkle library" ActiveX in your software development environment and read the appropriate "About", "Movie", "ReadMe", "ScreenSaver" and "UnlockCode" descriptions of Delphi VCL component.

The following HTML example shows how to build a Sparkle screen saver stright from your browser. Please install the ActiveX and put real file names in Param strings.

   <HTML>
   <body>
   <H1> Sparkle library ActiveX Test</H1><p>
   <HR>
   <center>

   
   <OBJECT   id="Sparkle1"
             classid="clsid:DD58BF7B-6C23-467B-9F2B-9DC241267A18"
             align=center >

             <Param Name="ScreenSaver" Value="C:\Sparkle\Test\WEBMovie.exe">
             <Param Name="ReadMe"      Value="C:\Sparkle\Test\ReadMe.rtf">
             <Param Name="About"       Value="C:\Sparkle\Test\About.rtf">
             <Param Name="Movie"       Value="C:\Sparkle\Test\Movie.swf">

   </OBJECT>
   


   <br>
   
   [<a href="JavaScript:Sparkle1.Build()"> BUILD Screen Saver! </a>].

   <br>

   </center>
   </body>
   </HTML>

          

5d: Return values of Build* methods and functions.

After the function or method succeeds (i.e. returns "True"), you will get either a screen saver installation package (*.exe) or a simple screen saver file (*.scr) depending of the file extension you have passed in the "ScreenSaver" parameter. When the function fails, it returns the Boolean "False" value.

 « Contents 

6: Order (Registration) and technical support

If you are a software developer and interested to buy it for $72, click on the red link below to go to the registration page.

You'll get your personal unlock code, documented and royalty-free version of this package. You can also suggest a reasonable quantity of a new functions. No copyrights or links need for me, a single payment will be absolutely enough. You will use and distribute the library wherever you like and, finally, you can be sure in after-sale support and expect a bug-fixes on demand (for a reasonable time).

6a: Online registration

You can suggest a reasonable quantity of new functions after registration.

...Once again:

You can suggest a reasonable quantity of new functions after registration.

6b: Source code licensing

Borland Delphi 7 source code is available by request after registration.

 « Contents 

7: System Requirements

As the Sparkle library and ActiveX/Delphi components, as the produced screen savers are developed for use on the Windows 9X/ME/XP/2000 systems with Macromedia Flash Player installed.

Usually, if your system has Internet Explorer 4 and above, the Macromedia Flash Player is present. However, if you are not sure is it installed, please download it from this page: http://www.macromedia.com/support/flash/downloads.html

 « Contents