Freeciv-3.1: /fast/freeciv/nightly/S3_1/client/helpdata.c File Reference

Freeciv-3.1

Loading...
Searching...
No Matches
Macros | Functions | Variables
helpdata.c File Reference
`#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 "effects.h"`
`#include "game.h"`
`#include "government.h"`
`#include "map.h"`
`#include "movement.h"`
`#include "multipliers.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 "helpdata.h"`
`#include "speclist.h"`

Go to the source code of this file.

## Macros

#define | CATLSTR(_b, _s, _t) fc_strlcat(_b, _t, _s)
#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)
char * | helptext_unit (char *buf, size_t bufsz, struct player *pplayer, const char *user_text, const struct unit_type *utype)
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

## ◆ CATLSTR

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

Definition at line 60 of file helpdata.c.

## ◆ help_list_iterate

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

Definition at line 73 of file helpdata.c.

## ◆ help_list_iterate_end

#define help_list_iterate_end LIST_ITERATE_END

Definition at line 75 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)
bufsz
static const int bufsz
Definition helpdlg.c:70
FALSE
#define FALSE
Definition support.h:47

## ◆ SPECLIST_TAG

#define SPECLIST_TAG help

Definition at line 69 of file helpdata.c.

## ◆ SPECLIST_TYPE

#define SPECLIST_TYPE struct help_item

Definition at line 70 of file helpdata.c.

## Function Documentation

## ◆ boot_help_texts()

void boot_help_texts | ( | void |  | ) |

pplayer may be NULL.

Definition at line 741 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 106 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 3510 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 117 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 1200 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 1223 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 719 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 1285 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 1275 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 5037 of file helpdata.c.

Referenced by help_hyperlink_callback().

## ◆ helpdata_done()

void helpdata_done | ( | void |  | ) |

Clean up.

Definition at line 95 of file helpdata.c.

Referenced by client_exit().

## ◆ helpdata_init()

void helpdata_init | ( | void |  | ) |

Initialize.

Definition at line 87 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 3115 of file helpdata.c.

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

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

Referenced by get_tooltip(), get_tooltip_improvement(), help_update_improvement(), help_update_wonder(), manual_command(), 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 3619 of file helpdata.c.

Referenced by help_update_extra(), 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 3585 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 4094 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 4175 of file helpdata.c.

Referenced by help_update_government(), 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 4871 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 3455 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 4140 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 3338 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
| ) |  |

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

pplayer may be NULL.

Definition at line 1763 of file helpdata.c.

Referenced by get_tooltip(), get_tooltip_unit(), help_update_unit_type(), manual_command(), 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 4834 of file helpdata.c.

Referenced by get_tooltip_unit(), help_update_unit_type(), 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 603 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 517 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 200 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 141 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 704 of file helpdata.c.

Referenced by boot_help_texts().

## ◆ num_help_items()

int num_help_items | ( | void |  | ) |

Number of help items.

Definition at line 1189 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 131 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 1728 of file helpdata.c.

Referenced by helptext_unit().

## Variable Documentation

## ◆ help_nodes

struct help_list* help_nodes

static

Definition at line 78 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 79 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 77 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", "Nations", "Multipliers", NULL
}

Definition at line 63 of file helpdata.c.

Referenced by boot_help_texts().