  CARDENG: A post card engine as a freeware ..............
         releases 1.0
         By Paul-henri FERME
         paul_henri@compuserve.com


Overview and start-up:    See readme.txt
----------------------

You need to be familiar with delphi to use it as there is no visual interface
for my objects. This save a lot of exe space.
It has also an advantage. As there is no component to be added to the delphi
library. This will save you a lot of time!!!

All you need is  basic delphi knowledge and a little object programming understanding to
use the object although the example will guide you.

Cardeng Key features:
--------------------

1) Very compact code achieved by not using any VCL graphic objects and direct call
windows API instead and also using fast LZH compression algorithm for all mid and bmp
files.

2) Single contained exe with no additional files required.

3) Easy to use Non-visual object to handle all tasks.


By the way you need to try write software without the VCL to understand how
valuable is the VCL in hiding all this nasty Device Context creation and release.
These guys from Microsoft really made this complex...


File List
---------

Cardengr.dpr   Main program
Userpar.pas    User definition script  { this is the only file to be modified }
Uscreen.pas    Anim and Screen objects
Ucardut.pas    Routines to create a bitmap from a file or from ressource
Ucardmsg.pas   Error code number
Ucardmasg.rc   Error strings
Uerror.pas     Error routines
Umidi.pas      Midi routines
Usprite.pas    Sprite objects
UScroll        Scrolling text object
LZRW1KH.PAS    Compression algorythm
Ucompstr.pas   Compression object
CardRes.rc     resource scipte for compressed bitmaps, midi and wave files
CardEng.ico    Icon for this program
readme.txt     Quick starter
cardeng.txt    this file

Additional software
-------------------

compr.exe      Program will call LZRW1KH and produce a compressed file
               with extension zzz. This files must then  be compiled into the ressource
               file Cardres with BRCC. The cardeng engine will use them automatically.
               The LZW1KH routines are free, very fast and do not need any DLL as they are
               witten in native Turbo pascal.
TestGif.exe     Excellent Freeware available from Reiner SterKenburg that will read a GIF
               file. I just add a command to save the gif file as a bitmap. This will create
               a file in a format that CardEngg can use. The format is simple: all
               succesive image from the animated GIF are aligned from left to right.
               Therefore if you GIF is 100x80 pixels with 5 animations you will get a
               composite bitmap of  500x80 that CardEng can use.


Mains Help file
---------------


************ TAnim **************

A Tanim is a list of TScreen. Each screen will be run in the sequence they have
been created via the addscreen command. It will run for a fixed duration or
until the user press a key. TAnim is activated via its RunAnim command.

Main properties and methods are:

  constructor create;
           Called  from cardeng.dpr.

  destructor destroy;override;
           Object released in cardeng.dpr.

  procedure RunAnimation(hdc:Thandle);
           Will run the animation. Called in cardeng by main timer.

  procedure AddScreen(Ascreen:TScreen;hdc:Thandle);
           Method to add a new screen to the anim list.

  property Autorepeat:boolean read FAutorepeat write FAutorepeat;
           If true animation will start again with screen otherwise anim will stay with
           the last screen forever.

  property OnScreenEnds:TNotifyEvent read FonScreenEnds write FonScreenEnds;
           Event called when a screen ends.

  property List:Tlist read FList;
           List of screen which form the animation.

  property Active:integer read Factive;
           Number of the screen being played. Starts with 0.

  property KeyPressed:boolean read GetKeyPressed write FKeyPressed;
           True if a key is pressed by the user. This is reset when a new screen
           is displayed.

************ TScreen **************

A TScreen consist of:
            - A midi file that is played during the screen either once or continuously
            - A background bitmap loaded when the  screen starts
            - A graph manager which contains all the animated part of the screen

      Main properties and methods are:

  constructor create(Backgroundres,Midires:string; Midirepeat:boolean;Duration:Longint);
              Backgroundres:  Name of the background bitmap resource in cardres.rc
              Midires:  Name of the midi file  resource in cardres.rc
              Midirepeat: if true midi files will repeat otherwise it is played only
                          once.
              Duration: If 0 the screen will stop when a key is pressed. otherwise this
                         parameter reprsents in msecond the time the screen will be on.

  property BitmapWindow:Hbitmap read FBitmapWindow;
  property BitmapWindowBgd:Hbitmap read FBitmapWindowBgd;
              Handle to respectively the bitmap displayed and the backgound bitmap;

  property Duration:longint read FDuration;
               see create.

  property GraphMng:TgraphMng read FGraphMng write FGraphMng;
               reference to the graphmng. See below. There is always a single graphmng
               per screen.

  property Midi:Tmidi read Fmidi;
               reference to the midi object.

  property MidiRepeat:boolean read FMidiRepeat;
               see create.

