#include <fc_config.h>
#include <QBitArray>
#include <QList>
#include <cstring>
#include "astring.h"
#include "bitvector.h"
#include "fciconv.h"
#include "fcintl.h"
#include "log.h"
#include "registry.h"
#include "registry_ini.h"
#include "requirements.h"
#include "support.h"
#include "effects.h"
#include "game.h"
#include "government.h"
#include "map.h"
#include "movement.h"
#include "multipliers.h"
#include "nation.h"
#include "reqtext.h"
#include "research.h"
#include "server_settings.h"
#include "specialist.h"
#include "unit.h"
#include "version.h"
#include "helpdata.h"

Include dependency graph for helpdata.cpp:

Macros
#define	CATLSTR(_b, _s, _t) fc_strlcat(_b, _t, _s)
	This module is for generic handling of help data, independent of gui considerations. More...

#define	PRINT_BREAK()

Typedefs
typedef QList< const struct help_item * >	helpList

Functions
void	free_help_texts ()
	Free all allocations associated with help_nodes. More...

static bool	insert_veteran_help (char outbuf, size_t outlen, const struct veteran_system veteran, const char intro, const char nolevels)
	Insert fixed-width table describing veteran system. More...

static void	format_change_terrain_string (char buf, int bufsize, enum gen_action act, int time, terrain from, const terrain *to)
	Formats the number of turns to transform between terrains so it can be included in the terrain alterations table. More...

static bool	insert_generated_text (char outbuf, size_t outlen, const char name)
	Insert generated text for the helpdata "name". More...

static void	insert_allows_single (struct universal psource, const requirement_vector psubjreqs, const char subjstr, const char const strs, char buf, size_t bufsz, const char *prefix)
	Append text to 'buf' if the given requirements list 'subjreqs' contains 'psource', implying that ability to build the subject 'subjstr' is affected by 'psource'. More...

static void	insert_allows (struct universal psource, char buf, size_t bufsz, const char *prefix)
	Generate text for what this requirement source allows. More...

struct help_item *	new_help_item (help_page_type type)
	Allocate and initialize new help item. More...

static int	help_item_compar (const struct help_item v1, const struct help_item v2)
	For help_list_sort(); sort by topic via compare_strings() (sort topics with more leading spaces after those with fewer) More...

void	boot_help_texts (const nation_set nations_to_show, help_item tileset_help)
	pplayer may be nullptr. More...

const struct help_item *	get_help_item_spec (const char name, enum help_page_type htype, int pos)
	The following few functions are essentially wrappers for the help_nodes help_list. More...

char *	helptext_building (char buf, size_t bufsz, struct player pplayer, const char user_text, const struct impr_type pimprove, const nation_set *nations_to_show)
	FIXME: Also, in principle these could be auto-generated once, inserted into pitem->text, and then don't need to keep re-generating them. More...

static bool	utype_may_do_escape_action (const struct unit_type *utype)
	Returns TRUE iff the specified unit type is able to perform an action that allows it to escape to the closest closest domestic city once done. More...

char *	helptext_unit (char buf, size_t bufsz, struct player pplayer, const char user_text, const struct unit_type utype, const nation_set *nations_to_show)
	Append misc dynamic text for units. More...

void	helptext_advance (char buf, size_t bufsz, struct player pplayer, const char user_text, int i, const nation_set nations_to_show)
	Append misc dynamic text for advance/technology. More...

void	helptext_terrain (char buf, size_t bufsz, struct player pplayer, const char user_text, struct terrain pterrain)
	Append text for terrain. More...

const char *	helptext_road_bonus_str (const struct terrain pterrain, const struct road_type proad)
	Return a textual representation of the F/P/T bonus a road provides to a terrain if supplied, or the terrain-independent bonus if pterrain == nullptr. More...

static void	extra_bonus_for_terrain (struct extra_type pextra, struct terrain pterrain, int *bonus)
	Calculate any fixed food/prod/trade bonus that 'pextra' will always add to terrain type, independent of any other modifications. More...

const char *	helptext_extra_for_terrain_str (struct extra_type pextra, struct terrain pterrain, enum unit_activity act)
	Return a brief description specific to the extra and terrain, when extra is built by cause 'act'. More...

void	helptext_extra (char buf, size_t bufsz, struct player pplayer, const char user_text, struct extra_type pextra)
	Append misc dynamic text for extras. More...

void	helptext_goods (char buf, size_t bufsz, struct player pplayer, const char user_text, struct goods_type pgood)
	Append misc dynamic text for goods. More...

