The Battle for Wesnoth  1.15.0-dev
help.cpp
Go to the documentation of this file.
1 /*
2  Copyright (C) 2003 - 2018 by David White <dave@whitevine.net>
3  Part of the Battle for Wesnoth Project https://www.wesnoth.org/
4 
5  This program is free software; you can redistribute it and/or modify
6  it under the terms of the GNU General Public License as published by
7  the Free Software Foundation; either version 2 of the License, or
8  (at your option) any later version.
9  This program is distributed in the hope that it will be useful,
10  but WITHOUT ANY WARRANTY.
11 
12  See the COPYING file for more details.
13 */
14 
15 /**
16  * @file
17  * Routines for showing the help-dialog.
18  */
19 
20 #define GETTEXT_DOMAIN "wesnoth-help"
21 
22 #include "help/help.hpp"
23 
24 #include "config.hpp" // for config, etc
25 #include "events.hpp" // for raise_draw_event, pump, etc
26 #include "font/constants.hpp" // for relative_size
27 #include "preferences/game.hpp"
28 #include "gettext.hpp" // for _
30 #include "help/help_browser.hpp" // for help_browser
31 #include "help/help_impl.hpp" // for hidden_symbol, toplevel, etc
32 #include "key.hpp" // for CKey
33 #include "log.hpp" // for LOG_STREAM, log_domain
34 #include "sdl/surface.hpp" // for surface
35 #include "show_dialog.hpp" // for dialog_frame, etc
36 #include "terrain/terrain.hpp" // for terrain_type
37 #include "units/unit.hpp" // for unit
38 #include "units/types.hpp" // for unit_type, unit_type_data, etc
39 #include "video.hpp" // for CVideo, resize_lock
40 #include "widgets/button.hpp" // for button
41 
42 #include <cassert> // for assert
43 #include <algorithm> // for min
44 #include <ostream> // for basic_ostream, operator<<, etc
45 #include <vector> // for vector, vector<>::iterator
46 #include <SDL.h>
47 
48 
49 static lg::log_domain log_display("display");
50 #define WRN_DP LOG_STREAM(warn, log_display)
51 
52 static lg::log_domain log_help("help");
53 #define WRN_HP LOG_STREAM(warn, log_help)
54 #define DBG_HP LOG_STREAM(debug, log_help)
55 
56 namespace help {
57 
59 {
61 }
62 
64 {
66 }
67 
69 {
70  std::string var_id = t.get_cfg()["variation_id"].str();
71  if (var_id.empty())
72  var_id = t.get_cfg()["variation_name"].str();
73  bool hide_help = t.hide_help();
74  bool use_variation = false;
75  if (!var_id.empty()) {
76  const unit_type *parent = unit_types.find(t.id());
77  assert(parent);
78  if (hide_help) {
79  hide_help = parent->hide_help();
80  } else {
81  use_variation = true;
82  }
83  }
84 
85  if (use_variation)
86  help::show_variation_help(t.id(), var_id, hide_help);
87  else
88  help::show_unit_help(t.id(), t.show_variations_in_help(), hide_help);
89 }
90 
91 extern config dummy_cfg;
92 
93 help_manager::help_manager(const config *cfg) //, gamemap *_map)
94 {
95  game_cfg = cfg == nullptr ? &dummy_cfg : cfg;
96 // map = _map;
97 }
98 
100 {
101  game_cfg = nullptr;
102 // map = nullptr;
105  // These last numbers must be reset so that the content is regenerated.
106  // Upon next start.
109 }
110 
111 /**
112  * Open the help browser, show topic with id show_topic.
113  *
114  * If show_topic is the empty string, the default topic will be shown.
115  */
116 void show_help(const std::string& show_topic, int xloc, int yloc)
117 {
118  show_help(default_toplevel, show_topic, xloc, yloc);
119 }
120 
121 /**
122  * Open the help browser, show unit with id unit_id.
123  *
124  * If show_topic is the empty string, the default topic will be shown.
125  */
126 void show_unit_help(const std::string& show_topic, bool has_variations, bool hidden, int xloc, int yloc)
127 {
129  hidden_symbol(hidden) + (has_variations ? ".." : "") + unit_prefix + show_topic, xloc, yloc);
130 }
131 
132 /**
133  * Open the help browser, show terrain with id terrain_id.
134  *
135  * If show_topic is the empty string, the default topic will be shown.
136  */
137 void show_terrain_help(const std::string& show_topic, bool hidden, int xloc, int yloc)
138 {
139  show_help(default_toplevel, hidden_symbol(hidden) + terrain_prefix + show_topic, xloc, yloc);
140 }
141 
142 /**
143  * Open the help browser, show the variation of the unit matching.
144  */
145 void show_variation_help(const std::string& unit, const std::string &variation, bool hidden, int xloc, int yloc)
146 {
147  show_help(default_toplevel, hidden_symbol(hidden) + variation_prefix + unit + "_" + variation, xloc, yloc);
148 }
149 
150 /**
151  * Open a help dialog using a toplevel other than the default.
152  *
153  * This allows for complete customization of the contents, although not in a
154  * very easy way.
155  */
156 void show_help(const section &toplevel_sec,
157  const std::string& show_topic,
158  int xloc, int yloc)
159 {
160  CVideo& video = CVideo::get_singleton();
161 
162  const events::event_context dialog_events_context;
163  const gui::dialog_manager manager;
164 
165  SDL_Rect screen_area = video.screen_area();
166 
167  const int width = std::min<int>(font::relative_size(1200), screen_area.w - font::relative_size(20));
168  const int height = std::min<int>(font::relative_size(850), screen_area.h - font::relative_size(150));
169  const int left_padding = font::relative_size(10);
170  const int right_padding = font::relative_size(10);
171  const int top_padding = font::relative_size(10);
172  const int bot_padding = font::relative_size(10);
173 
174  // If not both locations were supplied, put the dialog in the middle
175  // of the screen.
176  if (yloc <= -1 || xloc <= -1) {
177  xloc = screen_area.w / 2 - width / 2;
178  yloc = screen_area.h / 2 - height / 2;
179  }
180  std::vector<gui::button*> buttons_ptr;
181  gui::button close_button_(video, _("Close"));
182  buttons_ptr.push_back(&close_button_);
183 
184  gui::dialog_frame f(video, _("The Battle for Wesnoth Help"), gui::dialog_frame::default_style,
185  true, &buttons_ptr);
186  f.layout(xloc, yloc, width, height);
187  f.draw();
188 
189  // Find all unit_types that have not been constructed yet and fill in the information
190  // needed to create the help topics
192 
197  // More units or terrains encountered, update the contents.
202  }
203  try {
204  help_browser hb(video, toplevel_sec);
205  hb.set_location(xloc + left_padding, yloc + top_padding);
206  hb.set_width(width - left_padding - right_padding);
207  hb.set_height(height - top_padding - bot_padding);
208  if (!show_topic.empty()) {
209  hb.show_topic(show_topic);
210  }
211  else {
213  }
214  hb.set_dirty(true);
216  CKey key;
217  for (;;) {
218  events::pump();
220  f.draw();
222  if (key[SDLK_ESCAPE]) {
223  // Escape quits from the dialog.
224  return;
225  }
226  for (std::vector<gui::button*>::iterator button_it = buttons_ptr.begin();
227  button_it != buttons_ptr.end(); ++button_it) {
228  if ((*button_it)->pressed()) {
229  // There is only one button, close.
230  return;
231  }
232  }
233  video.flip();
234  CVideo::delay(10);
235  }
236  }
237  catch (parse_error& /*e*/) {
238  // Disabled due to issue #2587
239 #if 0
240  std::stringstream msg;
241  msg << _("Parse error when parsing help text: ") << "'" << e.message << "'";
242  gui2::show_transient_message("", msg.str());
243 #endif
244  }
245 }
246 
247 } // End namespace help.
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:116
const std::string unit_prefix
Definition: help_impl.cpp:89
config dummy_cfg
Definition: help_impl.cpp:75
const unit_type * find(const std::string &key, unit_type::BUILD_STATUS status=unit_type::FULL) const
Finds a unit_type by its id() and makes sure it is built to the specified level.
Definition: types.cpp:1275
This class represents a single unit of a specific type.
Definition: unit.hpp:99
void show_terrain_description(const terrain_type &t)
Definition: help.cpp:63
static const style default_style
Definition: show_dialog.hpp:66
A section contains topics and sections along with title and ID.
Definition: help_impl.hpp:143
Definition: video.hpp:31
boost::tribool last_debug_state
Definition: help_impl.cpp:73
int relative_size(int size)
Definition: constants.hpp:29
void flip()
Renders the screen.
Definition: video.cpp:337
void show_transient_message(const std::string &title, const std::string &message, const std::string &image, const bool message_use_markup, const bool title_use_markup, const bool restore_background)
Shows a transient message to the user.
Thrown when the help system fails to parse something.
Definition: help_impl.hpp:221
void set_width(int w)
Definition: widget.cpp:117
void build_all(unit_type::BUILD_STATUS status)
Makes sure the all unit_types are built to the specified level.
Definition: types.cpp:1321
unit_type_data unit_types
Definition: types.cpp:1452
const config & get_cfg() const
Definition: types.hpp:269
static CVideo & get_singleton()
Definition: video.hpp:43
static void msg(const char *act, debug_info &i, const char *to="", const char *result="")
Definition: debugger.cpp:109
const std::string terrain_prefix
Definition: help_impl.cpp:90
int last_num_encountered_terrains
Definition: help_impl.cpp:72
const config * game_cfg
Definition: help_impl.cpp:65
-file util.hpp
Definitions for the interface to Wesnoth Markup Language (WML).
A single unit type that the player may recruit.
Definition: types.hpp:42
help::section hidden_sections
Definition: help_impl.cpp:69
const unit_type & type() const
This unit&#39;s type, accounting for gender and variation.
Definition: unit.hpp:315
dimension_measurements layout(int x, int y, int w, int h)
help_manager(const config *game_config)
Definition: help.cpp:93
void set_dirty(bool dirty=true)
Definition: widget.cpp:215
static UNUSEDNOWARN std::string _(const char *str)
Definition: gettext.hpp:89
std::size_t size(const std::string &str)
Length in characters of a UTF-8 string.
Definition: unicode.cpp:86
bool is_combined() const
Definition: terrain.hpp:80
std::string hidden_symbol(bool hidden)
Definition: help_impl.cpp:1438
bool hide_help() const
Definition: types.cpp:587
std::set< t_translation::terrain_code > & encountered_terrains()
Definition: game.cpp:944
const std::string & id() const
The id for this unit_type.
Definition: types.hpp:139
static lg::log_domain log_display("display")
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:137
virtual void set_location(const SDL_Rect &rect)
Definition: widget.cpp:83
void raise_draw_event()
Definition: events.cpp:726
void show_unit_description(const unit &u)
Definition: help.cpp:58
void pump()
Definition: events.cpp:425
void raise_process_event()
Definition: events.cpp:703
const std::string variation_prefix
Definition: help_impl.cpp:94
void show_topic(const std::string &topic_id)
Display the topic with the specified identifier.
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:126
int last_num_encountered_units
Definition: help_impl.cpp:71
bool show_variations_in_help() const
Whether the unit type has at least one help-visible variation.
Definition: types.cpp:786
std::set< std::string > & encountered_units()
Definition: game.cpp:940
const bool & debug
bool hide_in_editor() const
Definition: terrain.hpp:40
#define f
const std::string default_show_topic
Definition: help_impl.cpp:87
double t
Definition: astarsearch.cpp:64
void generate_contents()
Generate the help contents from the configurations given to the manager.
Definition: help_impl.cpp:1374
Standard logging facilities (interface).
const std::string & id() const
Definition: terrain.hpp:37
static void delay(unsigned int milliseconds)
Waits a given number of milliseconds before returning.
Definition: video.cpp:330
#define e
Definition: help.cpp:56
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:92
Class that keeps track of all the keys on the keyboard.
Definition: key.hpp:27
SDL_Rect screen_area(bool as_pixels=true) const
Returns the current window renderer area, either in pixels or screen coordinates. ...
Definition: video.cpp:299
void set_height(int h)
Definition: widget.cpp:122
std::string::const_iterator iterator
Definition: tokenizer.hpp:24
A help browser widget.
help::section default_toplevel
Definition: help_impl.cpp:67
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:145
static lg::log_domain log_help("help")