Freeciv-3.3
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 "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"

Go to the source code of this file.

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_itemnew_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_itemget_help_item (int pos)
 
const struct help_itemget_help_item_spec (const char *name, enum help_page_type htype, int *pos)
 
void help_iter_start (void)
 
const struct help_itemhelp_iter_next (void)
 
charhelptext_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)
 
charhelptext_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 charhelptext_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 charhelptext_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)
 
charhelptext_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_linkhelp_nodes_iterator
 
static struct help_listhelp_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 (buf[0] != '\0') { \
CATLSTR(buf, bufsz, "\n\n"); \
} \
} \
} while (FALSE)
char * incite_cost
Definition comments.c:76
static const int bufsz
Definition helpdlg.c:70
#define FALSE
Definition support.h:47

◆ 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 3680 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 5200 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 3294 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 3789 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 3755 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 4254 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 4335 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 5034 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 3625 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 4300 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 3515 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 4997 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
pclassClass to add help text about
bufBuffer to append help text to
bufszSize 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

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