************ TGraphMng **************

A TGraphMng is a list of Tgraph. It  provides fast and flicker free
animation by performing all bitmap update in a buffer and blitting to the screen
only the part of the buffer which have been modified.

      Main properties and methods are:

 constructor create;
 destructor destroy;override;
    Called by Tscreen.

 procedure AddGraph(AGraph:TGraph);
           Add a new graph to the list.

 procedure RedrawScreen(hdc:Thandle);
           Main procedure called by timer to diplay all elements.

 property Count:integer read GetCount;
          Number of graphs.

 property OnBeginValidEvent:TNotifyEvent read FOnBeginValidEvent write FOnBeginValidEvent;
          Event fired  when one of the graph enters a non valid period

 property OnEndValidEvent:TNotifyEvent read FOnEndValidEvent write FOnEndValidEvent;
          Event fired  when one of the graph exits a non valid period

 property OnBorderEvent:TNotifyEvent read FOnBorderEvent write FOnBorderEvent;
          Event fired  when one of the sprite from the list  moves out of
          the window or bounces on its border.

  property OnEventRect:TNotifyEvent read FOnEventRect write FOnEventRect;
           See Tsprite.EventRect.
           

************ TGraph **************

A Tgraph is either a sprite which is an animated bitamp or a Text which is a
scrolling text window to display any specific message. A Tgraph has
the ability to  be hidden for period defines in its non valid list expressed in msecond.
The time reference will be the beginning of the active screen. This is an abstract
object which should never be used directly.  Descendants are  Tscroll and Tsprite.

      Main properties and methods are:

  property Width:integer read FWidth write FWidth;
           Width in pixels.

  property Height:integer read FHeight write FHeight;
           Height in pixels.

  property posx:integer read FPosx write FPosx;
  property posy:integer read FPosy write FPosy;
           x and y position in pixels from top left corner.

  property NonValid:Tlist read FNonValid write FNonValid;
           A list of non valid period where the graph is not displayed. See
           userpar in CardMaud project for an example.

  property Displayed:boolean read FDisplayed write FDisplayed;
           If false the object is not displayed. true by default.

  function DrawGraph(hdc:Thandle):Trect; virtual; abstract;
           Virtual redraw implementation.

************ TSprite **************

A Tsprite is a descendant from TGraph which  provides  movement , animation
and a bouncing facility

      Main properties and methods are:

        constructor CreateFmRes(RessourceName:string; Transparent:TTransparent;
                Compressed:TCompressed;Images:byte;hdc:Thandle);
            Create a sprite from a resource.
                Ttransparent=(Opaque,Transparent)
                  if transparent the background is displayed through the color of
                  upper left pixel.
                TCompressed=(NonCompressed,Compressed)
                  if compressed the ressource bitmap has been compressed.
                Images: Number of images in the bitmap. if O it is a fixed bitmap.
                hdc: Handle to the device context.


        constructor CreateFmBmp(BitmapFile:string;Transparent:TTransparent;
                Compressed:TCompressed;Images:byte;hdc:Thandle);
            Create a sprite from a file on the disk. see above.

        destructor  destroy;override;
        Called from GraphMng.

        function DrawGraph(hdc:Thandle):Trect;override;
             This will return the modified rectangle, i e the rectangle which
             needs to be redrawn.

        procedure DrawBitmap(hdc:Thandle);
             for debug purpose only.

        property speedx:integer read  FSpeedx write FSpeedx;
        property speedy:integer read  FSpeedy write FSpeedy;
             In pixels between two timer calls (every 55ms).

        property ImageRefresh:byte read FImageRef write FImageref default 1;
             Define the speed of the animation. it represents the number of
             time the same subimage is displayed. if 1 a new subimage  will be
             displayed every timer call.

        property Bounce:boolean read Fbounce write Fbounce;
              if true the sprite will bounce on the border of the screen.

        property Reversed:boolean read Freversed write Freversed;
              If true will mirror bitmap when speed x is negative. It is assumed that
              the initial bitmap is for positive speed (ie left to right). This
              can be slow especialy if you have a large bitmap in transparent mode.

        property  EventRect:TRect read FEventrect write SetEventrect;
              As soon as the sprite is completely in this rectangle,
              an OnEventRect event is be fired.