void	helptext_specialist (char buf, size_t bufsz, struct player pplayer, const char user_text, struct specialist pspec)
	Append misc dynamic text for specialists. More...

void	helptext_government (char buf, size_t bufsz, struct player pplayer, const char user_text, struct government gov)
	Append text for government. More...

char *	helptext_unit_upkeep_str (const struct unit_type *utype)
	Returns pointer to static string with eg: "1 shield, 1 unhappy". More...

void	helptext_nation (char buf, size_t bufsz, struct nation_type pnation, const char *user_text)
	Returns nation legend and characteristics. More...

Variables
static const char *const	help_type_names []

helpList *	help_nodes

Macro Definition Documentation

◆ CATLSTR

#define CATLSTR	(	_b,
		_s,
		_t
	)	fc_strlcat(_b, _t, _s)

This module is for generic handling of help data, independent of gui considerations.

Definition at line 55 of file helpdata.cpp.

◆ PRINT_BREAK

#define PRINT_BREAK ( )

Value:

  do {                                                                      \
    if (print_break) {                                                      \
      if (buf[0] != '\0') {                                                 \
        CATLSTR(buf, bufsz, "\n\n");                                        \
      }                                                                     \
      print_break = false;                                                  \
    }                                                                       \
  } while (false)

Typedef Documentation

◆ helpList

typedef QList<const struct help_item *> helpList

Definition at line 64 of file helpdata.cpp.

Function Documentation

◆ boot_help_texts()

void boot_help_texts	(	const nation_set *	nations_to_show,
		help_item *	tileset_help
	)

pplayer may be nullptr.

Definition at line 682 of file helpdata.cpp.

Referenced by client_main(), client_state(), handle_game_info(), and tilespec_reread().

◆ extra_bonus_for_terrain()

static void extra_bonus_for_terrain	(	struct extra_type *	pextra,
		struct terrain *	pterrain,
		int *	bonus
	)

static

Calculate any fixed food/prod/trade bonus that 'pextra' will always add to terrain type, independent of any other modifications.

Does not consider percentage bonuses. Result written into 'bonus' which should hold 3 ints (F/P/T).

Definition at line 3283 of file helpdata.cpp.

Referenced by helptext_extra_for_terrain_str().

◆ format_change_terrain_string()

static void format_change_terrain_string	(	char *	buf,
		int	bufsize,
		enum gen_action	act,
		int	time,
		terrain *	from,
		const terrain *	to
	)

static

Formats the number of turns to transform between terrains so it can be included in the terrain alterations table.

Definition at line 149 of file helpdata.cpp.

Referenced by insert_generated_text().

◆ free_help_texts()

void free_help_texts ( )

Free all allocations associated with help_nodes.

Definition at line 73 of file helpdata.cpp.

Referenced by boot_help_texts(), and client_game_free().

◆ get_help_item_spec()

const struct help_item* get_help_item_spec	(	const char *	name,
		enum help_page_type	htype,
		int *	pos
	)

The following few functions are essentially wrappers for the help_nodes help_list.

This allows us to avoid exporting the help_list, and instead only access it through a controlled interface. Find help item by name and type. Returns help item, and sets (*pos) to position in list. If no item, returns pointer to static internal item with some faked data, and sets (*pos) to -1.

Definition at line 1118 of file helpdata.cpp.

Referenced by popup_help_dialog_typed().

◆ help_item_compar()

static int help_item_compar	(	const struct help_item *	v1,
		const struct help_item *	v2
	)

static

For help_list_sort(); sort by topic via compare_strings() (sort topics with more leading spaces after those with fewer)

Definition at line 669 of file helpdata.cpp.

Referenced by boot_help_texts().

◆ helptext_advance()

void helptext_advance	(	char *	buf,
		size_t	bufsz,
		struct player *	pplayer,
		const char *	user_text,
		int	i,
		const nation_set *	nations_to_show
	)

Append misc dynamic text for advance/technology.

pplayer may be nullptr.

Definition at line 2886 of file helpdata.cpp.

Referenced by manual_command(), research_diagram::mouseMoveEvent(), and help_widget::set_topic_tech().

◆ helptext_building()

char* helptext_building	(	char *	buf,
		size_t	bufsz,
		struct player *	pplayer,
		const char *	user_text,
		const struct impr_type *	pimprove,
		const nation_set *	nations_to_show
	)

FIXME: Also, in principle these could be auto-generated once, inserted into pitem->text, and then don't need to keep re-generating them.

Only thing to be careful of would be changeable data, but don't have that here (for ruleset change or spacerace change must re-boot helptexts anyway). Eg, genuinely dynamic information which could be useful would be if help system said which wonders have been built (or are being built and by who/where?) Write dynamic text for buildings (including wonders). This includes the ruleset helptext as well as any automatically generated text.

