The Battle for Wesnoth  1.19.0-dev
help.hpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2024
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 class config;
19 class terrain_type;
20 class unit;
21 class unit_type;
22 class game_config_view;
23 
24 #include <memory>
25 #include <string>
26 
27 namespace help {
28 
29 /**
30  * The help implementation caches data parsed from the game_config. This class
31  * is used to control the lifecycle of that cache, so that the cache will be
32  * cleared before the game_config itself changes.
33  *
34  * Note: it's okay to call any of the help::show_* functions without creating
35  * an instance of help_manager - that will simply mean that the cache is
36  * cleared before the show function returns.
37  *
38  * Creating two instances of this will cause an assert.
39  */
40 struct help_manager {
42  help_manager(const help_manager&) = delete;
43  help_manager& operator=(const help_manager&) = delete;
44  ~help_manager();
45 };
46 
47 /**
48  * Helper function for any of the show_help functions to control the cache's
49  * lifecycle; can also be used by any other caller that wants to ensure the
50  * cache is reused over multiple show_help calls.
51  *
52  * Treat the return type as opaque, it can return nullptr on success. Also
53  * don't extend the cache lifecycle beyond the lifecycle of the
54  * game_config_manager or over a reload of the game config.
55  *
56  *@pre game_config_manager has been initialised
57  */
58 std::unique_ptr<help_manager> ensure_cache_lifecycle();
59 
60 /**
61  * Open the help browser. The help browser will have the topic with id
62  * show_topic open if it is not the empty string. The default topic
63  * will be shown if show_topic is the empty string.
64  *
65  *@pre game_config_manager has been initialised, or the instance of help_manager
66  * has been created with an alternative config.
67  */
68 void show_help(const std::string& show_topic="", int xloc=-1, int yloc=-1);
69 
70 /** wrapper to add unit prefix and hiding symbol */
71 void show_unit_help(const std::string& unit_id, bool has_variations=false,
72  bool hidden = false, int xloc=-1, int yloc=-1);
73 
74 /** wrapper to add variation prefix and hiding symbol */
75 void show_variation_help(const std::string &unit_id, const std::string &variation,
76  bool hidden = false, int xloc=-1, int yloc=-1);
77 
78 /** wrapper to add terrain prefix and hiding symbol */
79 void show_terrain_help(const std::string& unit_id, bool hidden = false,
80  int xloc = -1, int yloc = -1);
81 
82 void show_unit_description(const unit_type &t);
83 void show_unit_description(const unit &u);
85 
86 } // End namespace help.
double t
Definition: astarsearch.cpp:65
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:159
A class grating read only view to a vector of config objects, viewed as one config with all children ...
A single unit type that the player may recruit.
Definition: types.hpp:46
This class represents a single unit of a specific type.
Definition: unit.hpp:135
Game configuration data as global variables.
Definition: build_info.cpp:63
Definition: help.cpp:57
std::unique_ptr< help_manager > ensure_cache_lifecycle()
Helper function for any of the show_help functions to control the cache's lifecycle; can also be used...
Definition: help.cpp:119
void show_help(const std::string &show_topic, int xloc, int yloc)
Open the help browser, show topic with id show_topic.
Definition: help.cpp:144
void show_variation_help(const std::string &unit, const std::string &variation, bool hidden, int xloc, int yloc)
Open the help browser, show the variation of the unit matching.
Definition: help.cpp:176
void show_terrain_description(const terrain_type &t)
Definition: help.cpp:81
void show_terrain_help(const std::string &show_topic, bool hidden, int xloc, int yloc)
Open the help browser, show terrain with id terrain_id.
Definition: help.cpp:167
void show_unit_help(const std::string &show_topic, bool has_variations, bool hidden, int xloc, int yloc)
Open the help browser, show unit with id unit_id.
Definition: help.cpp:155
void show_unit_description(const unit &u)
Definition: help.cpp:75
The help implementation caches data parsed from the game_config.
Definition: help.hpp:40
help_manager & operator=(const help_manager &)=delete
help_manager(const help_manager &)=delete
help_manager(const game_config_view *game_config)
Definition: help.cpp:111