************ TScroll **************

A Tscroll is a descendant from TGraph that provides  scrolling text facility.

    Main properties and methods are:

        constructor Create(hdc:Thandle;FontName:string;FontSize:integer;FontColor:TColorref;
                            left,top,RectWidth,RectHeight:integer);
            hdc: DC handle
            FontName: font to be used
            Fontsize: in points
            FontColor: use an RGB call to obtain a Tcolorref from separate R,G,B
                       parameters.

        destructor destroy; override;
            Automatically called.

        function DrawGraph(hdc:Thandle):Trect; override;
            Called by graphmng.

        property Scroll:integer read FScroll write FScroll;
            Scrolling speed in pixels per timer call. if positive text will
            scroll down.


        property Strings:Tstringlist read Fstrings write Fstrings;
            Text to be displayed.


Note on Animation Speed
-----------------------

If compiled with the DISPLAY option you will see on the screen the time between
2 succesive call to the timer. Windows timers are limited to 55ms period and if
you PC is fast enough and  you are not trying to move too large bitmap that
what's you should read. Otherwise the animation will  slow down. Good new is
that this is pretty harmless: if you run the post card on a very slow machine
you will have very slow animation. That's all...

Known Restrictions:
-------------------

Bitmaps are limited to 1,4 or 16 bits per color. 24 bits bitmaps are not supported.
   Neither is the OS2 special bitmmap format, but who cares about that one any more...

Background color for all sprites is determined by the lower left corner pixel corner.

All position are in pixels with reference to the upper left corner of the screen.
Speed are expessed in pixels between 2 timer call.


Way of distribution:
--------------------

This code has been written and distributed as freeware as my contribution to the delphi
software community which helps me tremendously in getting up to speed with delphi
and windows API without any previous exposure to window prgramming.
 God!! when I see some of the messages I sent a year ago these guys have been
 really patient in answering my questions...

With special thanks to the following individual:

Ray Konopka for his book "Developping Custome Delphi components" which is a "must
read "

Charles Calvert for his book "Delphi2 unleashed" as it provides some good and easy
to unterstand examples of direct windows API call from delphi.

Charles Petzold "Windows 3.1 programming" which will take you smoothly through
the nigthmare of API programming.

And also Rick Rogers and Peter Below for their patient and consistent  support
via Borland delphi Forum...



Way of distribution
-------------------

You are free to use and distribute this software or part of this software as long
as this is  for non commercial use. However there is no garantee whatsoever regarding
its functionality and indeed it probably contains some bugs.

Debug
-----

As Delphi integrated debugger can be rather disruptive if you are dealing with time
driven software of if you try to debug a WM_PAINT message I included a small Debug tool
activated by the DEBUG conditional compile variable. It enables you to send string to
a debug window in a "not too disruptive" way. Make sure you recompile you all application
if you change this parameter.

example of call:
{$IFDEF  DEBUG}
    with TDebug.create do begin
       displaystring('selectobject:  '+inttostr(lastObj2));
       free;
     end;
{$ENDIF}

Alternatively you can stop the timer as explained  in WM_TIMER. This will allow
you to use the integrated debugger in the timer message and resume the software.

Some additional documentation about the object library  is included
in the file param.pas together with the key property. For the rest you will
have to refer to the object declaration.

I will provide support to the best of my time availability. Do not hesitate to send me
an Email if you have questions or found a bug.

Have fun....
Feb 1998
Paul-henri FERME




Revision history
----------------

1.0 original release to Delphi Super Page server  March 1998

Further enhancements:
--------------------

More capability to size and position the  window or have a window with a  size
different from the background bitmap...