pplayer may be nullptr. user_text, if non-nullptr, will be appended to the text.

Definition at line 1181 of file helpdata.cpp.

Referenced by get_tooltip(), get_tooltip_improvement(), manual_command(), research_diagram::mouseMoveEvent(), and help_widget::set_topic_building().

◆ helptext_extra()

void helptext_extra	(	char *	buf,
		size_t	bufsz,
		struct player *	pplayer,
		const char *	user_text,
		struct extra_type *	pextra
	)

Append misc dynamic text for extras.

Assumes build time and conflicts are handled in the GUI front-end.

pplayer may be nullptr.

Definition at line 3395 of file helpdata.cpp.

Referenced by help_widget::set_topic_extra().

◆ helptext_extra_for_terrain_str()

const char* helptext_extra_for_terrain_str	(	struct extra_type *	pextra,
		struct terrain *	pterrain,
		enum unit_activity	act
	)

Return a brief description specific to the extra and terrain, when extra is built by cause 'act'.

Returns number of turns to build, and selected bonuses. Returns a pointer to a static string, so caller should not free.

Definition at line 3361 of file helpdata.cpp.

Referenced by help_widget::add_extras_of_act_for_terrain().

◆ helptext_goods()

void helptext_goods	(	char *	buf,
		size_t	bufsz,
		struct player *	pplayer,
		const char *	user_text,
		struct goods_type *	pgood
	)

Append misc dynamic text for goods.

Assumes effects are described in the help text.

pplayer may be nullptr.

Definition at line 3853 of file helpdata.cpp.

Referenced by help_widget::set_topic_goods().

◆ helptext_government()

void helptext_government	(	char *	buf,
		size_t	bufsz,
		struct player *	pplayer,
		const char *	user_text,
		struct government *	gov
	)

Append text for government.

pplayer may be nullptr.

TODO: Generalize the effects code for use elsewhere. Add other requirements.

Definition at line 3942 of file helpdata.cpp.

Referenced by manual_command(), research_diagram::mouseMoveEvent(), and help_widget::set_topic_government().

◆ helptext_nation()

void helptext_nation	(	char *	buf,
		size_t	bufsz,
		struct nation_type *	pnation,
		const char *	user_text
	)

Returns nation legend and characteristics.

Definition at line 4653 of file helpdata.cpp.

Referenced by races_dialog::nation_selected(), and help_widget::set_topic_nation().

◆ helptext_road_bonus_str()

const char* helptext_road_bonus_str	(	const struct terrain *	pterrain,
		const struct road_type *	proad
	)

Return a textual representation of the F/P/T bonus a road provides to a terrain if supplied, or the terrain-independent bonus if pterrain == nullptr.

e.g. "0/0/+1", "0/+50%/0", or for a complex road "+2/+1+50%/0". Returns a pointer to a static string, so caller should not free (or nullptr if there is no effect at all).

Definition at line 3229 of file helpdata.cpp.

Referenced by helptext_extra().

◆ helptext_specialist()

void helptext_specialist	(	char *	buf,
		size_t	bufsz,
		struct player *	pplayer,
		const char *	user_text,
		struct specialist *	pspec
	)

Append misc dynamic text for specialists.

Assumes effects are described in the help text.

pplayer may be nullptr.

Definition at line 3905 of file helpdata.cpp.

Referenced by help_widget::set_topic_specialist().

◆ helptext_terrain()

void helptext_terrain	(	char *	buf,
		size_t	bufsz,
		struct player *	pplayer,
		const char *	user_text,
		struct terrain *	pterrain
	)

Append text for terrain.

Definition at line 3115 of file helpdata.cpp.

Referenced by help_widget::set_topic_terrain().

◆ helptext_unit()

char* helptext_unit	(	char *	buf,
		size_t	bufsz,
		struct player *	pplayer,
		const char *	user_text,
		const struct unit_type *	utype,
		const nation_set *	nations_to_show
	)

Append misc dynamic text for units.

Transport capacity, unit flags, fuel.

pplayer may be nullptr.

Definition at line 1639 of file helpdata.cpp.

Referenced by get_tooltip(), get_tooltip_unit(), manual_command(), research_diagram::mouseMoveEvent(), and help_widget::set_topic_unit().

◆ helptext_unit_upkeep_str()

char* helptext_unit_upkeep_str ( const struct unit_type * utype )

Returns pointer to static string with eg: "1 shield, 1 unhappy".

