The Battle for Wesnoth  1.15.2+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 <SDL2/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 ERR_HELP LOG_STREAM(err, log_help)
54 
55 namespace help {
56 
58 {
60 }
61 
63 {
65 }
66 
68 {
69  std::string var_id = t.get_cfg()["variation_id"].str();
70  if (var_id.empty())
71  var_id = t.get_cfg()["variation_name"].str();
72  bool hide_help = t.hide_help();
73  bool use_variation = false;
74  if (!var_id.empty()) {
75  const unit_type *parent = unit_types.find(t.id());
76  assert(parent);
77  if (hide_help) {
78  hide_help = parent->hide_help();
79  } else {
80  use_variation = true;
81  }
82  }
83 
84  if (use_variation)
85  help::show_variation_help(t.id(), var_id, hide_help);
86  else
87  help::show_unit_help(t.id(), t.show_variations_in_help(), hide_help);
88 }
89 
90 extern config dummy_cfg;
91 
92 help_manager::help_manager(const config *cfg) //, gamemap *_map)
93 {
94  game_cfg = cfg == nullptr ? &dummy_cfg : cfg;
95 // map = _map;
96 }
97 
99 {
100  game_cfg = nullptr;
101 // map = nullptr;
104  // These last numbers must be reset so that the content is regenerated.
105  // Upon next start.
108 }
109 
110 /**
111  * Open the help browser, show topic with id show_topic.
112  *
113  * If show_topic is the empty string, the default topic will be shown.
114  */
115 void show_help(const std::string& show_topic, int xloc, int yloc)
116 {
117  show_help(default_toplevel, show_topic, xloc, yloc);
118 }
119 
120 /**
121  * Open the help browser, show unit with id unit_id.
122  *
123  * If show_topic is the empty string, the default topic will be shown.
124  */
125 void show_unit_help(const std::string& show_topic, bool has_variations, bool hidden, int xloc, int yloc)
126 {
128  hidden_symbol(hidden) + (has_variations ? ".." : "") + unit_prefix + show_topic, xloc, yloc);
129 }
130 
131 /**
132  * Open the help browser, show terrain with id terrain_id.
133  *
134  * If show_topic is the empty string, the default topic will be shown.
135  */
136 void show_terrain_help(const std::string& show_topic, bool hidden, int xloc, int yloc)
137 {
138  show_help(default_toplevel, hidden_symbol(hidden) + terrain_prefix + show_topic, xloc, yloc);
139 }
140 
141 /**
142  * Open the help browser, show the variation of the unit matching.
143  */
144 void show_variation_help(const std::string& unit, const std::string &variation, bool hidden, int xloc, int yloc)
145 {
146  show_help(default_toplevel, hidden_symbol(hidden) + variation_prefix + unit + "_" + variation, xloc, yloc);
147 }
148 
149 /**
150  * Open a help dialog using a toplevel other than the default.
151  *
152  * This allows for complete customization of the contents, although not in a
153  * very easy way.
154  */
155 void show_help(const section &toplevel_sec,
156  const std::string& show_topic,
157  int xloc, int yloc)
158 {
159  CVideo& video = CVideo::get_singleton();
160 
161  const events::event_context dialog_events_context;
162  const gui::dialog_manager manager;
163 
164  SDL_Rect screen_area = video.screen_area();
165 
166  const int width = std::min<int>(font::relative_size(1200), screen_area.w - font::relative_size(20));
167  const int height = std::min<int>(font::relative_size(850), screen_area.h - font::relative_size(150));
168  const int left_padding = font::relative_size(10);
169  const int right_padding = font::relative_size(10);
170  const int top_padding = font::relative_size(10);
171  const int bot_padding = font::relative_size(10);
172 
173  // If not both locations were supplied, put the dialog in the middle
174  // of the screen.
175  if (yloc <= -1 || xloc <= -1) {
176  xloc = screen_area.w / 2 - width / 2;
177  yloc = screen_area.h / 2 - height / 2;
178  }
179  std::vector<gui::button*> buttons_ptr;
180  gui::button close_button_(video, _("Close"));
181  buttons_ptr.push_back(&close_button_);
182 
183  gui::dialog_frame f(video, _("The Battle for Wesnoth Help"), gui::dialog_frame::default_style,
184  true, &buttons_ptr);
185  f.layout(xloc, yloc, width, height);
186  f.draw();
187 
188  // Find all unit_types that have not been constructed yet and fill in the information
189  // needed to create the help topics
191 
196  // More units or terrains encountered, update the contents.
201  }
202  try {
203  help_browser hb(video, toplevel_sec);
204  hb.set_location(xloc + left_padding, yloc + top_padding);
205  hb.set_width(width - left_padding - right_padding);
206  hb.set_height(height - top_padding - bot_padding);
207  if (!show_topic.empty()) {
208  hb.show_topic(show_topic);
209  }
210  else {
212  }
213  hb.set_dirty(true);
215  CKey key;
216  for (;;) {
217  events::pump();
219  f.draw();
221  if (key[SDLK_ESCAPE]) {
222  // Escape quits from the dialog.
223  return;
224  }
225  for (std::vector<gui::button*>::iterator button_it = buttons_ptr.begin();
226  button_it != buttons_ptr.end(); ++button_it) {
227  if ((*button_it)->pressed()) {
228  // There is only one button, close.
229  return;
230  }
231  }
232  video.flip();
233  CVideo::delay(10);
234  }
235  }
236  catch (const parse_error& e) {
237  ERR_HELP << _("Parse error when parsing help text:") << " " << e.message << std::endl;
238 #if 0
239  // Displaying in the UI is disabled due to issue #2587
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:115
const std::string unit_prefix
Definition: help_impl.cpp:90
config dummy_cfg
Definition: help_impl.cpp:76
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:1271
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:62
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:141
Definition: video.hpp:31
boost::tribool last_debug_state
Definition: help_impl.cpp:74
int relative_size(int size)
Definition: constants.hpp:29
void flip()
Renders the screen.
Definition: video.cpp:324
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:205
void set_width(int w)
Definition: widget.cpp:109
void build_all(unit_type::BUILD_STATUS status)
Makes sure the all unit_types are built to the specified level.
Definition: types.cpp:1317
unit_type_data unit_types
Definition: types.cpp:1529
const config & get_cfg() const
Definition: types.hpp:272
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:91
int last_num_encountered_terrains
Definition: help_impl.cpp:73
const config * game_cfg
Definition: help_impl.cpp:66
-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:70
const unit_type & type() const
This unit&#39;s type, accounting for gender and variation.
Definition: unit.hpp:316
dimension_measurements layout(int x, int y, int w, int h)
help_manager(const config *game_config)
Definition: help.cpp:92
void set_dirty(bool dirty=true)
Definition: widget.cpp:207
static UNUSEDNOWARN std::string _(const char *str)
Definition: gettext.hpp:91
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:135
std::string hidden_symbol(bool hidden)
Definition: help_impl.cpp:1412
bool hide_help() const
Definition: types.cpp:590
std::set< t_translation::terrain_code > & encountered_terrains()
Definition: game.cpp:958
const std::string & id() const
The id for this unit_type.
Definition: types.hpp:138
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:136
virtual void set_location(const SDL_Rect &rect)
Definition: widget.cpp:75
void raise_draw_event()
Definition: events.cpp:776
void show_unit_description(const unit &u)
Definition: help.cpp:57
void pump()
Definition: events.cpp:475
#define ERR_HELP
Definition: help.cpp:53
void raise_process_event()
Definition: events.cpp:753
const std::string variation_prefix
Definition: help_impl.cpp:95
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:125
int last_num_encountered_units
Definition: help_impl.cpp:72
bool show_variations_in_help() const
Whether the unit type has at least one help-visible variation.
Definition: types.cpp:789
std::set< std::string > & encountered_units()
Definition: game.cpp:954
const bool & debug
bool hide_in_editor() const
Definition: terrain.hpp:40
#define f
const std::string default_show_topic
Definition: help_impl.cpp:88
double t
Definition: astarsearch.cpp:64
void generate_contents()
Generate the help contents from the configurations given to the manager.
Definition: help_impl.cpp:1348
Standard logging facilities (interface).
const std::string & id() const
Definition: terrain.hpp:37
std::string message
Definition: exceptions.hpp:31
static void delay(unsigned int milliseconds)
Waits a given number of milliseconds before returning.
Definition: video.cpp:317
#define e
Definition: help.cpp:55
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:68
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:286
void set_height(int h)
Definition: widget.cpp:114
std::string::const_iterator iterator
Definition: tokenizer.hpp:24
A help browser widget.
help::section default_toplevel
Definition: help_impl.cpp:68
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:144
static lg::log_domain log_help("help")