gitea-mirror/Cockatrice
1
0
Fork 0
mirror of https://github.com/Cockatrice/Cockatrice.git synced 2025-12-22 23:26:14 -08:00
Code Issues Packages Projects Releases Wiki Activity

Doxygen: Improve file structure and includes (#6344)

Browse Source
This commit is contained in:
tooomm
2025-11-22 19:38:39 +01:00
committed by GitHub
parent 73591d5d0f
commit 621c6a8d73
37 changed files with 7 additions and 153 deletions
Download Patch File Download Diff File Expand all files Collapse all files

17
doc/doxygen/extra-pages/user_documentation/deck_management/creating_decks.md Normal file
View File

@@ -0,0 +1,17 @@
@page creating_decks Creating Decks
Creating a new deck is done using either the \ref editing_decks_classic or \ref editing_decks_visual.
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

7
doc/doxygen/extra-pages/user_documentation/deck_management/editing_decks.md Normal file
View File

@@ -0,0 +1,7 @@
@page editing_decks Editing Decks
@subpage editing_decks_classic
@subpage editing_decks_visual
@subpage editing_decks_printings

54
doc/doxygen/extra-pages/user_documentation/deck_management/editing_decks_classic.md Normal file
View File

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

122
doc/doxygen/extra-pages/user_documentation/deck_management/editing_decks_printings.md Normal file
View File

@@ -0,0 +1,122 @@
@page editing_decks_printings Printing Selector
\image html printing_selector.png
# Purpose
The PrintingSelector allows editing the PrintingInfo associated with CardInfo%s contained in DeckList%s.
As described in PrintingInfo, a CardInfo can have different variations contained within the same or different CardSet%s.
PrintingSelector allows the user to choose a variation, as well as pinning a variation to be used as the preferred
printing in all cases where the 'default' or 'most preferred' image should be shown.
# Pre-requisites (User Interface)
To use the printing selector, ensure that you are using the Post-ProviderID change behavior (Checkbox as shown in the
image).
\image html printing_selector_pre_providerid.png
\attention This is the default behavior, unless you have explicitly changed it, in which case you will have seen a
warning as follows. Once again, checking this box will *disable* the new behavior and revert you to the legacy system
without the printing selector.
Disabling the printing selector:
\image html printing_selector_enable.png
Enabling the printing selector:
\image html printing_selector_disable.png
# Pre-requisites (Card Database)
The PrintingSelector requires each underlying CardInfo object to have a <set> entry with a *unique* providerID attribute
for each variation that should be displayed.
Here is an example, that first defines three sets, and then the 'Ace of Hearts' card with three variations.
```xml
<set rarity="common" uuid="00000000-0000-0000-0000-000000000033" num="51" muid="AH">PKR</set>
<set rarity="common" uuid="00000000-0000-0000-0001-000000000033" num="51" muid="AHSTD">STD</set>
<set rarity="common" uuid="00000000-0000-0000-0002-000000000033" num="51" muid="AHNBR">NBR</set>
```
```xml
<?xml version='1.0' encoding='UTF-8'?>
<cockatrice_carddatabase version="4">
<sets>
<set>
<name>PKR</name>
<longname>Cockatrice Poker</longname>
<settype>Custom</settype>
<releasedate>2025-11-15</releasedate>
</set>
<set>
<name>STD</name>
<longname>Standard Poker</longname>
<settype>core</settype>
<releasedate>2025-11-14</releasedate>
</set>
<set>
<name>NBR</name>
<longname>Numbers</longname>
<settype>core</settype>
<releasedate>2025-11-14</releasedate>
</set>
</sets>
<cards>
<card>
<name>Ace of Hearts</name>
<text>Ace of Hearts</text>
<prop>
<layout>normal</layout>
<side>front</side>
<type>Ace</type>
<maintype>Ace</maintype>
<manacost>14</manacost>
<cmc>14</cmc>
<colors>H</colors>
<coloridentity>H</coloridentity>
<format-standard>legal</format-standard>
</prop>
<reverse-related>Joker</reverse-related>
<token>0</token>
<tablerow>1</tablerow>
<cipt>0</cipt>
<upsidedown>0</upsidedown>
<set rarity="common" uuid="00000000-0000-0000-0000-000000000033" num="51" muid="AH">PKR</set>
<set rarity="common" uuid="00000000-0000-0000-0001-000000000033" num="51" muid="AHSTD">STD</set>
<set rarity="common" uuid="00000000-0000-0000-0002-000000000033" num="51" muid="AHNBR">NBR</set>
</card>
</cards>
</cockatrice_carddatabase>
```
# Using the Printing Selector
To use the PrintingSelector, first select a card in the DeckEditorDeckDockWidget:
\image html deck_dock_deck_list.png
You may add a variation to the mainboard by clicking the + and - buttons in the top row. The bottom row will add the
variation to your sideboard.
\image html printing_selector.png
You can also right-click a variation to pin it, which will move it to the top of the variation list for easy access and
additionally, use it as the default printing whenever the printing isn't explicitly specified (such as adding a card
from the database in the deck editor).
Only one printing may be pinned at a time.
Additionally, the PrintingSelector offers a navigation bar at the bottom to navigate through cards in your deck, as well
as an option to modify the variations of cards in bulk via the 'Bulk Selection' option.
\image html printing_selector_navigation.png
The search bar at the top may be used to filter the displayed variations and the cogwheel may be clicked to open up
additional settings.
\image html printing_selector_options.png