Definition at line 4611 of file helpdata.cpp.

Referenced by get_tooltip_unit(), manual_command(), and help_widget::set_topic_unit().

◆ insert_allows()

static void insert_allows	(	struct universal *	psource,
		char *	buf,
		size_t	bufsz,
		const char *	prefix
	)

static

Generate text for what this requirement source allows.

Something like

"Allows Communism (with University).\n" "Allows Mfg. Plant (with Factory).\n" "Allows Library (absent Fundamentalism).\n" "Prevents Harbor.\n"

This should be called to generate helptext for every possible source type. Note this doesn't handle effects but rather requirements to create/maintain things (currently only building/government reqs).

NB: This function overwrites any existing buffer contents by writing the generated text to the start of the given 'buf' pointer (i.e. it does NOT append like cat_snprintf).

Definition at line 592 of file helpdata.cpp.

Referenced by helptext_advance(), helptext_building(), helptext_extra(), helptext_government(), helptext_nation(), and helptext_terrain().

◆ insert_allows_single()

static void insert_allows_single	(	struct universal *	psource,
		const requirement_vector *	psubjreqs,
		const char *	subjstr,
		const char const	strs,
		char *	buf,
		size_t	bufsz,
		const char *	prefix
	)

static

Append text to 'buf' if the given requirements list 'subjreqs' contains 'psource', implying that ability to build the subject 'subjstr' is affected by 'psource'.

'strs' is an array of (possibly i18n-qualified) format strings covering the various cases where additional requirements apply.

Definition at line 508 of file helpdata.cpp.

Referenced by insert_allows().

◆ insert_generated_text()

static bool insert_generated_text	(	char *	outbuf,
		size_t	outlen,
		const char *	name
	)

static

Insert generated text for the helpdata "name".

Returns TRUE if anything was added.

Definition at line 167 of file helpdata.cpp.

Referenced by boot_help_texts().

◆ insert_veteran_help()

static bool insert_veteran_help	(	char *	outbuf,
		size_t	outlen,
		const struct veteran_system *	veteran,
		const char *	intro,
		const char *	nolevels
	)

static

Insert fixed-width table describing veteran system.

If only one veteran level, inserts 'nolevels' if non-nullptr. Otherwise, insert 'intro' then a table.

Definition at line 92 of file helpdata.cpp.

Referenced by helptext_unit(), and insert_generated_text().

◆ new_help_item()

struct help_item* new_help_item ( help_page_type type )

Allocate and initialize new help item.

Definition at line 656 of file helpdata.cpp.

Referenced by boot_help_texts(), and tileset_help().

◆ utype_may_do_escape_action()

static bool utype_may_do_escape_action ( const struct unit_type * utype )

static

Returns TRUE iff the specified unit type is able to perform an action that allows it to escape to the closest closest domestic city once done.

See diplomat_escape() for more.

Definition at line 1602 of file helpdata.cpp.

Referenced by helptext_unit().

Variable Documentation

◆ help_nodes

helpList* help_nodes

Definition at line 65 of file helpdata.cpp.

Referenced by boot_help_texts(), free_help_texts(), get_help_item_spec(), and help_dialog::make_tree().

◆ help_type_names

const char* const help_type_names[]

static

Initial value:

= {
    "(Any)",       "(Text)",  "Units",   "Improvements", "Wonders",
    "Techs",       "Terrain", "Extras",  "Goods",        "Specialists",
    "Governments", "Ruleset", "Tileset", "Nations",      "Multipliers",
    "Effects",     nullptr}

Definition at line 58 of file helpdata.cpp.

Referenced by boot_help_texts().

Macros

Typedefs

Functions

Variables

Macro Definition Documentation

◆ CATLSTR

◆ PRINT_BREAK

Typedef Documentation

◆ helpList

Function Documentation

◆ boot_help_texts()

◆ extra_bonus_for_terrain()

◆ format_change_terrain_string()

◆ free_help_texts()

◆ get_help_item_spec()

◆ help_item_compar()

◆ helptext_advance()

◆ helptext_building()

◆ helptext_extra()

◆ helptext_extra_for_terrain_str()

◆ helptext_goods()

◆ helptext_government()

◆ helptext_nation()

◆ helptext_road_bonus_str()

◆ helptext_specialist()

◆ helptext_terrain()

◆ helptext_unit()

◆ helptext_unit_upkeep_str()

◆ insert_allows()

◆ insert_allows_single()

◆ insert_generated_text()

◆ insert_veteran_help()

◆ new_help_item()

◆ utype_may_do_escape_action()

Variable Documentation

◆ help_nodes

◆ help_type_names