The Battle for Wesnoth  1.15.5+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 help_manager::help_manager(const game_config_view *cfg) //, gamemap *_map)
91 {
92  static game_config_view dummy_view;
93  game_cfg = cfg == nullptr ? &dummy_view : cfg;
94 // map = _map;
95 }
96 
98 {
99  game_cfg = nullptr;
100 // map = nullptr;
103  // These last numbers must be reset so that the content is regenerated.
104  // Upon next start.
107 }
108 
109 /**
110  * Open the help browser, show topic with id show_topic.
111  *
112  * If show_topic is the empty string, the default topic will be shown.
113  */
114 void show_help(const std::string& show_topic, int xloc, int yloc)
115 {
116  show_help(default_toplevel, show_topic, xloc, yloc);
117 }
118 
119 /**
120  * Open the help browser, show unit with id unit_id.
121  *
122  * If show_topic is the empty string, the default topic will be shown.
123  */
124 void show_unit_help(const std::string& show_topic, bool has_variations, bool hidden, int xloc, int yloc)
125 {
127  hidden_symbol(hidden) + (has_variations ? ".." : "") + unit_prefix + show_topic, xloc, yloc);
128 }
129 
130 /**
131  * Open the help browser, show terrain with id terrain_id.
132  *
133  * If show_topic is the empty string, the default topic will be shown.
134  */
135 void show_terrain_help(const std::string& show_topic, bool hidden, int xloc, int yloc)
136 {
137  show_help(default_toplevel, hidden_symbol(hidden) + terrain_prefix + show_topic, xloc, yloc);
138 }
139 
140 /**
141  * Open the help browser, show the variation of the unit matching.
142  */
143 void show_variation_help(const std::string& unit, const std::string &variation, bool hidden, int xloc, int yloc)
144 {
145  show_help(default_toplevel, hidden_symbol(hidden) + variation_prefix + unit + "_" + variation, xloc, yloc);
146 }
147 
148 /**
149  * Open a help dialog using a toplevel other than the default.
150  *
151  * This allows for complete customization of the contents, although not in a
152  * very easy way.
153  */
154 void show_help(const section &toplevel_sec,
155  const std::string& show_topic,
156  int xloc, int yloc)
157 {
158  CVideo& video = CVideo::get_singleton();
159 
160  const events::event_context dialog_events_context;
161  const gui::dialog_manager manager;
162 
163  SDL_Rect screen_area = video.screen_area();
164 
165  const int width = std::min<int>(font::relative_size(1200), screen_area.w - font::relative_size(20));
166  const int height = std::min<int>(font::relative_size(850), screen_area.h - font::relative_size(150));
167  const int left_padding = font::relative_size(10);
168  const int right_padding = font::relative_size(10);
169  const int top_padding = font::relative_size(10);
170  const int bot_padding = font::relative_size(10);
171 
172  // If not both locations were supplied, put the dialog in the middle
173  // of the screen.
174  if (yloc <= -1 || xloc <= -1) {
175  xloc = screen_area.w / 2 - width / 2;
176  yloc = screen_area.h / 2 - height / 2;
177  }
178  std::vector<gui::button*> buttons_ptr;
179  gui::button close_button_(video, _("Close"));
180  buttons_ptr.push_back(&close_button_);
181 
182  gui::dialog_frame f(video, _("The Battle for Wesnoth Help"), gui::dialog_frame::default_style,
183  true, &buttons_ptr);
184  f.layout(xloc, yloc, width, height);
185  f.draw();
186 
187  // Find all unit_types that have not been constructed yet and fill in the information
188  // needed to create the help topics
190 
195  // More units or terrains encountered, update the contents.
200  }
201  try {
202  help_browser hb(video, toplevel_sec);
203  hb.set_location(xloc + left_padding, yloc + top_padding);
204  hb.set_width(width - left_padding - right_padding);
205  hb.set_height(height - top_padding - bot_padding);
206  if (!show_topic.empty()) {
207  hb.show_topic(show_topic);
208  }
209  else {
211  }
212  hb.set_dirty(true);
214  CKey key;
215  for (;;) {
216  events::pump();
218  f.draw();
220  if (key[SDLK_ESCAPE]) {
221  // Escape quits from the dialog.
222  return;
223  }
224  for (std::vector<gui::button*>::iterator button_it = buttons_ptr.begin();
225  button_it != buttons_ptr.end(); ++button_it) {
226  if ((*button_it)->pressed()) {
227  // There is only one button, close.
228  return;
229  }
230  }
231  video.flip();
232  CVideo::delay(10);
233  }
234  }
235  catch (const parse_error& e) {
236  ERR_HELP << _("Parse error when parsing help text:") << " " << e.message << std::endl;
237 #if 0
238  // Displaying in the UI is disabled due to issue #2587
239  std::stringstream msg;
240  msg << _("Parse error when parsing help text:") << " '" << e.message << "'";
241  gui2::show_transient_message("", msg.str());
242 #endif
243  }
244 }
245 
246 } // 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:114
const std::string unit_prefix
Definition: help_impl.cpp:90
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:1159
This class represents a single unit of a specific type.
Definition: unit.hpp:129
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:142
Definition: video.hpp:31
boost::tribool last_debug_state
Definition: help_impl.cpp:75
int relative_size(int size)
Definition: constants.hpp:29
void flip()
Renders the screen.
Definition: video.cpp:329
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:204
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:1201
unit_type_data unit_types
Definition: types.cpp:1378
const config & get_cfg() const
Definition: types.hpp:268
static CVideo & get_singleton()
Definition: video.hpp:48
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:74
-file util.hpp
Definitions for the interface to Wesnoth Markup Language (WML).
bool hide_help() const
For instances created from a [terrain_type] tag, the value in the tag (with default false)...
Definition: terrain.hpp:60
A single unit type that the player may recruit.
Definition: types.hpp:44
help::section hidden_sections
Definition: help_impl.cpp:71
const unit_type & type() const
This unit&#39;s type, accounting for gender and variation.
Definition: unit.hpp:353
dimension_measurements layout(int x, int y, int w, int h)
void set_dirty(bool dirty=true)
Definition: widget.cpp:207
static UNUSEDNOWARN std::string _(const char *str)
Definition: gettext.hpp:100
std::string hidden_symbol(bool hidden)
Definition: help_impl.cpp:1461
bool hide_help() const
Definition: types.cpp:593
std::set< t_translation::terrain_code > & encountered_terrains()
Definition: game.cpp:957
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:135
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
u64 size
Definition: statement.cpp:80
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:124
int last_num_encountered_units
Definition: help_impl.cpp:73
bool show_variations_in_help() const
Whether the unit type has at least one help-visible variation.
Definition: types.cpp:731
const game_config_view * game_cfg
Definition: help_impl.cpp:67
std::set< std::string > & encountered_units()
Definition: game.cpp:953
const bool & debug
help_manager(const game_config_view *game_config)
Definition: help.cpp:90
#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:1400
Standard logging facilities (interface).
const std::string & id() const
Definition: terrain.hpp:51
std::string message
Definition: exceptions.hpp:31
static void delay(unsigned int milliseconds)
Waits a given number of milliseconds before returning.
Definition: video.cpp:322
#define e
Definition: help.cpp:55
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:291
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:69
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:143
static lg::log_domain log_help("help")