#include <stdio.h>
#include <string.h>
#include "astring.h"
#include "bitvector.h"
#include "fciconv.h"
#include "fcintl.h"
#include "log.h"
#include "mem.h"
#include "registry.h"
#include "string_vector.h"
#include "support.h"
#include "counters.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 "tilespec.h"
#include "unit.h"
#include "version.h"
#include "client_main.h"
#include "climisc.h"
#include "gui_main_g.h"
#include "music.h"
#include "helpdata.h"
#include "speclist.h"

Macros
#define	BULLET Q_("?bullet:*")

#define	BULLET_SPACE Q_("?bullet:* ")

#define	CATLSTR(_b, _s, _t, ...) cat_snprintf(_b, _s, _t, ## __VA_ARGS__)

#define	SPECLIST_TAG help

#define	SPECLIST_TYPE struct help_item

#define	help_list_iterate(helplist, phelp) TYPED_LIST_ITERATE(struct help_item, helplist, phelp)

#define	help_list_iterate_end LIST_ITERATE_END

#define	PRINT_BREAK()

Functions
void	helpdata_init (void)

void	helpdata_done (void)

static void	check_help_nodes_init (void)

void	free_help_texts (void)

static bool	show_help_for_nation (const struct nation_type *pnation)

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

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

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

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

static struct help_item *	new_help_item (int type)

static int	help_item_compar (const struct help_item const ppa, const struct help_item const ppb)

void	boot_help_texts (void)

int	num_help_items (void)

const struct help_item *	get_help_item (int pos)

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

void	help_iter_start (void)

const struct help_item *	help_iter_next (void)

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

static bool	utype_may_do_escape_action (const struct unit_type *utype)

void	helptext_unitclass (struct unit_class pclass, char buf, size_t bufsz)

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

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

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

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

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

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

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

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

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

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

char *	helptext_unit_upkeep_str (const struct unit_type *utype)

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

enum help_page_type	help_type_by_requirement (const struct requirement *req)

Variables
static const char *const	help_type_names []

static const struct help_list_link *	help_nodes_iterator

static struct help_list *	help_nodes

static bool	help_nodes_init = FALSE

Macro Definition Documentation

◆ BULLET

#define BULLET Q_("?bullet:*")

Definition at line 63 of file helpdata.c.

◆ BULLET_SPACE

#define BULLET_SPACE Q_("?bullet:* ")

Definition at line 65 of file helpdata.c.

◆ CATLSTR

#define CATLSTR	(	_b,
		_s,
		_t,
		...
	)	cat_snprintf(_b, _s, _t, ## __VA_ARGS__)

Definition at line 68 of file helpdata.c.

◆ help_list_iterate

#define help_list_iterate	(	helplist,
		phelp
	)	TYPED_LIST_ITERATE(struct help_item, helplist, phelp)

Definition at line 81 of file helpdata.c.

◆ help_list_iterate_end

#define help_list_iterate_end LIST_ITERATE_END

Definition at line 83 of file helpdata.c.

◆ PRINT_BREAK

#define PRINT_BREAK ( )

Value:

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

◆ SPECLIST_TAG

#define SPECLIST_TAG help

Definition at line 77 of file helpdata.c.

◆ SPECLIST_TYPE

#define SPECLIST_TYPE struct help_item

Definition at line 78 of file helpdata.c.

Function Documentation

◆ boot_help_texts()

void boot_help_texts ( void )

pplayer may be NULL.

Definition at line 710 of file helpdata.c.

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

◆ check_help_nodes_init()

static void check_help_nodes_init ( void )

static

Make sure help_nodes is initialised. Should call this just about everywhere which uses help_nodes, to be careful... or at least where called by external (non-static) functions.

Definition at line 114 of file helpdata.c.

Referenced by boot_help_texts(), free_help_texts(), get_help_item(), get_help_item_spec(), help_iter_next(), help_iter_start(), and num_help_items().

◆ 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 3685 of file helpdata.c.

Referenced by helptext_extra_for_terrain_str().

◆ free_help_texts()

void free_help_texts ( void )

Free all allocations associated with help_nodes.

Definition at line 125 of file helpdata.c.

Referenced by boot_help_texts(), and client_game_free().

◆ get_help_item()

const struct help_item * get_help_item ( int pos )

Return pointer to given help_item. Returns NULL for 1 past end. Returns NULL and prints error message for other out-of bounds.

Definition at line 1265 of file helpdata.c.

◆ get_help_item_spec()

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

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 1288 of file helpdata.c.

Referenced by popup_help_dialog_typed(), and select_help_item_string().

◆ help_item_compar()

static int help_item_compar	(	const struct help_item const	ppa,
		const struct help_item const	ppb
	)

static

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

Definition at line 688 of file helpdata.c.

Referenced by boot_help_texts().

◆ help_iter_next()

const struct help_item * help_iter_next ( void )

Returns next help item; after help_iter_start(), this is the first item. At end, returns NULL.

Definition at line 1350 of file helpdata.c.

◆ help_iter_start()

void help_iter_start ( void )

Start iterating through help items; that is, reset iterator to start position. (Could iterate using get_help_item(), but that would be less efficient due to scanning to find pos.)

Definition at line 1340 of file helpdata.c.

Referenced by check_help_nodes_init().

◆ help_type_by_requirement()

enum help_page_type help_type_by_requirement ( const struct requirement * req )

Return help page that matches the requirement, or HELP_LAST if none does.

Definition at line 5205 of file helpdata.c.

Referenced by help_hyperlink_callback().

◆ helpdata_done()

