10 minute read •
The following document describes the various C++ classes which make up the CardLib game library.
|Returns the suit of the card [0..3]|
|Returns the value of the card, Aces Low, [1..13]|
|Returns the value of the card, Aces High, [2..14]|
|Returns the unique card index, [0..51]|
|Returns if card is face-up|
|Returns if card is face-down|
|Sets the face direction|
|Returns if card is Clubs or Spades|
|Returns if card is Diamonds or Hearts|
|Allocates a new 52-card deck|
|Returns number of cards in stack|
|Shuffles the cards in the stack|
|Removes all cards from the stack|
|Reverses the order of cards|
|Pushes the specified card|
|Pushes the specified CardStack|
|Pops the top-most card|
|Pops the top-most n-cards|
|Peeks the top-most card, without removing it|
|Peeks the top-most n-cards, without removing them|
|Removes the card at specified index|
|Inserts a card at specified index|
|Sets the button style (push-button, label etc).|
|Returns the button style.|
|Set the button text.|
|Set the button type-face.|
|* Aligns the button within it’s parent CardWindow.|
|Set the button text colour.|
|Set the button background colour.|
|Re-position the button.|
|Show / Hide the button.|
|Force the button to repaint itself.|
|Return the button ID.|
CardRegion::SetPlacement for more details.
|Set a new colour-scheme for the cardgame.|
|Assign a new CardStack.|
|Retrieve the current CardStack.|
|Control how high a card-stack can appear by grouping cards together. (Useful for decks with large numbers of cards).|
|Position the card region.|
|Show / Hide the card region.|
|Is the card region visible?|
|Set the image used to represent an empty card stack. Use |
|Set the card bitmap used for the card-backs.|
|Align the card region within its parent CardWindow.|
|Force the card region to repaint itself.|
|Control how cards are placed on the stack (face-down, face-up, or a combination of the two).|
|Return the current face-direction rule.|
|Make the stack flash a number of times.|
|Stop the stack flashing.|
|Return the ID.|
|Move the specified number of cards with index [0..51] to the specified CardRegion.|
|Move the specified number of cards from the top of the stack.|
|CardStack wrappers (for the internal stack).|
|Returns the number of cards in the internal CardStack.|
|Allocates a new 52-card deck.|
|Shuffles the cards in the stack.|
|Removes all cards from the stack.|
|Event Callbacks (see user guide for details).|
|Set the dragging rule for the CardStack.|
|Set the drop rule.|
|Mouse-button click event.|
|Mouse-button double-click event.|
|Post-add event callback.|
|Post-remove event callback.|
The following list describes a few of the functions in the above table which need more careful explanation.
void SetPlacement(UINT xJustify, UINT yJustify, int xAdjust, int yAdjust)
Controls the alignment of the CardRegion within it’s CardWindow.
xJustify specifies the horizontal alignment. Possible values are:
|Default alignment (left-aligned).|
|Aligned to the center of the CardWindow.|
|Aligned to the right side of the CardWindow.|
yJustify specifies the vertical alignment. Possible values are:
|Default alignment (aligned to the top of the window).|
|Aligned to the middle of the CardWindow.|
|Aligned to the bottom of the CardWindow.|
xAdjust specifies a horizontal offset (or border) to use. This offset is applied when the card-region is aligned to the center or right of the window. A positive value offsets the card-region to the right, a negative value offsets to the left.
yAdjust specifies a vertical offset (or border) to use. This offset is applied when the card-region is aligned to the middle or bottom of the window. A positive value offsets the card-region downwards, a negative value offsets the card-region upwards.
void SetFaceDirection(UINT uDirType, int nOption)
Controls how cards are placed onto the card-stack. Cards can be either face-up, face-down, or a combination of the two.
uDirType specifies what the face-direction is. Possible values are:
|All cards will be face-up when added to the stack.|
|Cards will be face-down.|
|The bottom most |
|The bottom most |
|Cards can be either face-up or face-down.|
nOption is used in conjunction with
CS_FACE_UPDOWN. This value controls the face-direction of the bottom-most nOption cards.
For example, assume that
nOption is 3. This means that the bottom 3 cards will always be face-down, and any cards above these 3 will always be face-up.
UINT GetFaceDirection(int *pnOption)
Returns the current face-direction rules.
This function returns the direction-type variable, and stores the option in the address specified by
void Flash(int count, int timeout)
Causes the card-region to flash on and off. This is achieved by hiding and then showing the card-region multiple times.
count specifies how many times the card-region will be hidden and shown again.
timeout specifies the duration of each stage of animation, in milliseconds.
Stops immediately any stack-flashing that might be active.
bool PlayCard(CardRegion *pDest, int val, int num)
Moves num cards of face-value val to the specified card-region.
val specifies the face-value of the card, using “Aces High” numbering [2..14].
num identifies the number of these cards to move.
PlayCard returns true on success, false on failure.
bool MoveCard(CardRegion *pDest, int nNumCards, bool fAnimate)
Moves the specified number of cards from the top of the current stack, to the specified destination stack.
nNumCards specifies how many cards are to be moved.
fAnimate is a boolean value, which specifies if the cards are to be animated when they are moved, or (when fAnimate is false) moved without any animation.
MoveCard returns true on success, false on failure.
|Create a physical card window.|
|Create a button.|
|Create a card-region.|
|Return the card-button with specified ID.|
|Return the card-region with specified ID.|
|Deletes the specified button.|
|Deletes the specifies card-region.|
|Deletes ALL regions, buttons and drop-zones|
|Empty all card-stacks in the card-window.|
|Force the card-window to repaint itself.|
|Update the position of all card-stacks and buttons.|
|Position a range of card-stacks in an aligned manner.|
|Specify a callback function for window resizes.|
|Return the width of the card-window.|
|Return the height of the card-window.|
|Set the current background colour.|
|Return the current background colour.|
|Specify which bitmap is to be used as the card-backs.|
|Set the bitmap to be used as window background.|
|Creates a new DropZone area.|
|Deletes the specified DropZone.|
The CardWindow functions are not as obvious as the previous classes, so following section describes each CardWindow member function separately.
BOOL Create(HWND hwndParent, DWORD dwExStyle, DWORD dwStyle, int x, int y, int width, int height)
Creates a physical window which will form the basis for a card-game.
CardButton *CreateButton(int id, TCHAR *szText, UINT uStyle, bool fVisible, int x, int y, int width, int height)
Create a button within the window.
id specifies a unique integer ID for the button.
szText is the address of a null-terminated string, which contains the button text.
uStyle specifies the button styles. The following styles are supported.
|Creates a static text label (default)|
|Creates a normal push-button|
|Centers the button text (default)|
|Left-aligns the button text|
|Right-aligns the button text|
fVisible specifies whether or not the button is visible.
x, y specifies the position of the button.
width, height specifies the dimensions of the button.
CardRegion *CreateRegion(int id, bool fVisible, int x, int y, int xoffset, int yoffset)
Create a card-stack region within the window.
id specifies a unique integer ID for the region.
fVisible specifies whether or not the region is visible.
x, y specifies the position of the region.
xoffset, yoffset specifies the direction that cards take when placed on the stack.
CardButton *CardButtonFromId(int id)
Returns a pointer to the CardButton object with the specified ID.
CardRegion *CardRegionFromId(int id)
Returns a pointer to the CardRegion object with the specified ID.
bool DeleteButton(CardButton *pButton)
Destroy the specified button. Do not use the
delete operator to delete a button - use this function instead. Note that the CardWindow will automatically delete all buttons when it is deleted itself.
bool DeleteRegion(CardRegion *pRegion)
Destroy the specified region. Do not use the
delete operator to delete a region - use this function instead. Note that the CardWindow will automatically delete all region when it is deleted itself.
Destroys every CardRegion, CardButton and drop-zone. All pointers to these objects become invalid.
Empty ALL card-stacks currently in the card-window.
Force the card-window to repaint itself.
Force the card-window to reposition all stacks and buttons.
bool DistributeStacks(int nIdFrom, int nNumStacks, UINT xJustify, int xSpacing, int nStartX)
Physically distribute the specified card stacks. The stack with the specified id (
nIdFrom ) is used as the starting point., and the
nNumStacks created after this stack will have their positions modified.
xJustify specifies the type of alignment to use:
|No alignment (left-aligned, default)|
xSpacing specifies how far apart each stack is to be placed.
nStartX specifies the starting x-coordinate to place the series of card-stacks.
void SetResizeProc(pResizeWndProc proc)
Specify a callback function, which is executed whenever the CardWindow’s size is altered. The callback function must have the following prototype:
void CARDLIBPROC ResizeWndProc(int width, int height)
Returns the width (in pixels) of the card-window.
Returns the height (in pixels) of the card-window.
void SetBackColor(COLORREF cr)
Set the current background colour.
Returns the current background colour.
void SetBackCardIdx(UINT uBackIdx)
Specify which card-bitmap is to be used as the card-back.
uBackIdx must be in the range [53..68] inclusive. Use one of the ecbxxx constants defined in CardLib.h
void SetBackImage(HBITMAP hBitmap)
Specifies a bitmap to be used as the card-window background. The CardWindow does not assume ownership of the bitmap.
hBitmap must be a valid handle to a bitmap object, or NULL to remove the background bitmap.
bool RegisterDropZone(int id, RECT *rect, pDropZoneProc proc)
Creates a DropZone within the card-window.
id specifies a unique ID for the DropZone. This id must NEVER be -1.
rect is the address of a RECT structure, which specifies the coordinates of the DropZone.
proc is the address of a callback function, which is executed whenever a card is dropped inside the rectangular area.
A DropZone is a special area within a CardWindow which cards can be dropped on. Even if a card-stack is within the area, the cards will not be dropped on it.
The specified function callback is called whenever one or more cards are dropped within the zone. This function must have the following prototype:
int CARDLIBPROC DropZoneProc(int dzid, const CardStack &cards)
The callback function returns the ID of the stack to drop the specified cards onto. Using this mechanism provides complete control over which stack cards are dropped.
The function must return a valid ID of a CardRegion to send the cards to, or use a value of
CS_DROPZONE_NODROP to prevent the cards from being dropped.
bool DeleteDropZone(int id)
Deletes the DropZone with the specified ID.