
                 ========================
                 CARDPACK ActiveX Control
                      Release v1.7
                       README.TXT
                 ========================



Abstract
--------

This package contains the CardPack ActiveX control.

This small software component implements a stack of playing cards,
giving programmers a powerful object to build card games with.
It can be used from Visual Basic, Visual C++ and even on web pages!

The most relevant features of this control are:

- It comes as an ActiveX control in 16 and 32-bit format. An
  earlier version (1.1) is still available as a VBX for use in
  Visual Basic 3.

- It can use the card picture library taken from old SOL.EXE or
  CARDS.DLL, which are provided in different versions of MS-Windows,
  The control is thus very small. If you prefer, you can provide your
  own card picture library with no color limitations!.

- It handles (as the name implies) stack with a virtually unlimited
  number of cards. Cards can be stacked or spread out in a number of ways.

- It has a wide set of game-oriented properties, designed to make it
  very easy to implement card games with no hassle. These include
  pattern-based queries and selections in the stack, handy extraction
  and addition methods, shuffling, sorting, and more!

- Comes with extensive documentation, programming tutorial, reference
  information and samples for Visual Basic and Internet Explorer!

More complete documentation is contained in the help file you will
find in this archive (cardpack.hlp).


Getting the files
-----------------

You can always get the latest release of this software from the
official Cardpack home page on the Web:

  http://www.multimedia.it/andy/cardpack/

You can also contact the author by E-mail at the following address:

  zanna@multimedia.it

  

More Information
----------------

The CardPack custom control began its life as a spare time
self-training project on custom controls and Windows programming.
Day after day, feature after feature, the control became a nice
piece of software, and it was really a shame to let it gather dust
in a drawer.

This piece of software was never actually intended for commercial
use. However, just in case, there is a license mechanism built in
that should convince you to check with the author before you attempt
to make money out of this software. Please read the following
sections for details.

I sincerely hope that you have as much fun using this software
as I had writing it.


