The Battle for Wesnoth  1.19.0-dev
help_text_area.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 #include <list> // for list
19 #include <string> // for string
20 #include <utility> // for pair
21 #include "font/standard_colors.hpp" // for NORMAL_COLOR
22 #include "sdl/texture.hpp" // for texture
23 #include "widgets/scrollarea.hpp" // for scrollarea
24 
25 class config;
26 namespace help { struct section; }
27 namespace help { struct topic; }
28 
29 namespace help {
30 
31 
32 /** The area where the content is shown in the help browser. */
34 {
35 public:
36  help_text_area(const section &toplevel);
37  /** Display the topic. */
38  void show_topic(const topic &t);
39 
40  /**
41  * Return the ID that is cross-referenced at the (screen)
42  * coordinates x, y. If no cross-reference is there, return the
43  * empty string.
44  */
45  std::string ref_at(const int x, const int y);
46 
47 protected:
48  virtual void scroll(unsigned int pos);
49  virtual void set_inner_location(const SDL_Rect& rect);
50 
51 private:
53  /** Convert a string to an alignment. Throw parse_error if unsuccessful. */
54  ALIGNMENT str_to_align(const std::string &s);
55 
56  /**
57  * An item that is displayed in the text area. Contains the surface
58  * that should be blitted along with some other information.
59  */
60  struct item {
61 
62  item(const texture& tex, int x, int y, const std::string& text="",
63  const std::string& reference_to="", bool floating=false,
64  bool box=false, ALIGNMENT alignment=HERE);
65 
66  item(const texture& tex, int x, int y,
67  bool floating, bool box=false, ALIGNMENT=HERE);
68 
69  /** Relative coordinates of this item. */
71 
73 
74  // If this item contains text, this will contain that text.
75  std::string text;
76 
77  // If this item contains a cross-reference, this is the id
78  // of the referenced topic.
79  std::string ref_to;
80 
81  // If this item is floating, that is, if things should be filled
82  // around it.
83  bool floating;
84  bool box;
86  };
87 
88  /** Function object to find an item at the specified coordinates. */
89  class item_at {
90  public:
91  item_at(const int x, const int y) : x_(x), y_(y) {}
92  bool operator()(const item&) const;
93  private:
94  const int x_, y_;
95  };
96 
97  /**
98  * Update the vector with the items of the shown topic, creating
99  * surfaces for everything and putting things where they belong.
100  */
101  void set_items();
102 
103  // Create appropriate items from configs. Items will be added to the
104  // internal vector. These methods check that the necessary
105  // attributes are specified.
106  void handle_ref_cfg(const config &cfg);
107  void handle_img_cfg(const config &cfg);
108  void handle_bold_cfg(const config &cfg);
109  void handle_italic_cfg(const config &cfg);
110  void handle_header_cfg(const config &cfg);
111  void handle_jump_cfg(const config &cfg);
112  void handle_format_cfg(const config &cfg);
113 
114  void draw_contents();
115 
116  /**
117  * Add an item with text. If ref_dst is something else than the
118  * empty string, the text item will be underlined to show that it
119  * is a cross-reference. The item will also remember what the
120  * reference points to. If font_size is below zero, the default
121  * will be used.
122  */
123  void add_text_item(const std::string& text, const std::string& ref_dst="",
124  bool broken_link = false,
125  int font_size=-1, bool bold=false, bool italic=false,
127 
128  /** Add an image item with the specified attributes. */
129  void add_img_item(const std::string& path, const std::string& alignment, const bool floating,
130  const bool box);
131 
132  /** Move the current input point to the next line. */
133  void down_one_line();
134 
135  /** Adjust the heights of the items in the last row to make it look good. */
136  void adjust_last_row();
137 
138  /** Return the width that remain on the line the current input point is at. */
139  int get_remaining_width();
140 
141  /**
142  * Return the least x coordinate at which something of the
143  * specified height can be drawn at the specified y coordinate
144  * without interfering with floating images.
145  */
146  int get_min_x(const int y, const int height=0);
147 
148  /** Analogous with get_min_x but return the maximum X. */
149  int get_max_x(const int y, const int height=0);
150 
151  /**
152  * Find the lowest y coordinate where a floating img of the
153  * specified width and at the specified x coordinate can be
154  * placed. Start looking at desired_y and continue downwards. Only
155  * check against other floating things, since text and inline
156  * images only can be above this place if called correctly.
157  */
158  int get_y_for_floating_img(const int width, const int x, const int desired_y);
159 
160  /** Add an item to the internal list, update the locations and row height. */
161  void add_item(const item& itm);
162 
163  std::list<item> items_;
164  std::list<item *> last_row_;
167  const int title_spacing_;
168  /** The current input location when creating items. */
169  std::pair<int, int> curr_loc_;
170  const unsigned min_row_height_;
172  /** The height of all items in total. */
174 };
175 
176 } // end namespace help
double t
Definition: astarsearch.cpp:63
A config object defines a single node in a WML file, with access to child nodes.
Definition: config.hpp:159
int width() const
Definition: widget.cpp:113
int height() const
Definition: widget.cpp:118
Function object to find an item at the specified coordinates.
item_at(const int x, const int y)
bool operator()(const item &) const
The area where the content is shown in the help browser.
const section & toplevel_
const unsigned min_row_height_
void handle_italic_cfg(const config &cfg)
void handle_img_cfg(const config &cfg)
void add_img_item(const std::string &path, const std::string &alignment, const bool floating, const bool box)
Add an image item with the specified attributes.
int get_min_x(const int y, const int height=0)
Return the least x coordinate at which something of the specified height can be drawn at the specifie...
std::string ref_at(const int x, const int y)
Return the ID that is cross-referenced at the (screen) coordinates x, y.
help_text_area(const section &toplevel)
std::list< item * > last_row_
std::pair< int, int > curr_loc_
The current input location when creating items.
int get_remaining_width()
Return the width that remain on the line the current input point is at.
virtual void set_inner_location(const SDL_Rect &rect)
void show_topic(const topic &t)
Display the topic.
void handle_format_cfg(const config &cfg)
void adjust_last_row()
Adjust the heights of the items in the last row to make it look good.
virtual void scroll(unsigned int pos)
void set_items()
Update the vector with the items of the shown topic, creating surfaces for everything and putting thi...
void handle_bold_cfg(const config &cfg)
void handle_ref_cfg(const config &cfg)
void down_one_line()
Move the current input point to the next line.
ALIGNMENT str_to_align(const std::string &s)
Convert a string to an alignment.
void handle_jump_cfg(const config &cfg)
int get_max_x(const int y, const int height=0)
Analogous with get_min_x but return the maximum X.
void add_item(const item &itm)
Add an item to the internal list, update the locations and row height.
void add_text_item(const std::string &text, const std::string &ref_dst="", bool broken_link=false, int font_size=-1, bool bold=false, bool italic=false, color_t color=font::NORMAL_COLOR)
Add an item with text.
void handle_header_cfg(const config &cfg)
int contents_height_
The height of all items in total.
topic const * shown_topic_
int get_y_for_floating_img(const int width, const int x, const int desired_y)
Find the lowest y coordinate where a floating img of the specified width and at the specified x coord...
std::list< item > items_
Wrapper class to encapsulate creation and management of an SDL_Texture.
Definition: texture.hpp:33
const color_t NORMAL_COLOR
std::string path
Definition: filesystem.cpp:83
Definition: help.cpp:53
std::string bold(const std::string &s)
Definition: help_impl.hpp:404
The basic class for representing 8-bit RGB or RGBA colour values.
Definition: color.hpp:59
An item that is displayed in the text area.
item(const texture &tex, int x, int y, const std::string &text="", const std::string &reference_to="", bool floating=false, bool box=false, ALIGNMENT alignment=HERE)
rect rect_
Relative coordinates of this item.
A section contains topics and sections along with title and ID.
Definition: help_impl.hpp:144
A topic contains a title, an id and some text.
Definition: help_impl.hpp:111
An abstract description of a rectangle with integer coordinates.
Definition: rect.hpp:47
static map_location::DIRECTION s