++++++++++++++++++++++++++++++++++++++++
How to create a style for PokerTH
++++++++++++++++++++++++++++++++++++++++

PokerTH ships two clients with their own sets of styles. Sections 1 and
2 describe the styles of the classic widget client, section 3 describes
those of the QML client, and section 4 applies to both.

+++++++++++++++++++++++
1. Game Table Styles
+++++++++++++++++++++++

1.1 Creating a game table
-----------------------------
The best way to start building a custom PokerTH game table is to look
at the file "defaulttablestyle.xml". You can find it in the source code
or in the installation directory for PokerTH >= 0.7, in the
data/gfx/gui/table/default/ subfolder. This file is the control center
of your style. It also contains comments describing the controls.

Maybe you would like to play around with the default table to see how 
the controls will work. To do this, you should copy the whole
data/gfx/gui/table/default/ directory to another place. 

To avoid confusing styles, first change the description:
<StyleDescription value="PokerTH default table style" /> --> (e.g.)
<StyleDescription value="my custom style" />.

Also rename the file and directory:
"defaulttablestyle.xml" --> (e.g.) "mycustomstyle.xml"

"default" --> (e.g.) "mycustomtable".

Now you can experiment with color values or edit the graphics files.
For the best table-drawing performance, draw the graphics at the optimal
size specified in the corresponding comment in the XML file.


1.2 Testing your style
--------------------------------
To test your style, load it in PokerTH using
"Settings" -> "Style" -> "Game Table Styles" --> "Add ...". 
After you select the file, its "StyleDescription" value appears in the
list. Select the corresponding entry and click "Activate". Closing the
Settings dialog refreshes the game table style.

If you change your custom style's XML file, you do not need to re-add it
in Settings or restart PokerTH. To refresh the game table style, simply
open the Settings dialog and close it again.


+++++++++++++++++++++++++
2. Card Deck Styles
+++++++++++++++++++++++++

2.1 Start building a card deck
--------------------------------
Creating a card deck is simpler than creating a game table style. The XML
file is used only for StyleDescription, StyleMaintainerEMail and Preview.
The file data/gfx/cards/default/defaultdeckstyle.xml contains all the
information needed to set these values.

Maybe you would like to play around with the default card deck.
To do this, copy the whole data/gfx/cards/default/ directory somewhere
else. To avoid confusing card deck styles, first change the description:
<StyleDescription value="PokerTH default card deck" /> --> (e.g.) 
<StyleDescription value="my custom card deck" />.

Also rename the file and directory:
"defaultdeckstyle.xml" --> (e.g.) "mycustomcardstyle.xml" 

"default" --> (e.g.) "mycustomdeck". 

Now you can start editing the graphics files.

The files numbered 0.png through 51.png correspond to the card values.
It is very important to leave the filenames unchanged. For example,
PokerTH uses 0.png for the diamond 2, 51.png for the club ace and 24.png
for the heart king. The card deck directory must also contain a
flipside image named "flipside.png".

All cards should be 48x76 pixels. If an image does not have these
dimensions, PokerTH scales it automatically. This scaling can slow down
animations.


2.2 Testing your deck
--------------------------------
To test your deck, load it into PokerTH using
"Settings" -> "Style" -> "Card Deck Styles" --> "Add ...".
After you select the file, its "StyleDescription" value appears in the
list. Select the corresponding entry and click "Activate". Closing the
Settings dialog refreshes the card deck style.

If you change your custom card deck's XML file, you do not need to
re-add it in Settings or restart PokerTH. To refresh the card deck
style, simply open the Settings dialog and close it again.


+++++++++++++++++++++++++
3. QML Client Styles
+++++++++++++++++++++++++

Sections 1 and 2 describe the styles of the classic widget client. The
QML client has its own styles under data/gfx/qml/. The XML format was
kept deliberately close to the widget format: it uses the same root
element (<PokerTH>) and section tags, and stores all data in a "value"
attribute. The conventions therefore carry over. The differences are:

  * All style graphics are SVG (scalable to any size). The only raster
    image is the game table background.
  * The card back is a style category of its own; in the QML client it
    is NOT part of the card deck.
  * A game table style can additionally carry colors (player boxes,
    chat/log panels) and a portrait preview for the mobile layout.

There are three categories, with one folder per style:

  data/gfx/qml/table/<name>/     game table   *tablestyle.xml
  data/gfx/qml/cards/<name>/     card deck    *deckstyle.xml
  data/gfx/qml/backside/<name>/  card back    *backsidestyle.xml

