============================================================================

VBCARDS.DLL - Version 1.01P

T h e G r i n n i n g J a c k D e c k

Written by Richard R. Sands
CIS 70274,103

============================================================================

The VBCARDS.DLL is a library of routines that allows card-game
applications to share common bitmap resources. It also provides some
basic support routines.

Personally, I'm tired of getting card games, each that contain a copy of
their own bitmaps for the cards. Hopefully, this can form a basis for
writing card games that can share the images thus saving diskspace and
memory.

This library contains the basic card values Ace through King, a Joker, and
seven card back styles. It also includes a couple of misc. cards used to
indicate (non-)empty decks (a green X and a green O card).

The compiled DLL is released to the Public Domain. Turbo Pascal for
Windows Source code is available from me for a nominal $5.00. You may not
distribute the DLL source code.

I am completely open to suggestions for improvement, bugs, and, of course,
critisisms (who me?). Send them to this forum or use email.

Although the DLL is public domain, I *sure* would like to see some of the
games that is created using this DLL!


============================================================================
IMPLEMENTATION NOTES
============================================================================
1. Note that the DLL, when a card image routine is called, will place the
card into the clipboard. So don't try to keep something in the Clip-
board while playing a card game.

2. Set the BorderStyle property of each card to 0 - No Border

3. Given an array:
Option Base 1
Global Deck(52) As Integer
then a these will work:

Sub InitDeck ()
For I = 1 to 52
Deck(i) = i
Next I
End Sub

Sub ShuffleDeck ()
For I = 1 to 10
For J = 1 to 52
K = Int( 1 + (52 * Rnd))
Temp = Deck(j)
Deck(j) = Deck(k)
Deck(k) = Temp
Next
Next
End Sub

============================================================================
THE ROUTINE DOCUMENTATION
============================================================================
You must declare the following routines in a module to access these subs
and functions:

Declare Function CardVersion Lib "VBCards.dll" () As Integer

Declare Sub GetCard Lib "VBCards.dll" (ByVal Card As Integer)
Declare Sub GetCardBack Lib "VBCards.dll" (ByVal C As Integer)
Declare Sub GetCardMisc Lib "VBCards.dll" (ByVal C As Integer)

Declare Function SuitOf Lib "VBCards.dll" (ByVal C As Integer) As Integer
Declare Function SameSuit Lib "VBCards.dll" (ByVal c1 As Integer, ByVal c2 As Integer) As Integer
Declare Function IsCardRed Lib "VBCards.dll" (ByVal C As Integer) As Integer
Declare Function IsCardBlack Lib "VBCards.dll" (ByVal C As Integer) As Integer
Declare Function IsCardSameColor Lib "VBCards.dll" (ByVal C1 as Integer, ByVal C2 As Integer) As Integer

Declare Function CardValue Lib "VBCards.dll" (ByVal C As Integer) As Integer
Declare Function SameCardValue Lib "VBCards.dll" (ByVal c1 As Integer, ByVal c2 As Integer) As Integer


You should declare in the GLOBALS section:

Global Const NumCards = 52 'Or 53 if you want to include the Joker
Global Const CardWidth = 71
Global Const CardHeight= 96

Global Const Spades = 1
Global Const Hearts = 2
Global Const Clubs = 3
Global Const Diamonds = 4


============================================================================
VERSION ROUTINE
============================================================================
Function CardVersion () As Integer

This returns the version number. Eg. Version 1.01 is returned as 101.
This function should be called before any other routines are executed.


============================================================================
BASIC CARD BITMAP ROUTINES
============================================================================
Sub GetCard (ByVal Card As Integer)

This routine will copy the card specified to the clipboard. You can then
assign the clipboard contents (bitmap=2) to a control.Picture.

Values 1..13 are Spades. 11=Jack, 12=Queen, 13=King. Values 14..26 are
Hearts, 27..39 are Clubs, and, 40-52 are Diamonds. The Joker is 53.

Example:
GetCard(13)'King of Spades
Picture1(i).Picture = ClipBoard.GetCard(2)' 2=Bitmap


----------------------------------------------------------------------------
Sub GetCardBack (ByVal Card As Integer)

This routine will copy the card back specified to the clipboard. You can
then assign the clipboard contents (bitmap=2) to a control.Picture.

As supplied, valid values are 1..7

----------------------------------------------------------------------------
Sub GetCardMisc (ByVal Card As Integer)

This routine will copy the misc. card specified to the clipboard. You can
then assign the clipboard contents (bitmap=2) to a control.Picture.

As supplied, valid values are 1 and 2. 1 returns a green card with a big
red X on it, and 2 returns a green card with a large O on it.


============================================================================
CARD SUIT COMPARISON ROUTINES
============================================================================
Function SuitOf (ByVal C As Integer) As Integer

This routine returns the suit of the card as an integer. It returns 0 if
the card is not in the range of 1..52.

Values of the suits are:
1 Spades
2 Hearts
3 Clubs
4 Diamonds

----------------------------------------------------------------------------
Function SameSuit (ByVal c1 As Integer, ByVal c2 As Integer) As Integer

This returns -1 (true) if cards C1 and C2 are the same suit. Returns zero
if the card is not valid.

----------------------------------------------------------------------------
Function IsCardRed (ByVal C As Integer) As Integer

This returns -1 (true) if the card C is a Heart or Diamond. Returns zero
if the card is not valid.

----------------------------------------------------------------------------
Function IsCardBlack (ByVal C As Integer) As Integer

This returns -1 (true) if the card C is a Spade or Club. Returns zero
if the card is not valid.

----------------------------------------------------------------------------
Function IsCardSameColor (ByVal C1 as Integer, ByVal C2 As Integer) As Integer

This returns -1 (true) if the card C1 is a the same color as C2. Returns
zero if the card is not valid.


============================================================================
CARD VALUE COMPARISON ROUTINES
============================================================================
Function CardValue (ByVal C As Integer) As Integer

This returns the value of a card. All values are in the range of 1..13.
For example, card 14 is the Ace of Hearts. Card 39 is the King of Clubs.
Returns zero if the card is not valid.

----------------------------------------------------------------------------
Function SameCardValue (ByVal c1 As Integer, ByVal c2 As Integer) As Integer

This returns the -1 (true) if the value of C1 is the same as C2
For example, card 13 has the same value as 26. Returns zero if the card
is not valid.


============================================================================
ADDING NEW BACK VALUES
============================================================================
If you have the Whitewater Resource Toolkit (WRT.EXE) or Resource Workshop
(RW.EXE) then you can edit the VBCards.dll to add new card backs. The
Card Back Resources are valued at 60 through 89 of which I have provided
60 through 66 (7 card backs).

The bitmaps for the images are 71 pixels wide and 96 pixels high.

Optionally, the backs could be released as .BMP files so users can add the
.BMP files themselves.