Doxygen: Improve file structure and includes (#6344)

doc/doxygen/extra-pages/developer_documentation/card_database_schema_and_parsing.md

@@ -0,0 +1 @@
+@page card_database_schema_and_parsing Card Database Schema and Parsing

doc/doxygen/extra-pages/developer_documentation/displaying_cards.md

@@ -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
+
+
+

doc/doxygen/extra-pages/developer_documentation/index.md

@@ -0,0 +1,9 @@
+@page developer_reference Developer Reference
+
+- @subpage primer_cards
+
+- @subpage card_database_schema_and_parsing
+- @subpage querying_the_card_database
+
+- @subpage loading_card_pictures
+- @subpage displaying_cards

doc/doxygen/extra-pages/developer_documentation/loading_card_pictures.md

@@ -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

doc/doxygen/extra-pages/developer_documentation/primer_cards.md

@@ -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.

doc/doxygen/extra-pages/developer_documentation/querying_the_card_database.md

@@ -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.