void helpdata_done ( void )

Clean up.

Definition at line 103 of file helpdata.c.

Referenced by client_exit().

◆ helpdata_init()

void helpdata_init ( void )

Initialize.

Definition at line 95 of file helpdata.c.

Referenced by client_main().

◆ helptext_advance()

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

Append misc dynamic text for advance/technology.

pplayer may be NULL.

Definition at line 3299 of file helpdata.c.

Referenced by create_tech_info(), help_update_tech(), manual_techs(), 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
	)

Write dynamic text for buildings (including wonders). This includes the ruleset helptext as well as any automatically generated text.

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

Definition at line 1381 of file helpdata.c.

Referenced by get_tooltip(), get_tooltip_improvement(), help_update_improvement(), help_update_wonder(), manual_improvements(), research_diagram::mouseMoveEvent(), popup_impr_info(), 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 NULL.

Definition at line 3794 of file helpdata.c.

Referenced by help_update_extra(), manual_extras(), and 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 3760 of file helpdata.c.

Referenced by help_widget::add_extras_of_act_for_terrain(), and help_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 NULL.

Definition at line 4259 of file helpdata.c.

Referenced by help_update_goods(), and 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 NULL.

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

Definition at line 4340 of file helpdata.c.

Referenced by help_update_government(), manual_governments(), 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 5039 of file helpdata.c.

Referenced by help_update_nation(), nation_button_callback(), races_dialog::nation_selected(), select_nation(), 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 == NULL. 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 NULL if there is no effect at all).

Definition at line 3630 of file helpdata.c.

Referenced by help_update_extra(), and 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 NULL.

Definition at line 4305 of file helpdata.c.

Referenced by help_update_specialist(), and 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 3520 of file helpdata.c.

Referenced by help_update_terrain(), and 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,
		bool	class_help
	)

Append misc dynamic text for units. Transport capacity, unit flags, fuel.

pplayer may be NULL.

Definition at line 1932 of file helpdata.c.

Referenced by get_tooltip(), get_tooltip_unit(), help_update_unit_type(), manual_units(), research_diagram::mouseMoveEvent(), popup_unit_info(), 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 5002 of file helpdata.c.

Referenced by get_tooltip_unit(), help_update_unit_type(), manual_units(), and help_widget::set_topic_unit().

◆ helptext_unitclass()

void helptext_unitclass	(	struct unit_class *	pclass,
		char *	buf,
		size_t	bufsz
	)

Unit class part of the unit helptext

Parameters

pclass	Class to add help text about
buf	Buffer to append help text to
bufsz	Size of the buffer

Definition at line 1866 of file helpdata.c.

Referenced by helptext_unit(), and manual_uclasses().

◆ 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 571 of file helpdata.c.

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,
		struct 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 485 of file helpdata.c.

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 208 of file helpdata.c.

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-NULL. Otherwise, insert 'intro' then a table.

Definition at line 149 of file helpdata.c.

Referenced by helptext_unit(), and insert_generated_text().

◆ new_help_item()

static struct help_item * new_help_item ( int type )

static

Allocate and initialize new help item

Definition at line 672 of file helpdata.c.

Referenced by boot_help_texts().

◆ num_help_items()

int num_help_items ( void )

Number of help items.

Definition at line 1254 of file helpdata.c.

◆ show_help_for_nation()

static bool show_help_for_nation ( const struct nation_type * pnation )

static

Returns whether we should show help for this nation.

Definition at line 139 of file helpdata.c.

Referenced by boot_help_texts(), helptext_advance(), helptext_building(), and helptext_unit().

◆ 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 1830 of file helpdata.c.

Referenced by helptext_unit().

Variable Documentation

◆ help_nodes

struct help_list* help_nodes

static

Definition at line 86 of file helpdata.c.

Referenced by boot_help_texts(), free_help_texts(), get_help_item(), get_help_item_spec(), help_iter_start(), helpdata_done(), helpdata_init(), and num_help_items().

◆ help_nodes_init

bool help_nodes_init = FALSE

static

Definition at line 87 of file helpdata.c.

Referenced by check_help_nodes_init().

◆ help_nodes_iterator

const struct help_list_link* help_nodes_iterator

static

Definition at line 85 of file helpdata.c.

Referenced by help_iter_next(), and help_iter_start().

◆ 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", "Musicset", "Nations", "Multipliers", "Counters", NULL
}

Definition at line 71 of file helpdata.c.

Referenced by boot_help_texts().

Macros

Functions

Variables

Macro Definition Documentation

◆ BULLET

◆ BULLET_SPACE

◆ CATLSTR

◆ help_list_iterate

◆ help_list_iterate_end

◆ PRINT_BREAK

◆ SPECLIST_TAG

◆ SPECLIST_TYPE

Function Documentation

◆ boot_help_texts()

◆ check_help_nodes_init()

◆ extra_bonus_for_terrain()

◆ free_help_texts()

◆ get_help_item()

◆ get_help_item_spec()

◆ help_item_compar()

◆ help_iter_next()

◆ help_iter_start()

◆ help_type_by_requirement()

◆ helpdata_done()

◆ helpdata_init()

◆ 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()

◆ helptext_unitclass()

◆ insert_allows()

◆ insert_allows_single()

◆ insert_generated_text()

◆ insert_veteran_help()

◆ new_help_item()

◆ num_help_items()

◆ show_help_for_nation()

◆ utype_may_do_escape_action()

Variable Documentation

◆ help_nodes

◆ help_nodes_init

◆ help_nodes_iterator

◆ help_type_names