93
doc/doxygen/extra-pages/user_documentation/deck_management/editing_decks_visual.md Normal file
View File

@@ -0,0 +1,93 @@
@page editing_decks_visual Visual Deck Editor
\image html vde_overlap_layout_type_grouped.png width=1200px
# 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.
\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 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 be displayed in a "Flat" layout, which displays each picture next to each other and ensures full
visibility for each card.
\image html vde_flat_layout_type_grouped.png width=1200px
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.
\image html vde_overlap_layout_type_grouped.png width=1200px
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.
Example - Cards grouped by suit/color:
\image html vde_flat_layout_color_grouped.png width=1200px
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
\image html vde_deck_analytics.png width=1200px
# 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.
\image html vde_sample_hand.png width=1200px

151
doc/doxygen/extra-pages/user_documentation/deck_management/exporting_decks.md Normal file
View File

@@ -0,0 +1,151 @@
@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.
```
// Full Deck
// An example comment.
// 63 Maindeck
// 4 Ace
1 Ace of Clubs (PKR) 49
1 Ace of Diamonds (PKR) 50
1 Ace of Hearts (PKR) 51
1 Ace of Spades (PKR) 52
// 13 Face
1 Jack of Clubs (PKR) 53
1 Jack of Diamonds (PKR) 54
1 Jack of Hearts (PKR) 55
1 Jack of Spades (PKR) 56
1 King of Clubs (PKR) 57
1 King of Diamonds (PKR) 58
1 King of Spades (PKR) 60
1 Queen of Clubs (PKR) 61
1 Queen of Diamonds (PKR) 62
1 Queen of Hearts (PKR) 63
1 Queen of Spades (PKR) 64
2 King of Hearts (PKR) 59
// 44 Number
1 0 of Clubs (PKR) 1
1 0 of Diamonds (PKR) 2
1 0 of Hearts (PKR) 3
1 1 of Clubs (PKR) 11
1 1 of Diamonds (PKR) 12
1 1 of Hearts (PKR) 13
1 1 of Spades (PKR) 14
1 10 of Clubs (PKR) 5
1 10 of Diamonds (PKR) 6
1 10 of Hearts (PKR) 7
1 2 of Clubs (PKR) 17
1 2 of Diamonds (PKR) 18
1 2 of Hearts (PKR) 19
1 2 of Spades (PKR) 20
1 3 of Clubs (PKR) 21
1 3 of Diamonds (PKR) 22
1 3 of Hearts (PKR) 23
1 3 of Spades (PKR) 24
1 4 of Clubs (PKR) 25
1 4 of Diamonds (PKR) 26
1 4 of Hearts (PKR) 27
1 4 of Spades (PKR) 28
1 5 of Clubs (PKR) 29
1 5 of Diamonds (PKR) 30
1 5 of Hearts (PKR) 31
1 5 of Spades (PKR) 32
1 6 of Clubs (PKR) 33
1 6 of Diamonds (PKR) 34
1 6 of Hearts (PKR) 35
1 6 of Spades (PKR) 36
1 7 of Clubs (PKR) 37
1 7 of Diamonds (PKR) 38
1 7 of Hearts (PKR) 39
1 7 of Spades (PKR) 40
1 8 of Clubs (PKR) 41
1 8 of Diamonds (PKR) 42
1 8 of Hearts (PKR) 43
1 8 of Spades (PKR) 44
1 9 of Clubs (PKR) 45
1 9 of Diamonds (PKR) 46
1 9 of Hearts (PKR) 47
1 9 of Spades (PKR) 48
1 10 of Spades (PKR) 8
1 0 of Spades (PKR) 4
// 2 Joker
1 1 Joker (PKR) 10
1 2 Joker (PKR) 16
```
## 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.

62
doc/doxygen/extra-pages/user_documentation/deck_management/importing_decks.md Normal file
View File

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

13
doc/doxygen/extra-pages/user_documentation/index.md Normal file
View File

@@ -0,0 +1,13 @@
@page user_reference User Reference
@subpage search_syntax_help
@subpage deck_search_syntax_help
@subpage creating_decks
@subpage importing_decks
@subpage editing_decks
@subpage exporting_decks