Initial commit of mtgonline project
This commit is contained in:
+16
@@ -0,0 +1,16 @@
|
||||
@page card_database_schema_and_parsing Card Database Schema and Parsing
|
||||
|
||||
# Card Database Schemas
|
||||
|
||||
Cockatrice uses `XML files` to store information of available cards to be used in the app (`cards.xml`).
|
||||
The token file follows the schema of the card database (`tokens.xml`), too.
|
||||
|
||||
Saved decks (`<deckname>.xml`) use a different schema.
|
||||
|
||||
- [XSD Schema for `Card Databases`](https://github.com/Cockatrice/Cockatrice/blob/master/doc/carddatabase_v4/cards.xsd) <kbd>v4</kbd>
|
||||
- [XSD Schema for `Decks`](https://github.com/Cockatrice/Cockatrice/blob/master/doc/deck.xsd) <kbd>v1</kbd>
|
||||
|
||||
|
||||
# Card Database Parsing
|
||||
|
||||
TODO
|
||||
@@ -0,0 +1,83 @@
|
||||
@page displaying_cards Displaying Cards
|
||||
|
||||
Cockatrice offers a number of widgets for displaying cards. To pick the right one for your purpose, it is first
|
||||
important
|
||||
to determine the context in which you will be displaying the card.
|
||||
|
||||
# In-client
|
||||
|
||||
In the client (like in your custom widgets), you can use the existing card display widgets.
|
||||
|
||||
## Simple Display
|
||||
|
||||
The most general purpose of these is @ref CardInfoPictureWidget, which simply displays a picture of a card.
|
||||
|
||||
The textual equivalent to this is @ref CardInfoTextWidget, which displays all the properties of a card in text form.
|
||||
|
||||
## Detailed Display
|
||||
|
||||
The convenience class @ref CardInfoDisplayWidget displays both of these widgets in a tabbed container, which allows
|
||||
choosing between either visual, textual, or both representations at the same time. It is the class that is most
|
||||
familiar to our users when a single card is highlighted or inspected, since it is used in the deck editor and in-game
|
||||
for these purposes.
|
||||
|
||||
If you would like the user to be able to inspect a single card in your custom widget, you should
|
||||
expose a @ref CardInfoDisplayWidget to them and incorporate it as a dock widget inside your custom widget.
|
||||
|
||||
@ref CardInfoDisplayWidget is great for ensuring that the user has all the relevant details of a card available.
|
||||
It is crucial anywhere the user might encounter a card for the first time or needs to make an informed decision.
|
||||
|
||||
## Visual Display
|
||||
|
||||
However, there is a reason why it is possible to have a visual-only representation of the card in the
|
||||
@ref CardInfoDisplayWidget.
|
||||
|
||||
Cards are, by design, meant to be represented as images and cards which we can reasonably
|
||||
expect the user to know (for example, cards contained in a user made deck or explicitly chosen by the user) can be
|
||||
represented with just their image as a sort of "visual shorthand".
|
||||
|
||||
The simplest way to do this is of course, the above-mentioned @ref CardInfoPictureWidget which simply displays the
|
||||
picture without modifications.
|
||||
|
||||
However, there exist a couple of other convenience classes which subclass @ref CardInfoPictureWidget to accomplish some
|
||||
things which you might find useful as well.
|
||||
|
||||
- @ref CardInfoPictureWithTextOverlayWidget displays text overlaid on top of the card picture and scales this text to
|
||||
fit automatically.
|
||||
- @ref DeckPreviewCardPictureWidget is a @ref CardInfoPictureWithTextOverlayWidget which also features a
|
||||
raise-on-mouse-enter animation, controlled by the global setting (TODO: specify which).
|
||||
- @ref CardInfoPictureArtCropWidget attempts to display an 'art crop' of the card by cropping the upper region of the
|
||||
card and only displaying that.
|
||||
|
||||
## Groups of Cards
|
||||
|
||||
Sometimes it is useful to display images of cards in groups, for example to represent the deck in the @ref
|
||||
VisualDeckEditorWidget or during confirmation in the pre-game lobby.
|
||||
|
||||
To this end, Cockatrice offers three convenience classes to display cards for an index in a @ref DeckListModel in a
|
||||
group and one to display all cards in a particular zone of a @ref DeckListModel.
|
||||
|
||||
The generic way to do this is @ref CardGroupDisplayWidget, which displays cards in @ref QVBoxLayout. This class is very
|
||||
generic and it is probably a better choice to either subclass it or use one of the two existing implementations.
|
||||
|
||||
@ref FlatCardGroupDisplayWidget displays cards using a horizontal @ref FlowWidget. This means it will fill available
|
||||
screen space, left to right with no margins, with card pictures, skipping to a new line if it overflows available screen
|
||||
space horizontally.
|
||||
|
||||
@ref OverlappedCardGroupDisplayWidget displays cards using an @ref OverlapWidget, which displays widgets on top of each
|
||||
other in vertical columns until it exceeds available screen space in which case it will start a new column. The amount
|
||||
of overlap as well as the overlap direction is configurable.
|
||||
|
||||
@ref DeckCardZoneDisplayWidget can be used to visualize all cards in a zone with either a @ref
|
||||
FlatCardGroupDisplayWidget or a @ref OverlappedCardGroupDisplayWidget and headed by a @ref BannerWidget. It also allows
|
||||
grouping and sorting.
|
||||
|
||||
# In-game
|
||||
|
||||
The in-game view is a @ref QGraphicsScene, which means any widget we want to display inside of it should be a @ref
|
||||
QGraphicsObject.
|
||||
|
||||
- @ref CardItem
|
||||
|
||||
|
||||
|
||||
@@ -0,0 +1,11 @@
|
||||
@page developer_reference Developer Reference
|
||||
|
||||
- @subpage logging
|
||||
|
||||
- @subpage primer_cards
|
||||
|
||||
- @subpage card_database_schema_and_parsing
|
||||
- @subpage querying_the_card_database
|
||||
|
||||
- @subpage loading_card_pictures
|
||||
- @subpage displaying_cards
|
||||
@@ -0,0 +1,52 @@
|
||||
@page loading_card_pictures Loading Card Pictures
|
||||
|
||||
Pictures associated with CardInfo%s are retrieved either from on-disk or the network through the CardPictureLoader.
|
||||
|
||||
In most cases, you don't need to concern yourself with the internals of CardPictureLoader.
|
||||
|
||||
Simply using one of the ways described in @ref displaying_cards is enough to automatically queue a request to the
|
||||
CardPictureLoader when the chosen widget is shown, emitting signals to refresh the widget when the request is finished.
|
||||
|
||||
# How requests are triggered
|
||||
|
||||
CardPictureLoader::getPixmap() is called exactly two times in the code base, in CardInfoPictureWidget::loadPixmap(), the
|
||||
base class
|
||||
for all widget based card picture display, and AbstractCardItem::paintPicture(), the base class for all QGraphicsItem
|
||||
based card picture
|
||||
display. See @ref displaying_cards for more information on the difference between these two display methods.
|
||||
|
||||
Because both of these calls are made in the paintEvent() methods of their respective classes, this means that requests
|
||||
are issued as soon as but not before the widget is shown on screen.
|
||||
|
||||
It is also possible to "warm up" the cache by issuing card picture load requests to the CardPictureLoader without using
|
||||
a display widget and waiting for it to be shown by calling CardPictureLoader::cacheCardPixmaps() with a list of
|
||||
ExactCard%s.
|
||||
|
||||
# The QPixmapCache and QNetworkDiskCache
|
||||
|
||||
Cockatrice uses the QPixmapCache from the Qt GUI module to store card pictures in-memory and the QNetworkDiskCache from
|
||||
the Qt Network module to cache network requests for card pictures on-disk.
|
||||
|
||||
What this means is that the CardPictureLoader will first attempt to look up a card in the QPixmapCache according to the
|
||||
ExactCard::getPixmapCacheKey() method of an ExactCard object. If it does not find it in the in-memory cache, it will
|
||||
issue a load request, which will first look for local images on-disk and then consult the QNetworkDiskCache and if
|
||||
found, use the stored binary data from the network cache to populate the in-memory pixmap cache under the card's cache
|
||||
key. If it is not found, it will then proceed with issuing a network request.
|
||||
|
||||
The size of both of these caches can be configured by the user in the "Card Sources" settings page.
|
||||
|
||||
# PixmapCacheKeys and ProviderIDs
|
||||
|
||||
TODO
|
||||
|
||||
# The Redirect Cache
|
||||
|
||||
TODO
|
||||
|
||||
# Local Image Loading
|
||||
|
||||
TODO
|
||||
|
||||
# URL Generation and Resolution
|
||||
|
||||
TODO
|
||||
@@ -0,0 +1,184 @@
|
||||
@page logging Logging
|
||||
|
||||
Cockatrice uses QtLogging from the QtCore module for its logging. See
|
||||
the [official documentation](https://doc.qt.io/qt-6/qtlogging.html) for further details.
|
||||
|
||||
# Log Message Pattern
|
||||
|
||||
Any message logged through the QtLogging system automatically conforms to this message pattern:
|
||||
|
||||
Generic:
|
||||
|
||||
```
|
||||
[<timestamp> <log_level>] [<class:function>] - <message> [<filename>:<line_no>]
|
||||
```
|
||||
|
||||
Example:
|
||||
|
||||
```
|
||||
[2025-12-05 14:48:25.908 I] [MainWindow::startupConfigCheck] - Startup: found config with current version [window_main.cpp:951]
|
||||
```
|
||||
|
||||
For more information, see [Logging Setup](#logging-setup).
|
||||
|
||||
# Log Level and Categories
|
||||
|
||||
\note The default log level for the application is info.
|
||||
|
||||
This means that you should only use qInfo() in production-level code if you are truly sure that this message is
|
||||
beneficial to end-users and other developers. As a general rule, if your functionality logs to info more than twice in
|
||||
response to a user interaction, you are advised to consider moving some of these logs down to the debug level.
|
||||
|
||||
\warning You are strongly advised to avoid the use of the generic logging macros (e.g. qDebug(), qInfo(), qWarn()).
|
||||
|
||||
\note You should instead use the corresponding category logging macros (qCDebug(), qCInfo(), qCWarn()) and define
|
||||
logging
|
||||
categories for your log statements.
|
||||
|
||||
Example:
|
||||
|
||||
```c++
|
||||
in .h
|
||||
|
||||
inline Q_LOGGING_CATEGORY(ExampleCategory, "cockatrice_example_category");
|
||||
inline Q_LOGGING_CATEGORY(ExampleSubCategory, "cockatrice_example_category.sub_category");
|
||||
|
||||
in .cpp
|
||||
|
||||
qCInfo(ExampleCategory) << "Info level logs are usually sent through the main category"
|
||||
qCDebug(ExampleSubCategory) << "Debug level logs are permitted their own category to allow selective silencing"
|
||||
```
|
||||
|
||||
For more information on how to enable or disable logging categories,
|
||||
see [Logging Configuration](#logging-configuration).
|
||||
|
||||
# Logging Configuration
|
||||
|
||||
For configuring our logging, we use the qtlogging.ini, located under cockatrice/resources/config/qtlogging.ini, which is
|
||||
baked into the application in release version and set as the QT_LOGGING_CONF environment variable in main.cpp.
|
||||
|
||||
```c++
|
||||
#ifdef Q_OS_APPLE
|
||||
// <build>/cockatrice/cockatrice.app/Contents/MacOS/cockatrice
|
||||
const QByteArray configPath = "../../../qtlogging.ini";
|
||||
#elif defined(Q_OS_UNIX)
|
||||
// <build>/cockatrice/cockatrice
|
||||
const QByteArray configPath = "./qtlogging.ini";
|
||||
#elif defined(Q_OS_WIN)
|
||||
// <build>/cockatrice/Debug/cockatrice.exe
|
||||
const QByteArray configPath = "../qtlogging.ini";
|
||||
#else
|
||||
const QByteArray configPath = "";
|
||||
#endif
|
||||
|
||||
if (!qEnvironmentVariableIsSet(("QT_LOGGING_CONF"))) {
|
||||
// Set the QT_LOGGING_CONF environment variable
|
||||
qputenv("QT_LOGGING_CONF", configPath);
|
||||
}
|
||||
```
|
||||
|
||||
For more information on how to use this file and on how Qt evaluates which logging rules/file to use, please
|
||||
see the [official Qt documentation](https://doc.qt.io/qt-6/qloggingcategory.html#configuring-categories).
|
||||
|
||||
Some examples:
|
||||
|
||||
```
|
||||
# Turn off all logging except everything from card_picture_loader and all sub categories
|
||||
|
||||
[Rules]
|
||||
# The default log level is info
|
||||
*.debug = false
|
||||
*.info = false
|
||||
*.warning = false
|
||||
*.critical = false
|
||||
*.fatal = false
|
||||
|
||||
card_picture_loader.* = true
|
||||
```
|
||||
|
||||
```
|
||||
# Turn off all logging except info level logs from card_picture_loader and all sub categories
|
||||
|
||||
[Rules]
|
||||
# The default log level is info
|
||||
*.debug = false
|
||||
*.info = false
|
||||
*.warning = false
|
||||
*.critical = false
|
||||
*.fatal = false
|
||||
|
||||
card_picture_loader.*.info = true
|
||||
```
|
||||
|
||||
```
|
||||
[Rules]
|
||||
# Turn on debug level logs for card_picture_loader but keep logging for sub categories suppressed
|
||||
*.debug = false
|
||||
|
||||
card_picture_loader.debug = true
|
||||
```
|
||||
|
||||
```
|
||||
[Rules]
|
||||
# Turn on all logs for worker subcategory of card_picture_loader
|
||||
*.debug = false
|
||||
|
||||
card_picture_loader.worker = true
|
||||
```
|
||||
|
||||
```
|
||||
[Rules]
|
||||
# Turn off some noisy and irrelevant startup logging for local development
|
||||
*.debug = false
|
||||
|
||||
qt_translator = false
|
||||
window_main.* = false
|
||||
release_channel = false
|
||||
spoiler_background_updater = false
|
||||
theme_manager = false
|
||||
sound_engine = false
|
||||
tapped_out_interface = false
|
||||
card_database = false
|
||||
card_database.loading = false
|
||||
card_database.loading.success_or_failure = true
|
||||
cockatrice_xml.* = false
|
||||
```
|
||||
|
||||
# Logging Setup
|
||||
|
||||
This is achieved through our logging setup in @ref main.cpp, where we set the message pattern and install a custom
|
||||
logger which replaces the full file path at the end with just the file name (Qt shows the full and quite lengthy path by
|
||||
default).
|
||||
|
||||
```c++
|
||||
qSetMessagePattern(
|
||||
"\033[0m[%{time yyyy-MM-dd h:mm:ss.zzz} "
|
||||
"%{if-debug}\033[36mD%{endif}%{if-info}\033[32mI%{endif}%{if-warning}\033[33mW%{endif}%{if-critical}\033[31mC%{"
|
||||
"endif}%{if-fatal}\033[1;31mF%{endif}\033[0m] [%{function}] - %{message} [%{file}:%{line}]");
|
||||
QApplication app(argc, argv);
|
||||
|
||||
QObject::connect(&app, &QApplication::lastWindowClosed, &app, &QApplication::quit);
|
||||
|
||||
qInstallMessageHandler(CockatriceLogger);
|
||||
```
|
||||
|
||||
```c++
|
||||
static void CockatriceLogger(QtMsgType type, const QMessageLogContext &ctx, const QString &message)
|
||||
{
|
||||
QString logMessage = qFormatLogMessage(type, ctx, message);
|
||||
|
||||
// Regular expression to match the full path in the square brackets and extract only the filename and line number
|
||||
QRegularExpression regex(R"(\[(?:.:)?[\/\\].*[\/\\]([^\/\\]+\:\d+)\])");
|
||||
QRegularExpressionMatch match = regex.match(logMessage);
|
||||
|
||||
if (match.hasMatch()) {
|
||||
// Extract the filename and line number (e.g., "main.cpp:211")
|
||||
QString filenameLine = match.captured(1);
|
||||
|
||||
// Replace the full path in square brackets with just the filename and line number
|
||||
logMessage.replace(match.captured(0), QString("[%1]").arg(filenameLine));
|
||||
}
|
||||
|
||||
Logger::getInstance().log(type, ctx, logMessage);
|
||||
}
|
||||
```
|
||||
@@ -0,0 +1,71 @@
|
||||
@page primer_cards A Primer on Cards
|
||||
|
||||
# The Cockatrice Card Library
|
||||
|
||||
All non-gui code related to cards used by Cockatrice is contained within libcockatrice_card.
|
||||
|
||||
# A Basic Card Object: CardInfo
|
||||
|
||||
A CardInfo object is the translational unit used by the CardDatabase to represent an on-disk XML entry as an in-memory
|
||||
Qt object.
|
||||
|
||||
For a complete overview of the fields that define a CardInfo object, see the class documentation and more specifically
|
||||
@ref PrivateCardProperties.
|
||||
|
||||
These fields correspond to either entries or a combination of entries in the XML card entry to which the
|
||||
CardDatabaseParser applies special logic to map, populate or determine their respective values in the CardInfo object.
|
||||
|
||||
Any property to which special parsing is not applied is stored in CardInfo::properties and may be retrieved or set with
|
||||
CardInfo::getProperty() or CardInfo::setProperty() as well as CardInfo::getProperties() to get a collection of the
|
||||
property keys a CardInfo contains.
|
||||
|
||||
For more information on how special fields contained within @ref PrivateCardProperties are parsed, see
|
||||
CockatriceXml4Parser::loadCardsFromXml().
|
||||
|
||||
Apart from access to the basic and extended properties of a card, CardInfo also provides two important mechanisms to us.
|
||||
The first is the CardInfo::pixmapUpdated() signal, which allows the CardPictureLoader to signal when it is done
|
||||
manipulating (in most cases: loading) the QPixmap of an ExactCard::getPixmapCacheKey(), where the ExactCard::card
|
||||
corresponds to this CardInfo object.
|
||||
|
||||
Put simply: Whenever the CardPictureLoader loads a new PrintingInfo which is not already in the cache, it emits this
|
||||
signal so that any widget using a CardInfo object can update the display of it to possibly use this new QPixmap.
|
||||
|
||||
\attention It should be noted that it is not possible to use CardPictureLoader::getPixmap() with anything but an
|
||||
ExactCard, which is a CardInfo object associated with a PrintingInfo, i.e. a definitive printing of a specific card
|
||||
|
||||
The other signal, CardInfo::cardInfoChanged() conceptually works much the same way, except it is concerned with the
|
||||
properties of the CardInfo object.
|
||||
|
||||
# Getting specific: PrintingInfo and ExactCard
|
||||
|
||||
## Printing Info
|
||||
|
||||
A CardInfo object describes the basic properties of a card in much the same way that we say "Two cards with the same
|
||||
name are and should be equal if their properties are equal". However, there are certain (mostly visual) properties which
|
||||
might differ between printings of a card but still conceptually classify two instances of a card as "the same card".
|
||||
The most obvious example to this are cards which fundamentally share all properties except the artwork depicted on the
|
||||
card.
|
||||
|
||||
We refer to such differences as Printings and track them in the PrintingInfo class. A PrintingInfo is always related to
|
||||
the CardSet that introduced the variation. Multiple variations can exist in the same CardSet and the respective
|
||||
PrintingInfo::getProperty() can be used to determine the differences, such as the collector numbers on the printings, if
|
||||
there are any.
|
||||
|
||||
## Exact Card
|
||||
|
||||
A CardInfo object is used to hold the functional properties of a card and a PrintingInfo object can be used to hold the
|
||||
visual properties of a card. To represent a 'physical' card, as in, a concrete immutable instance of a card, we can use
|
||||
ExactCard, which combines a CardInfo and a PrintingInfo object into one class. The class is used as a container around
|
||||
CardInfo objects whenever the user (and thus the program) expects to be presented with a defined card printing.
|
||||
|
||||
# Using Cards
|
||||
|
||||
For more information on the XML database schema which the CardDatabaseParser parses to generate CardInfo objects, see
|
||||
@ref card_database_schema_and_parsing.
|
||||
|
||||
For more information on querying the CardDatabase for CardInfo objects, see @ref querying_the_card_database.
|
||||
|
||||
For more information on displaying CardInfo and ExactCard objects using Qt Widgets, see @ref displaying_cards.
|
||||
|
||||
For more information on how card pictures are loaded from disk or the network, see @ref loading_card_pictures as well as
|
||||
the CardPictureLoader documentation.
|
||||
@@ -0,0 +1,39 @@
|
||||
@page querying_the_card_database Querying the Card Database
|
||||
|
||||
# The CardDatabaseQuerier Class
|
||||
|
||||
The CardDatabaseQuerier is the only class used for querying the database. The CardDatabase is an in-memory map and thus
|
||||
provides no structured query language. CardDatabaseQuerier offers methods to retrieve cards by name, by providerID or in
|
||||
bulk, as CardSet%s.
|
||||
|
||||
## Obtaining a handle to the CardDatabaseQuerier for usage
|
||||
|
||||
To obtain the CardDatabaseQuerier related to the global CardDatabase singleton, use CardDatabaseManager::query().
|
||||
|
||||
## Querying for known cards
|
||||
|
||||
There are, essentially, two ways to ensure card equality, with the second being optional but necessitating the first.
|
||||
These two ways are CardInfo name equality and PrintingInfo provider ID equality.
|
||||
|
||||
Because of this, most queries require, at the very least, a card name to match against and optionally a providerID to
|
||||
narrow the results.
|
||||
|
||||
### Generic Card Infos
|
||||
|
||||
To check if a card with the exact provided name exists as a CardInfo in the CardDatabase use,
|
||||
CardDatabaseQuerier::getCardInfo() or CardDatabaseQuerier::getCardInfos() for multiple cards.
|
||||
|
||||
### Guessing Cards
|
||||
|
||||
If the exact name might not be present in the CardDatabase, you can use CardDatabaseQuerier::getCardBySimpleName(),
|
||||
which automatically simplifies the card name and matches it against simplified card names in the CardDatabase.
|
||||
|
||||
Alternatively, you can use CardDatabaseQuerier::lookupCardByName(), which first attempts an exact match search and then
|
||||
uses CardDatabaseQuerier::getCardBySimpleName() as a fallback.
|
||||
|
||||
### ExactCard%s
|
||||
|
||||
To obtain an ExactCard from the CardDatabaseQuerier, you must use a CardRef as a parameter to
|
||||
CardDatabaseQuerier::getCard(), CardDatabaseQuerier::getCards(), or CardDatabaseQuerier::guessCard().
|
||||
|
||||
CardRef is a simple struct consisting of a card name and a card provider ID as QString%s.
|
||||
Reference in New Issue
Block a user