The Battle for Wesnoth  1.19.14+dev
helper.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2025
3  by David White <dave@whitevine.net>
4  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
5 
6  This program is free software; you can redistribute it and/or modify
7  it under the terms of the GNU General Public License as published by
8  the Free Software Foundation; either version 2 of the License, or
9  (at your option) any later version.
10  This program is distributed in the hope that it will be useful,
11  but WITHOUT ANY WARRANTY.
12 
13  See the COPYING file for more details.
14 */
15 
16 #pragma once
17 
18 #include "team.hpp"
19 #include "units/map.hpp"
20 #include "units/types.hpp"
21 
22 namespace unit_helper {
23 
24 /**
25  * Encapsulates the logic for deciding whether an iterator @a u points to
26  * a unit that can advance.
27  * @return true if the unit exists, has available advances, and can_advance().
28  */
30 
31 /**
32  * Determines the total number of available advancements (of any kind) for
33  * a given unit. This includes normal advances and modifiers.
34  * @return the total number of possible advancements.
35  */
37 
38 /**
39  * @return the name of the color encoding the weight of the unit's
40  * resistance value for presenting it to the player.
41  */
42 std::string resistance_color(const int resistance);
43 
44 /**
45  * @return the tooltip text showing a unit's level and what it can advance to.
46  */
47 std::string unit_level_tooltip(const unit &u);
48 
49 /**
50  * @return the tooltip text showing a unit type's level and what it can
51  * advance to.
52  */
53 std::string unit_level_tooltip(const unit_type &u);
54 
55 /**
56  * @return If active, do nothing. If inactive, surround with pango tag that
57  * changes font color to grey.
58  */
59 std::string maybe_inactive(const std::string& str, bool active);
60 
61 /**
62  * @return If unit recall cost is greater than team's recall cost,
63  * return a help markup string that shows the unit recall cost
64  * in red font color. If unit recall cost is less than team's cost,
65  * color in green instead. If equal, default color.
66  * In all cases, a gold icon using `<img>` tag is prepended to the formatted cost.
67  * Icon is greyscaled when unit recall cost > team recall cost.
68  * Eg. `<img src='themes/gold.png~GS()'/><span color='#ff0000'>40</span>`.
69  */
70 std::string format_cost_string(int unit_recall_cost, const int team_recall_cost);
71 
72 /**
73  * @return Help markup string with gold icon followed by unit_cost.
74  * Eg. `<img src='themes/gold.png'/>40`
75  * If active, do nothing. If inactive, surround with pango tag that
76  * changes font color to grey and grayscales the gold icon.
77  */
78 std::string format_cost_string(int unit_cost, bool active = true);
79 
80 /**
81  * @return A pango formatted string representation of level.
82  * The applied formatting is different for each level.
83  * L0: level number in normal text, grey color
84  * L1: level number in normal text
85  * L2: level number in bold text
86  * L3: level number in bold, font color `#e2b776`
87  * L3+: level number in bold, font color `#dd6600`.
88  * If not recallable, return greyscaled versions.
89  * So, L0, L1: normal text, L2+: bold text
90  */
91 std::string format_level_string(const int level, bool recallable);
92 
93 /**
94  * @return A pango formatted string representation of "moves_left/moves_max",
95  * colored based on condition below:
96  * moves_left is zero: "moves_left/moves_max" colored in red
97  * moves_left is less than/equal to moves_max: "moves_left/moves_max" colored in green
98  * moves_left is greater than moves_max: "moves_left/moves_max" colored in yellow
99  * active = false: "moves_left/moves_max" colored in grey,
100  * regardless of the previous conditions.
101  */
102 std::string format_movement_string(const int moves_left, const int moves_max, const bool active = true);
103 
104 /** @returns the amount of gold tied up in the given side's planned actions. */
106 
107 /** @returns an error message if the given unit cost is unaffordable. */
108 std::string check_recruit_purse(int unit_cost, int current_purse, int investments);
109 
110 /** @returns an error message if the given unit is not on the given side's recruit list. */
111 std::string check_recruit_list(
112  const std::string& type, int side_number, const map_location& target_hex);
113 
114 /**
115  * Verifies that @a target_hex is a valid recruit location for the given side.
116  *
117  * @returns a tuple consisting of
118  * - any applicable error message
119  * - the valid recruit target hex
120  * - the valid recruit source hex
121  */
122 std::tuple<std::string, map_location, map_location> validate_recruit_target(
123  const std::string& type, int side_number, const map_location& target_hex);
124 
125 } // namespace unit_helper
A single unit type that the player may recruit.
Definition: types.hpp:43
This class represents a single unit of a specific type.
Definition: unit.hpp:132
int side_number
Definition: game_info.hpp:40
static std::string unit_level_tooltip(const int level, const std::vector< std::string > &adv_to_types, const std::vector< config > &adv_to_mods)
Definition: helper.cpp:60
bool will_certainly_advance(const unit_map::iterator &u)
Encapsulates the logic for deciding whether an iterator u points to a unit that can advance.
Definition: helper.cpp:39
std::string resistance_color(const int resistance)
Maps resistance <= -60 (resistance value <= -60%) to intense red.
Definition: helper.cpp:54
std::string format_level_string(const int level, bool recallable)
Definition: helper.cpp:135
std::string check_recruit_list(const std::string &type, int side_number, const map_location &target_hex)
Definition: helper.cpp:186
std::string format_movement_string(const int moves_left, const int moves_max, bool active)
Definition: helper.cpp:154
std::string check_recruit_purse(int unit_cost, int current_purse, int investments)
Definition: helper.cpp:174
int planned_gold_spent(int side_number)
Definition: helper.cpp:167
std::string maybe_inactive(const std::string &str, bool active)
Definition: helper.cpp:96
int number_of_possible_advances(const unit &u)
Determines the total number of available advancements (of any kind) for a given unit.
Definition: helper.cpp:34
std::string format_cost_string(int unit_recall_cost, bool active)
Definition: helper.cpp:101
std::tuple< std::string, map_location, map_location > validate_recruit_target(const std::string &type, int side_number, const map_location &target_hex)
Verifies that target_hex is a valid recruit location for the given side.
Definition: helper.cpp:198
int moves_left
Definition: pathfind.cpp:156
Encapsulates the map of the game.
Definition: location.hpp:45