diff --git a/Doxyfile b/Doxyfile index 5b125ef13..a1861f64f 100644 --- a/Doxyfile +++ b/Doxyfile @@ -991,7 +991,7 @@ WARN_LOGFILE = # spaces. See also FILE_PATTERNS and EXTENSION_MAPPING # Note: If this tag is empty the current directory is searched. -INPUT = cockatrice doc/doxygen-groups libcockatrice_card libcockatrice_deck_list libcockatrice_filters libcockatrice_interfaces libcockatrice_models libcockatrice_network libcockatrice_protocol libcockatrice_rng libcockatrice_settings libcockatrice_utility +INPUT = cockatrice doc/doxygen-extra-pages doc/doxygen-groups libcockatrice_card libcockatrice_deck_list libcockatrice_filters libcockatrice_interfaces libcockatrice_models libcockatrice_network libcockatrice_protocol libcockatrice_rng libcockatrice_settings libcockatrice_utility # This tag can be used to specify the character encoding of the source files # that Doxygen parses. Internally Doxygen uses the UTF-8 encoding. Doxygen uses @@ -1145,7 +1145,7 @@ EXAMPLE_RECURSIVE = NO # that contain images that are to be included in the documentation (see the # \image command). -IMAGE_PATH = +IMAGE_PATH = doc/doxygen-images # The INPUT_FILTER tag can be used to specify a program that Doxygen should # invoke to filter for each input file. Doxygen will invoke the filter program diff --git a/doc/doxygen-extra-pages/developer_documentation/card_database_schema_and_parsing.md b/doc/doxygen-extra-pages/developer_documentation/card_database_schema_and_parsing.md new file mode 100644 index 000000000..6c5e3512b --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc/doxygen-extra-pages/developer_documentation/displaying_cards.md b/doc/doxygen-extra-pages/developer_documentation/displaying_cards.md new file mode 100644 index 000000000..6a43097c5 --- /dev/null +++ b/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 + + + diff --git a/doc/doxygen-extra-pages/developer_documentation/index.md b/doc/doxygen-extra-pages/developer_documentation/index.md index 121ee7c6f..b26faf836 100644 --- a/doc/doxygen-extra-pages/developer_documentation/index.md +++ b/doc/doxygen-extra-pages/developer_documentation/index.md @@ -1,3 +1,9 @@ @page developer_reference Developer Reference -- [Contributing](@subpage contributing) +- @subpage primer_cards + +- @subpage card_database_schema_and_parsing +- @subpage querying_the_card_database + +- @subpage loading_card_pictures +- @subpage displaying_cards \ No newline at end of file diff --git a/doc/doxygen-extra-pages/developer_documentation/loading_card_pictures.md b/doc/doxygen-extra-pages/developer_documentation/loading_card_pictures.md new file mode 100644 index 000000000..b606f9e4b --- /dev/null +++ b/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 \ No newline at end of file diff --git a/doc/doxygen-extra-pages/developer_documentation/primer_cards.md b/doc/doxygen-extra-pages/developer_documentation/primer_cards.md new file mode 100644 index 000000000..8f79adbc9 --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/doxygen-extra-pages/developer_documentation/querying_the_card_database.md b/doc/doxygen-extra-pages/developer_documentation/querying_the_card_database.md new file mode 100644 index 000000000..b2812b0ad --- /dev/null +++ b/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. \ No newline at end of file diff --git a/doc/doxygen-extra-pages/user_documentation/deck_management/creating_decks.md b/doc/doxygen-extra-pages/user_documentation/deck_management/creating_decks.md new file mode 100644 index 000000000..0de587b64 --- /dev/null +++ b/doc/doxygen-extra-pages/user_documentation/deck_management/creating_decks.md @@ -0,0 +1,17 @@ +@page creating_decks Creating Decks + +Creating a new deck is done using either the TabDeckEditor or TabDeckEditorVisual. + +They can be accessed either by clicking the "Create Deck" button in the TabHome screen, which will open the default deck +editor configured in the "User Interface" -> "Deck editor/storage settings" -> "Default deck editor type" setting, or +by selecting "Deck Editor" or "Visual Deck Editor" under the "Tabs" application menu located at the top. + +# Further References + +See @ref editing_decks for information on how to modify the attributes and contents of a deck in the Deck Editor +widgets. + +See @ref exporting_decks for information on how to store and persist your deck either in-client or to external +services. + +See @ref importing_decks for information on how to import existing decks either in-client or from external services \ No newline at end of file diff --git a/doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks.md b/doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks.md new file mode 100644 index 000000000..d8b96dac3 --- /dev/null +++ b/doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks.md @@ -0,0 +1,5 @@ +@page editing_decks Editing Decks + +@subpage editing_decks_classic + +@subpage editing_decks_visual \ No newline at end of file diff --git a/doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks_classic.md b/doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks_classic.md new file mode 100644 index 000000000..f9f2239bc --- /dev/null +++ b/doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks_classic.md @@ -0,0 +1,54 @@ +@page editing_decks_classic Classic Deck Editor + +\image html classic_deck_editor.png width=900px + +# Editing Basic Deck Information + +Editing basic deck information is done through the deck dock widget (DeckEditorDeckDockWidget). + +\image html deckeditordeckdockwidget.png + +This widget allows editing: + +- The name +- The comments +- The banner card, which is used to represent the deck in the visual deck storage +- The tags, which are used for filtering in the visual deck storage + +# Adding Cards + +Adding cards is done using the list of cards in the database presented in the list view on the left. + +\image html classic_database_display.png + +Cards can be added by either double-clicking an entry, pressing return with an entry selected to add it to the mainboard +or pressing ctrl/cmd + return to add it to the sideboard. + +There are also buttons for these two functions on the right of the search bar above the list view. + +\image html classic_database_display_add_buttons.png + +# Modifying the Deck List + +To modify or remove cards in the deck list, the tree list view in the deck dock widget can be used. + +\image html deck_dock_deck_list.png + +Just above the list, at the top right, there are four buttons to manipulate the currently selected card(s): + +- Increment Card +- Decrement Card +- Remove Card +- Switch Card between Mainboard and Sideboard + +\image html deck_dock_deck_list_buttons.png + +Additionally, there is a combo box above the list, which may be used to change how cards are grouped in the list +display. This is only for visual display and does not affect how the list is saved. + +\image html deck_dock_deck_list_group_by.png + +# Modifying printings + +For more information on modifying the printings in a deck see @ref editing_decks_printings + diff --git a/doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks_printings.md b/doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks_printings.md new file mode 100644 index 000000000..27ade3f63 --- /dev/null +++ b/doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks_printings.md @@ -0,0 +1 @@ +@page editing_decks_printings Printing Selector \ No newline at end of file diff --git a/doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks_visual.md b/doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks_visual.md new file mode 100644 index 000000000..adef7335f --- /dev/null +++ b/doc/doxygen-extra-pages/user_documentation/deck_management/editing_decks_visual.md @@ -0,0 +1,71 @@ +@page editing_decks_visual Visual Deck Editor + +# Editing Basic Deck Information + +Editing basic deck information is done through the deck dock widget (DeckEditorDeckDockWidget). + +\image html deckeditordeckdockwidget.png + +This widget allows editing: + +- The name +- The comments +- The banner card, which is used to represent the deck in the visual deck storage +- The tags, which are used for filtering in the visual deck storage + +# Adding Cards + +Adding cards is done by either using the "Quick search and add card" search bar at the top of the "Visual Deck View" tab +or by clicking on a picture of a card in the "Visual Database Display" tab. + +See @ref visual_database_display for more information on how to utilize the visual database display. + +# Modifying the Deck List + +To modify or remove cards in the deck list, the tree list view in the deck dock widget can be used. + +Just above the list, at the top right, there are four buttons to manipulate the currently selected card(s): + +- Increment Card +- Decrement Card +- Remove Card +- Switch Card between Mainboard and Sideboard + +Additionally, there is a combo box above the list, which may be used to change how cards are grouped in the list +display. This is only for visual display and does not affect how the list is saved. + +# Modifying the visual deck layout + +The visual deck editor displays cards visually, as opposed to simply in list form in the Deck Dock Widget. Each entry in +the deck list is represented by a picture. These entries are grouped together under their respective sub-groups. +Sub-groups may be collapsed (i.e. the pictures contained within them are hidden) by clicking on the name of the group in +the banner. + +Cards may either be displayed in a "Flat" layout, which displays each picture next to each other and ensures full +visibility for each card, or in an "Overlap" layout, which overlaps cards on top of each other (leaving the top 20% of +the card uncovered so names remain readable) and arranges them in stacks to save space and allow for an easy overview. + +Additionally, it is possible to change how the cards in the deck list are grouped by selecting a different grouping +method from the combo box, either in the top left of the "Visual Deck View" tab or above the list view in the deck dock +widget. + +Furthermore, it is possible to change how the cards are sorted within the sub-group. This is done by clicking on the +button with the cogwheel icon next to the combo box that adjusts grouping in the top left of the "Visual Deck View" tab. +This presents a list of available sort criteria, which may be rearranged to change their priorities. + +# Modifying printings + +For more information on modifying the printings in a deck see @ref editing_decks_printings + +# Deck Analytics + +The visual deck editor offers a "Deck Analytics" tab, which displays information about: + +- The mana curve +- The mana devotion +- The mana base + +# Sample Hand + +The visual deck editor offers a "Sample Hand" tab, which allows simulating drawing a configurable amount of cards from +the deck, which reduces the need to launch a single player game for testing purposes. \ No newline at end of file diff --git a/doc/doxygen-extra-pages/user_documentation/deck_management/exporting_decks.md b/doc/doxygen-extra-pages/user_documentation/deck_management/exporting_decks.md new file mode 100644 index 000000000..644336681 --- /dev/null +++ b/doc/doxygen-extra-pages/user_documentation/deck_management/exporting_decks.md @@ -0,0 +1,95 @@ +@page exporting_decks Exporting Decks + +# Where to export? + +There are two screens in the client which can be used to import decks, depending on the context. + +- The deck editor tab +- The deck storage tab (not to be confused with the visual deck storage tab) + +# The Deck Editor Tab + +The deck editor tabs (Classic and Visual) offer three ways of export a deck: + +- To a file on your local storage +- To your clipboard +- To an online service + +## Local File Storage + +To save a deck to a file on your local storage, select the "Save Deck" action in the "Deck Editor" or "Visual Deck +Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd + S +to access this action. + +Selecting this action will open a file picker dialog provided by your operating system. Simply enter a file name and +select a format (.cod is recommended) and confirm. + +Just below the "Save Deck" action described above is the "Save Deck as..." option, which allows saving an existing file +under a different filename, which is useful for saving a different version or copy of a deck. + +## From Clipboard + +To save a deck to your clipboard, select the "Save deck to clipboard..." action in the "Deck Editor" or "Visual Deck +Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd + +Shift + C or Ctrl/Cmd + Shift + R to access this action. + +Selecting this action will save the currently open deck list to your clipboard. + +Saving the decklist without annotations will export the decklist, with each card being described in the following format + +``` +CARD_AMOUNT CARD_NAME (SET_SHORT_NAME) CARD_COLLECTOR_NUMBER +``` + +There is also the (no set info) option, which will simply export each card as + +``` +CARD_AMOUNT CARD_NAME +``` + +Mainboard and sideboard are delimited by a newline like so: + +``` +1 MainboardCard +1 OtherMainboardCard + +1 SideboardCard +``` + +Saving the decklist as annotated will insert comments (marked with // in front of them). +It will first insert the name and any comments associated with the deck before separating each deck section into its own +newline delimited and annotated group. + +Example: TODO: Adjust this to be non mtg based. + +``` +// Deck Name + +// Deck Comment + +// 10 Maindeck +// 6 Artifact +2 The Darkness Crystal (FIN) 335 +2 The Fire Crystal (FIN) 337 +2 Black Mage's Rod (FIN) 90 + +// 6 Sorcery +2 Nibelheim Aflame (FIN) 339 +4 Cornered by Black Mages (FIN) 93 + +// 6 Sideboard +// 6 Creature +SB: 4 Blazing Bomb (FIN) 130 +SB: 1 Garland, Knight of Cornelia (FIN) 221 +SB: 1 Undercity Dire Rat (FIN) 123 +``` + +## From an online service + +To export a deck to an online service, select the "Send deck to online service..." action in the "Deck Editor" or " +Visual Deck Editor" menu in the application menu bar at the top of the screen. + +Selecting this action will open your browser with the selected service open and the deck list information from the +client supplied to it. + +Currently supported services are DeckList and TappedOut. \ No newline at end of file diff --git a/doc/doxygen-extra-pages/user_documentation/deck_management/importing_decks.md b/doc/doxygen-extra-pages/user_documentation/deck_management/importing_decks.md new file mode 100644 index 000000000..e9626d57f --- /dev/null +++ b/doc/doxygen-extra-pages/user_documentation/deck_management/importing_decks.md @@ -0,0 +1,62 @@ +@page importing_decks Importing Decks + +# Where to import? + +There are three screens in the client which can be used to import decks, depending on the context. + +- The deck editor tab +- The pre-game lobby tab +- The deck storage tab (not to be confused with the visual deck storage tab) + +# The Deck Editor Tab + +The deck editor tabs (Classic and Visual) offer three ways of importing a deck: + +- From a file on your local storage +- From your clipboard +- From an online service + +## Local File Storage + +To load a deck from a file on your local storage, select the "Load Deck" action in the "Deck Editor" or "Visual Deck +Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd + O +to access this action. + +Selecting this action will open a file picker dialog provided by your operating system. Simply select a supported file +here and it will be loaded. + +Just below the "Load Deck" action described above is the "Load recent deck" option, which keeps a record of the last 10 +loaded decks for quick access. + +## From Clipboard + +To load a deck from your clipboard, select the "Load deck from clipboard..." action in the "Deck Editor" or "Visual Deck +Editor" menu in the application menu bar at the top of the screen. Alternatively, you can use the shortcut Ctrl/Cmd + +Shift + V to access this action. + +Selecting this action will open a new text editor dialog with the contents of your clipboard pasted inside it. + +The import dialog expects each line to be a card with the following format: + +TODO + +Each card should be on a separate line and there should be no empty lines between cards. The first empty line between +two blocks of cards will be considered as the divider between mainboard and sideboard. + +Selecting "Parse Set Name and Number (if available)" will automatically parse these options and attempt to resolve them +to valid provider IDs found in the card database. If this option is unselected, Cockatrice will import all cards as +versions without provider IDs, which means they will display to everyone according to their own user defined set +preferences, rather than being the same defined printing for everyone. + +## From an online service + +To load a deck from an online service, select the "Load deck from online service..." action in the "Deck Editor" or " +Visual Deck Editor" menu in the application menu bar at the top of the screen. + +Selecting this action will open a dialog containing the contents of your clipboard pasted into it. If your clipboard +currently contains a supported URL, the dialog will accept it and close on its own, otherwise you may adjust the URL and +confirm. + +The action will automatically import the deck from the online service without any other required user action. + +Currently supported services are Archidekt, Deckstats, Moxfield, and TappedOut. \ No newline at end of file diff --git a/doc/doxygen-extra-pages/user_documentation/index.md b/doc/doxygen-extra-pages/user_documentation/index.md index 97c6f375c..8a5c88c37 100644 --- a/doc/doxygen-extra-pages/user_documentation/index.md +++ b/doc/doxygen-extra-pages/user_documentation/index.md @@ -1,4 +1,13 @@ @page user_reference User Reference @subpage search_syntax_help -@subpage deck_search_syntax_help \ No newline at end of file + +@subpage deck_search_syntax_help + +@subpage creating_decks + +@subpage importing_decks + +@subpage editing_decks + +@subpage exporting_decks \ No newline at end of file diff --git a/doc/doxygen-images/classic_database_display.png b/doc/doxygen-images/classic_database_display.png new file mode 100644 index 000000000..1f4773514 Binary files /dev/null and b/doc/doxygen-images/classic_database_display.png differ diff --git a/doc/doxygen-images/classic_database_display_add_buttons.png b/doc/doxygen-images/classic_database_display_add_buttons.png new file mode 100644 index 000000000..b9cb7cd32 Binary files /dev/null and b/doc/doxygen-images/classic_database_display_add_buttons.png differ diff --git a/doc/doxygen-images/classic_deck_editor.png b/doc/doxygen-images/classic_deck_editor.png new file mode 100644 index 000000000..2e41b6e1d Binary files /dev/null and b/doc/doxygen-images/classic_deck_editor.png differ diff --git a/doc/doxygen-images/deck_dock_deck_list.png b/doc/doxygen-images/deck_dock_deck_list.png new file mode 100644 index 000000000..d01a5334e Binary files /dev/null and b/doc/doxygen-images/deck_dock_deck_list.png differ diff --git a/doc/doxygen-images/deck_dock_deck_list_buttons.png b/doc/doxygen-images/deck_dock_deck_list_buttons.png new file mode 100644 index 000000000..cb66b41da Binary files /dev/null and b/doc/doxygen-images/deck_dock_deck_list_buttons.png differ diff --git a/doc/doxygen-images/deck_dock_deck_list_group_by.png b/doc/doxygen-images/deck_dock_deck_list_group_by.png new file mode 100644 index 000000000..ba23b1fb5 Binary files /dev/null and b/doc/doxygen-images/deck_dock_deck_list_group_by.png differ diff --git a/doc/doxygen-images/deckeditordeckdockwidget.png b/doc/doxygen-images/deckeditordeckdockwidget.png new file mode 100644 index 000000000..d71720db7 Binary files /dev/null and b/doc/doxygen-images/deckeditordeckdockwidget.png differ diff --git a/libcockatrice_card/libcockatrice/card/card_info.h b/libcockatrice_card/libcockatrice/card/card_info.h index c2a8453d9..598313789 100644 --- a/libcockatrice_card/libcockatrice/card/card_info.h +++ b/libcockatrice_card/libcockatrice/card/card_info.h @@ -1,9 +1,3 @@ -/** - * @file card_info.h - * @ingroup Cards - * @brief TODO: Document this. - */ - #ifndef CARD_INFO_H #define CARD_INFO_H @@ -54,6 +48,10 @@ class CardInfo : public QObject Q_OBJECT private: + /** @name Private Card Properties + * @anchor PrivateCardProperties + */ + ///@{ CardInfoPtr smartThis; ///< Smart pointer to self for safe cross-references. QString name; ///< Full name of the card. QString simpleName; ///< Simplified name for fuzzy matching. @@ -69,6 +67,7 @@ private: bool landscapeOrientation; ///< Orientation flag for rendering. int tableRow; ///< Row index in a table or visual representation. bool upsideDownArt; ///< Whether artwork is flipped for visual purposes. + ///@} public: /** diff --git a/libcockatrice_card/libcockatrice/card/database/card_database.h b/libcockatrice_card/libcockatrice/card/database/card_database.h index 4b2769fcb..191298142 100644 --- a/libcockatrice_card/libcockatrice/card/database/card_database.h +++ b/libcockatrice_card/libcockatrice/card/database/card_database.h @@ -1,10 +1,3 @@ -/** - * @file card_database.h - * @ingroup CardDatabase - * @brief The CardDatabase is responsible for holding the card and set maps, managing card additions/removals, - * and providing access to sets and card querying via CardDatabaseQuerier. - */ - #ifndef CARDDATABASE_H #define CARDDATABASE_H diff --git a/libcockatrice_card/libcockatrice/card/database/card_database_loader.h b/libcockatrice_card/libcockatrice/card/database/card_database_loader.h index 7bf02cc9a..db1376ac7 100644 --- a/libcockatrice_card/libcockatrice/card/database/card_database_loader.h +++ b/libcockatrice_card/libcockatrice/card/database/card_database_loader.h @@ -1,12 +1,3 @@ -/** - * @file card_database_loader.h - * @ingroup CardDatabase - * @brief The CardDatabaseLoader is responsible for discovering, loading, and saving card databases from files on disk. - * - * This class interacts with available parsers to populate a CardDatabase instance. It also handles - * loading main, token, spoiler, and custom card databases. - */ - #ifndef COCKATRICE_CARD_DATABASE_LOADER_H #define COCKATRICE_CARD_DATABASE_LOADER_H diff --git a/libcockatrice_card/libcockatrice/card/printing/exact_card.h b/libcockatrice_card/libcockatrice/card/printing/exact_card.h index b36233bd5..01c61a3a1 100644 --- a/libcockatrice_card/libcockatrice/card/printing/exact_card.h +++ b/libcockatrice_card/libcockatrice/card/printing/exact_card.h @@ -5,7 +5,7 @@ /** * @class ExactCard - * @ingroup Cards + * @ingroup CardPrintings * * @brief Represents a specific card instance, defined by its CardInfo * and a particular printing. diff --git a/libcockatrice_card/libcockatrice/card/printing/printing_info.h b/libcockatrice_card/libcockatrice/card/printing/printing_info.h index cacb98068..37d7a15e2 100644 --- a/libcockatrice_card/libcockatrice/card/printing/printing_info.h +++ b/libcockatrice_card/libcockatrice/card/printing/printing_info.h @@ -14,7 +14,7 @@ using SetToPrintingsMap = QMap>; /** * @class PrintingInfo - * @ingroup Cards + * @ingroup CardPrintings * * @brief Represents metadata for a specific variation of a card within a set. * diff --git a/libcockatrice_card/libcockatrice/card/set/card_set.h b/libcockatrice_card/libcockatrice/card/set/card_set.h index b3e35f2db..5fc769bb6 100644 --- a/libcockatrice_card/libcockatrice/card/set/card_set.h +++ b/libcockatrice_card/libcockatrice/card/set/card_set.h @@ -15,7 +15,7 @@ using CardSetPtr = QSharedPointer; /** * @class CardSet - * @ingroup Cards + * @ingroup CardSets * * @brief A collection of cards grouped under a common identifier. * diff --git a/libcockatrice_card/libcockatrice/card/set/card_set_comparator.h b/libcockatrice_card/libcockatrice/card/set/card_set_comparator.h index 53e2cb97d..96f1052a9 100644 --- a/libcockatrice_card/libcockatrice/card/set/card_set_comparator.h +++ b/libcockatrice_card/libcockatrice/card/set/card_set_comparator.h @@ -1,6 +1,6 @@ /** * @file card_set_comparator.h - * @ingroup Cards + * @ingroup CardSets * @brief TODO: Document this. */ diff --git a/libcockatrice_card/libcockatrice/card/set/card_set_list.h b/libcockatrice_card/libcockatrice/card/set/card_set_list.h index 2e644a277..21b4a55d4 100644 --- a/libcockatrice_card/libcockatrice/card/set/card_set_list.h +++ b/libcockatrice_card/libcockatrice/card/set/card_set_list.h @@ -8,7 +8,7 @@ /** * @class CardSetList - * @ingroup Cards + * @ingroup CardSets * * @brief A list-like container for CardSet objects with extended management methods. *