What's new in release 1.7
-------------------------

  From this release on, only a 32-bit ActiveX version of the control
  is provided. Only Visual Basic 5 or higher is supported. 

  Removed fixed limit on number of cards in a control. The value
  of NumCards is now only limited by system memory.

  Added support for 256-colour cards on displays with a palette.
  The control now looks for a palette in the test card it opens
  from the DLL (resource #53, the first back) and uses it for all
  cards rendering.

  Fixed a bug where setting a control .Cards property to an empty
  card set could leave the control with 1 card.


Previous Release History
------------------------

* Version 1.6

  Migrated 32-bit development environment to VC++ 5 (requires new
  run-time libraries)

  The NumCards property can now be set to any number and it will
  not be rounded to a multiple of 4. This is useful at design time
  to get a better feel for your layout design.

  Added a new method, DrawCard, which can be used to perform
  completely custom layouts or animation effects, as shown in the
  about box of the sample game included in the archive, Briscola. 

  The Shuffle method was extended to take a seed parameter. This allows
  you to generate predictable random shuffling sequences, so that you
  can reproduce situations and test your game strategies.

  Fixed a bug where registering the control with Windows 95 at set-up
  could crash on some systems.

  Fixed a bug where, on fast computers, shuffling cards was not working
  very well.


* Version 1.5

  The control now supports 2 different jokers, as values 14 and 15. They
  map to card pictures in the library with resources id # 70 and 71, if
  available, or 70, or fall back to resource 56 if none of those are
  found.

  Now both CARDS16 and CARD32.DLLs have 2 jokers cards (red and blue),
  as resources 70 and 71, to match the new capabilities in the control.

  Fixed a bug where the CARDS16.DLL released in the previous version was
  broken and could not load the joker.

  Fixed a bug where jokers were always added face-down rather than
  respecting the default stack facing.

  Fixed a bug where moving jokers across controls caused an invalid
  property value error. The control was checking that the card had a
  valid suit, a rule which should not apply to jokers.

  Added 2 new properties to extract the top and bottom sections of a card
  deck without having to loop over each card: TopCards and BottomCards

  Added a 'CurrentCard' property that removes and returns the card
  currently under the cursor.

* Version 1.4

  A patch for making the control work with Visual Basic 5 has been
  incorporated (formerly released as version 1.3 build 002).
  The control was crashing VB5 due to some subtle environmental
  differences with respect to VB4 and other ActiveX containers.

  The control code was slightly optimized. Some dead code has been
  removed.

  Fixed a bug where controls with AutoSize=False would not properly
  reload their size.

  Fixed a bug where controls with AutoSize=False were not recalculating
  their layout correctly at design time.

  Fixed a bug where the control was not respecting custom card sizes
  when reloading properties.

  The control now prevents recursion of the Change() event. You can now
  safely add and remove cards within the event without bothering about
  implementing a semaphore variable in Visual Basic code.

  The CardsLibrary property now always shows the name of currently
  loaded DLL, even when it is one of the system DLL that are
  automatically sought by the control. The DLL name now always gets
  serialized when a project is saved.

  If loading the specified cards DLL fails, the control now attempts all
  the default names, as if no specific DLL had been indicated. This is a
  workaround against possible problems where loading the project or
  program on a different system, failing because a differently named
  cards DLL is present.

* Version 1.3

  The 32 bit OCX version of the control could always be used in Web
  pages. However, previous versions had a bug where checking a
  server-side control license from Microsoft Internet Explorer failed.
  This is now fixed.

  The control is not signed yet, so Internet Explorer will warn you
  against it for security reasons, but it works very well on the Web.

  Also, a tutorial about using the CardPack control on Web Pages was
  added to the documentation for all you Internet programmers and some
  web-based demos have been added to the distribution package.

  A little bug was fixed that could cause the control to fail loading
  the Joker card.

  Finally, we have included an automatic setup for Windows 95,
  NT 4 or better, as well as provisions to uninstall the software.


* Version 1.2

  There is a new property, "CardsLibrary", that allows you to
  explicitely specify the cards DLL to be used to provide the
  pictures for a specific control instance. It is thus possible
  to freely specify custom cards picture libraries.

  A 16-bit sample custom card DLL (acards.dll) is provided to
  test this feature with the 16-bit version of the control.

* ActiveX Version 1.1

  Two OLE control (OCX) versions of the control are now provided:
  a 16-bit version, CARDPK16.OCX and a 32-bit version, CARDPK32.OCX,
  with equivalent functionality. Since this release, all new control
  release are in the ActiveX (OCX) format.

  A couple of nasty layout bugs apparent when the stack was shown in
  "slanted" mode have been evicted.

  Note that the binary format for card-set strings has changed and is
  now different between CARDPK16.OCX and CARDPK32.OCX. Sorry, but this
  has to do with the way 32-bit OLE works. This has an inpact on load
  and save code in your application. See the help file for details.

  The 32-bit version of the control will require a 32-bit version
  of CARDS.DLL. Such version is directly available on NT systems, but
  not on Windows 95. When ported to Windows 95, the DLL should be
  renamed CARDS32.DLL.

* OCX Version 1.0

  One 16-bit OLE control (OCX) is provided: CARDPK16.OCX
  For the time being the 32-bit version (CARDPK32.OCX) is not ready.

  Using Visual Basic 4, it is possible to automatically migrate existing
  code that used the VBX version of the control to the new standard.

  The control supports new Methods, a better alternative to the old
  Action property of the VBX version of the control. Some of the methods
  also support optional parameters. 

  A new action/method (Reset) is provided.

  The control allows the use of a custom graphic as mouse pointer, using
  the new property MouseIcon.

  All properties for accessing the components of a Card Descriptor are
  range-checked on setting. An error is raised when an illegal value is
  used.

* VBX Version 1.1

  Fixed bug where adding a card to a position other than Top or
  Bottom of the stack with AddCard was broken.

  Fixed bug where adding a card to a stack caused 2 redraws,
  not 1 when AutoSize was set to True.

  Some optimization of control repaint has been implemented,
  in case just one card is inserted or removed. In particular,
  removing a card does not repaint the whole control unless
  AutoSize =True and PackOnRemove=True; adding one card does
  not repaint the whole control unless AutoSize =True.

  Because of some code optimization, the exception caused when
  reading SelectedCard the last time has changed from overflow to
  invalid property index.

  The sample program (Briscola) is now provided in two versions:
  one for Visual Basic 3.0 (Folder Briscola.vb3) and one for
  Visual Basic 4.0/16-bit (Folder Briscola.vb4).

* VBX Version 1.0

  Initial release


Contents of the Archive
-----------------------

The distribution archive should contain the following files:

  Main directory
    README.TXT   - This file
    CARDPACK.HLP - Control help file
    SETUP.EXE    - Program for automatic installation
    CARDPACK.INF - Installation script for SETUP.EXE

  BRISCOLA Directory 
    Sample Visual Basic card game.

  CARDSDLL Directory
    Sample custom-card DLL and Visual Basic project using it.
 
  CONTROLS Directory 
    Cardpack controls,
    Visual Basic programming support file.

  WEBGAME Directory
    A solitaire game implemented on a Web page in VBScript.

  WEBTEST Directory
    A simple demo showing how to embed the control in a Web page. 


Installation
------------

Preliminary Notes:

The Cardpack control is a custom control suitable for use with 
versions of Visual Basic supporting OCXs (4.0 or better). The
16-bit version of the control (CARDPK16.OCX) will only work with
Visual Basic 4.0/16-bit, while the 32-bit version (CARDPK32.OCX)
should work with all 32-bit versions of Visual Basic.

In order to keep the file size down, this archive does not contain
the shared Microsoft DLL that are needed to run this control:

	MFC42.DLL, MSVCRT.DLL	(32-bit version)
	OC25.DLL		(16-bit version)

You probably already have these DLLs on your system, but just in
case, they are available for download at:

	  http://www.multimedia.it/andy/logbook/download

or from in most on-line software archives.

The Cardpack controls contained in the distribution archive are
fully functional. However, you will require a license file in
order to get rid of the warning dialog both at programming time
and in executables.

To automatically install the software under NT 4, Windows 95:

1. If you are running Windows 95, NT 4 or anything better, you
   can install the software by double clicking on the SETUP.EXE
   program from the Windows Explorer. This will install the controls,
   help file and sample applications on your system.

2. Check out the Manual Installation Procedure detailed below anyway.
   Point 3 explains how to install the license file that you may
   receive separately. Point 5 explains how you can use Visual Basic
   to check that the controls are properly registered 

3. Check the important notes on CARDS.DLL further down in this file.

To uninstall the package use the Windows Control Panel, "software"
applet. In the list you find on the Add/Remove Software page, double
click the entry named "Cardpack Control".


To install the controls MANUALLY:

The distribution archive should include the following files:

 CARDPK32.OCX	the custom control file - 32-bit version
 CARDPK16.OCX	the custom control file - 16-bit version
 CARDPACK.HLP	the help file
 CARDPACK.BAS	support file for program development

Additionally, when you register you shall receive the license file,
CARDPACK.LIC via E-mail.

1. Copy the selected control file(s) and in the System directory: 
   In Windows 3.x, Windows 95 and Windows 98, typically
   C:\WINDOWS\SYSTEM
   In Windows NT, 16-bit controls in C:\WINNT\SYSTEM, while
   32-bit controls in C:\WINNT\SYSTEM32.

2. Copy CARDPACK.HLP in C:\WINDOWS\HELP, C:\WINNT\HELP or in
   the same directory where you put the control files.

3. The license file should be placed in the \Windows directory.
   Of course, you should not  distribute the license file with
   executable programs you write.

4. If you are a Visual Basic programmer, the CARDPACK.BAS file
   can be placed in your program source code directory and added
   to your VB project.

5. Register the control from Visual Basic. In Visual Basic 4,
   select the Tools menu, Custom Controls. Click the BROWSE
   button. Go to the directory where the control is installed,
   then check it. Close the Controls window clicking OK. In
   Visual Basic 5, use the Project, Components menu item.

6. For automatic conversion of Visual Basic programs from VBX
   to the OCX version of the control, edit VB.INI (normally in
    c:\WINDOWS); locate the section named [VBX Conversions16] and
    add the following line:

cardpack.vbx={6B17E7E3-AECA-11D0-B4D8-444553540000}#1.0#0;C:\Windows\System\cardpk16.ocx

    You can do the same for the 32-bit version of the control.
    The VB.INI section to edit is [VBX Conversions32] and the
    line to add is:

cardpack.vbx={6B17E7E3-AECA-11D0-B4D8-444553540000}#1.0#0;C:\Windows\System\cardpk32.ocx


CARDS.DLL, Important Notes
--------------------------

This control can use the card bitmaps it finds in SOL.EXE or CARDS.DLL.

These are components of the Solitaire and other card games which are provided
in different versions of MS-Windows and in the Windows Entertainment Packs.

Since these are Microsoft products, we cannot distribute them with the control.
So, first of all, make sure you have installed the card games that came with
your system. 

Unfortunately, 16-bit versions of the control require a 16-bit version of
CARDS.DLL, while 32-bit versions of the control require a 32-bit version
of CARDS.DLL.

You need to be aware of this, because with some set-ups you may be missing an
appropriate version of the library on the system. If the control complains
about being unable to find a cards library and you DO have one on the system,
it may simply be the wrong version.

Apparently most Windows95 installations only come with 16-bit versions of card
games and CARDS.DLL (exactly like Windows 3.1). These will work fine with either
the VBX version or with the 16-bit OCX version of the control, but not with
32-bit versions of the OCX control. Viceversa, the version of CARDS.DLL
installed in the System32 directory on Windows NT systems is a true 32-bit DLL
and can be used with the 32-bit OCX version, but not with either of the 16-bit
versions.

To sum things up:

           | Windows 3.1 |     Windows 95      |     Windows NT
-----------|-------------|---------------------|---------------------
16-Bit VBX |	OK       |        OK           | Needs 16-Bit DLL (1)
16-Bit OCX |	OK       |        OK           | Needs 16-Bit DLL (1)
32-Bit OCX |	NO       | Needs 32-Bit DLL(2) |         OK

(1) 16-bit versions of the control on Windows NT require you to get a copy of
    a 16-bit CARDS.DLL from a Windows 3.1 or Window95 system and copy it to
    the C:\WINNT\SYSTEM directory on the NT machine.

(2) 32-bit versions of the control on Windows 95 require you to get a copy of
    a 32-bit CARDS.DLL from the C:\WINNT\SYSTEM32 directory on an NT computer
    and copy it on your W95 computer in C:\WINDOWS\SYTEM as CARDS32.DLL

OK, so you are missing the right DLL and cannot get it? No problem.
There are a CARDS32.DLL and a CARDS16.DLL for you to use with the
control in the CARDSDLL Sample. Note that these sample DLLs do not
provide the code needed by Solitaire and other standard Window games.
They will only work with the Cardpack control, so make sure you don't
overwrite one of the original CARDS.DLL you have on your system.

Please note that, in case (2) above, changing the name of the library
is necessary in order to avoid deleting the existing 16-bit CARDS.DLL
which may reside in the same directory. 

Finally, the 32-bit version of the control has not been tested on Win32s
systems. It is not currently known if it will behave properly on such machines.


Copyright Notices
-----------------

The CardPack Control is Copyright  1995-1998 by Andy Zanna.
All rights reserved.

Windows, Windows NT, Windows 95, Visual Basic, Excel, Access,
Office, Visual Basic for Applications, VBScript, Windows
Entertainment Packs, Visual C++, Front Page, ActiveX and
Internet Explorer are either trademarks or registered trademarks
of Microsoft Corporation.

Disclaimer
----------

THIS SOFTWARE AND THE ACCOMPANYING FILES ARE PROVIDED "AS IS" AND
WITHOUT WARRANTIES AS TO PERFORMANCE OF MERCHANTABILITY OR ANY
OTHER WARRANTIES WHETHER EXPRESSED OR IMPLIED. IN NO EVENT SHALL
THE AUTHOR BE LIABLE FOR ANY DAMAGES, INCLUDING ANY LOSS OF PROFITS,
LOSS OF DATA, INCLUDING BUT NOT LIMITED TO SPECIAL, INCIDENTAL,
CONSEQUENTIAL, OR INDIRECT DAMAGES ARISING FROM THE USE OF THIS
SOFTWARE.


Distribution
------------

The distribution package for this version of the CardPack software
must at least include the following files:

 CARDPK32.OCX
 CARDPK16.OCX
 CARDPACK.HLP
 CARDPACK.BAS
 README.TXT

This package can be freely distributed provided that:

1.  It is not bundled with a commercial product.

2.  All the files in the package are included and no changes of
    any kind are made to the original files.

3.  No charge or donation is requested for any copy of
    the software itself, however made, except for the bare
    cost of physical support, transmission medium and time
    required to perform the copy.

In all other circumstances, written permission must be obtained
from the author prior to distribution.

The custom control files (CARDPK16.OCX and CARDPK32.OCX) can be
distributed alone only as part of a commercial product and only
if the author of that product has a valid license for the CardPack
software.

This license cannot be transferred to users or purchasers of the
said commercial product.


User License
------------

This package can be freely used for any legitimate personal,
non-commercial purpose.

When used as component of a commercial  program, the producer
is required to contact the CardPack author in order to obtain
permission, in the form of a specific development license file
(see Registration Information below).

The author reserves all right to change the distribution and
licensing policy for any future major version of the CardPack
software and derived products.

Source code for this package is not freely available. It can,
however, be purchased from the author.


About the Author
----------------

The author (Andy Zanna) is an electronic engineer with a broad
experience in software design and production on a wide range of
systems, from home computers to real-time systems, enterprise
servers and large networks.

This software is in no way related to the authors real work or
to the company where he is employed.

Registrations, information queries and suggestions should be
addressed to:

  Andy Zanna
  Hauptstr. 41
  D-71263
  Merklingen - Weil der Stadt
  Germany
  
  phone:	+49-7033-33800
  E-mail:	zanna@multimedia.it


Registration Information
------------------------

If you register this control, you will receive a license file that
will get rid of the warning dialog that is displayed when the control
is loaded at design or run-time. You will then be able to compile
stand-alone applications and distribute them free of royalty.

You will also receive notifications of updates and a right to use
all minor updates (e.g. 1.x) with the same license.

The registration fee is US$ 25 or equivalent in major currencies
(DM, UK Pound, F Franks), should be sent by mail money order to
the address above. You should add another 5$ if you require that
the software and the license be sent to you via ordinary mail,
rather than E-mail.

You should also send a registration notice by ordinary mail or
E-mail (preferably) to the address above, indicating your name,
company (if applicable), mail and E-mail addresses.

                     * end of file *