The folder name is the style name stored in the client's configuration,
so it must be unique within its category. The XML file name can be
anything as long as it ends with the suffix listed above. The client
finds styles by this suffix and ignores files with other names.

Styles shipped with PokerTH live in the installation directory. Styles
added by the user are copied to the user data directory (on Linux,
~/.pokerth/data/gfx/qml/<category>/<name>/). The client scans both
locations, checking the bundled styles first.

Every style XML starts with the same block of style information:

  <PokerTH>
    <TableStyle>   <!-- or <CardDeck> / <CardBack> -->
       <StyleDescription value="my custom style" />
       <StyleMaintainerName value="Your Name" />
       <StyleMaintainerEMail value="you@example.com" />
       <StyleCreateDate value="18.06.2026" />
       <PokerTHStyleFileVersion value="3" />
       <Preview value="preview.png" />
       ...

PokerTHStyleFileVersion is 3 for a game table, 2 for a card deck and 1
for a card back. A different version is accepted, but the client warns
that the style is outdated. All file names are relative to the XML file.


3.1 Game table style
--------------------------------
Start with data/gfx/qml/table/default/defaulttablestyle.xml. It contains
comments and examples for every tag. Copy the whole folder, rename it,
update StyleDescription, and then edit the graphics.

Table background (the only raster graphic):

  <Table value="table.png" />
  <TableBackgroundAlign value="bottom" />   bottom | center
  <TableBackgroundZoom value="1.3" />       center mode only, >= 1.0

"bottom" draws the image as a classic cover across the table zone.
"center" is meant for images that show the table in the middle of a
scene: the client scales the image to cover the whole zone and centers it
on the player-box ellipse. This position is fixed because there is no
offset tag. To move the felt, crop the image rather than changing a tag.
TableBackgroundZoom then decides how large the table sits in the frame
(a larger value crops more of the outer border). To tune it without
rebuilding, change the value and restart the client.

The bundled backgrounds are between 1024 and 2164 pixels wide; roughly
1600x1000 or more is a good target for a full screen table.

Pucks and action buttons (SVG):

  <DealerPuck value="dealerPuck.svg" />
  <SmallBlindPuck value="smallblindPuck.svg" />
  <BigBlindPuck value="bigblindPuck.svg" />
  <FoldButton value="actionFold.svg" />
  <CheckCallButton value="actionCall.svg" />
  <BetRaiseButton value="actionRaise.svg" />
  <AllInButton value="actionAllIn.svg" />
  <ActionButtonBorderRadius value="9" />

The pucks are drawn on a nearly square canvas; the bundled ones use
viewBoxes ranging from "0 0 40 40" to "0 0 44 45". The action buttons
are drawn on a 168x43 canvas and are pure symbol graphics: the client
renders the button text and the state frames (preselection, primary
action) itself.
ActionButtonBorderRadius sets the corner radius of your SVG in units of
that 168x43 canvas. Otherwise, the state frame and button corners do not
match. Unlike the widget client, there are no separate hover or
checked graphics.

The button text color is derived from the brightness of the button
(averaged over its gradient stops) so that it always contrasts. Set it
explicitly if the automatic value does not fit:

  <ActionButtonTextColor value="#efe6d4" />     all four buttons
  <FoldButtonTextColor value="#efe6d4" />       per button
  <CheckCallButtonTextColor value="..." />
  <BetRaiseButtonTextColor value="..." />
  <AllInButtonTextColor value="..." />

The following colors control the table furniture. They are independent
of the application's light or dark mode; the table always keeps the look
of its style.
Every tag is optional. Missing tags fall back to the bundled default
set. The client chooses the default set (dark or light) based on the
brightness of ChatLogBackground, so a bright table has readable panels
even if only that tag is specified.

  <PlayerBoxAccent value="#cf9a34" />       tints gradient and frame of
                                            the player boxes
  <ChatLogBackground value="#1d222b" />     panel background
  <ChatLogSurface value="#394150" />        input field / chat bubble
  <ChatLogBorder value="#576378" />         frame / separator
  <ChatLogText value="#eff1f5" />           main text
  <ChatLogTextSecondary value="#cdd3e0" />  secondary text / icons
  <ChatLogTextMuted value="#7787a3" />      muted text / placeholder
  <ChatLogAccent value="#E3C800" />         title, active tab, mention
  <ChatLogAccentText value="#101010" />     text on the accent
  <ChatLogWinner value="#FFFF00" />         winner of the main pot
  <ChatLogWinnerSide value="#FFFFCC" />     winner of a side pot
  <ChatLogBoard value="#FF6633" />          flop/turn/river, sits out
  <ChatLogSend value="#4ade80" />           send icon

Use solid hex colors only, the translucency of the panels is done by the
client. ChatLogAccentText is derived from ChatLogAccent if omitted.

Previews:

  <Preview value="preview.png" />                    800x500
  <PreviewPortrait value="preview_portrait.png" />   380x822

PreviewPortrait is a QML addition and shows the style in the portrait
(mobile) layout. If only one of the two is present it is used for both
orientations. Both should be real screenshots of the running table, not
a composition of the source graphics.


3.2 Card deck style
--------------------------------
A card deck consists of 52 card faces, the style XML file and a preview;
see data/gfx/qml/cards/default/. As in the widget client, the files are
named by engine index. The format is the only difference: 0.svg to
51.svg instead of PNG. All 52 files must be present; decks with missing
files are rejected on import.

  suit = index / 13:  0-12 diamonds, 13-25 hearts,
                      26-38 spades,  39-51 clubs
  rank = index % 13:  0=2, 1=3, ... 8=10, 9=jack, 10=queen, 11=king,
                      12=ace

For example, 0.svg is the diamond 2, 24.svg is the heart king and
51.svg is the club ace. Do not rename the files.

Draw the cards on a viewBox of "0 0 120 168". The client stretches each
card to the table's aspect ratio, so a different canvas size will distort
it. Since all ranks are drawn into the same rectangle, the rank glyphs
must all have exactly the same height. Otherwise, the indexes jump from
card to card.

The card back is NOT part of the deck (see 3.3), so there is no
flipside.svg. BigIndexesActionBottom exists in the XML for compatibility
with the widget client only and is ignored by the QML client.

The deck preview is a transparent PNG of about 724x564 showing two
overlapping, slightly rotated cards.


3.3 Card back style
--------------------------------
A card back style consists of one graphic and its XML file:

  <CardBack>
     ...
     <Backside value="backside.svg" />
  </CardBack>

See data/gfx/qml/backside/default/. The graphic is stretched to the card
rectangle, so draw it in the card's aspect ratio (the bundled backs use
viewBox "0 0 580 800", "0 0 630 880" or "0 0 120 168"). The preview is a
PNG of 424x561 showing the back side alone.


3.4 Adding and testing a style
--------------------------------
In the QML client, styles are managed under "Settings" -> "Style". The
three tabs "Game Table", "Card Deck" and "Card Back" list the available
styles with their previews. Click a style to activate it, or select
"Add Style..." to import a new one.

The import accepts either a ZIP archive of the style folder or, on the
desktop, the style XML file in its folder. In both cases, the whole
folder is copied into the user data directory, so the style remains
available after the download folder or USB stick is gone. The import
rejects archives whose XML file name does not follow the suffix
convention, whose style name is already in use, or whose card deck is
missing cards. Missing optional entries are reported as warnings and
replaced by the bundled defaults at runtime.

The style takes effect immediately when you activate it. After editing
an imported style on disk, restart the client to see the changes.
Note that the import copies the style. Editing the source folder has no
effect; edit the copy in the user data directory instead.

Styles imported by the user can be removed again from the same list.
Every style, bundled or imported, can also be exported from this list as
a ZIP archive. This is the simplest way to package your style for
distribution.


+++++++++++++++++++++++++
4. Distributing Styles
+++++++++++++++++++++++++

Once your game table or card deck style is finished, complete its style
information: StyleDescription, StyleMaintainerEMail and Preview. The best
preview for a game table style is a screenshot of it running in PokerTH.
For a card deck style, you may want to create an image like
data/gfx/cards/default/preview.png.

If your style is ready to ship, pack the whole directory into a ZIP
archive. For a QML client style, the export option in
"Settings" -> "Style" does exactly that: it writes the style folder
into a ZIP archive ready for distribution.

If you would like your style to be added to the style gallery on
https://www.pokerth.net, send a link to the archive's location to
webmaster@pokerth.net. We cannot promise that every style will be added,
but if everything works and the legal issues are clear, there should be
no problem.

Please read the PokerTH GUI styling legal notices
(https://www.pokerth.net/content/view/55) carefully if you would like a
link to your style archive from https://www.pokerth.net.


And now ... have fun creating stylish PokerTH styles!


2009 by Felix Hammer 
