common/featured_text.h

   1 /***********************************************************************
   2  Freeciv - Copyright (C) 1996 - A Kjeldberg, L Gregersen, P Unold
   3    This program is free software; you can redistribute it and/or modify
   4    it under the terms of the GNU General Public License as published by
   5    the Free Software Foundation; either version 2, or (at your option)
   6    any later version.
   7
   8    This program is distributed in the hope that it will be useful,
   9    but WITHOUT ANY WARRANTY; without even the implied warranty of
  10    MERCHANTABILITY or FITNESS FOR A PARTICULAR PURPOSE.  See the
  11    GNU General Public License for more details.
  12 ***********************************************************************/
  13 #ifndef FC__FEATURED_TEXT_H
  14 #define FC__FEATURED_TEXT_H
  15
  16 #ifdef __cplusplus
  17 extern "C" {
  18 #endif /* __cplusplus */
  19
  20 /* utility */
  21 #include "support.h"            /* bool type. */
  22
  23 /* common */
  24 #include "fc_types.h"
  25
  26 /*
  27  * Some words about the featured text module.
  28  *
  29  * Bored to have black only chat, players used to hack their clients, to
  30  * obtain colored chat based patterns.  Also for strategic communication,
  31  * they added some clickable links on particular city or location.
  32  * The present code is not based on old warclient code, but it also contains
  33  * the same tools.  Whereas colors where determinated in client side only,
  34  * here the server also has the possibility to choose what color to display
  35  * to the clients.  Such embellishments are performed using escape sequences
  36  * (which are described bellow) in the strings.
  37  *
  38  * Plain text vs featured text.
  39  *
  40  * What is called plain text in those files is actually a string without any
  41  * escape sequence.  It is the text which should basically displayed in the
  42  * client, without taking account of the features.  On the other side, what
  43  * is called featured text is also a string, but which could include one of
  44  * many escape sequences.
  45  *
  46  * Text tag.
  47  *
  48  * The text_tag type is a structure which tag a particular modification for
  49  * a string.  It contains many informations, which the type of modification,
  50  * the start of the modification in bytes from the start of the string, and
  51  * the stop of it.  It also can contains many others fields, according to
  52  * sequence type.
  53  * Note that all offset datas are calculated in bytes and not in character
  54  * number, so the client must translate those offsets before using them.
  55  *
  56  * Escape sequences.
  57  *
  58  * - Bold.
  59  * Full name sequence: [bold] ... [/bold]
  60  * Abbreviation sequence: [b] ... [/b]
  61  * Text tag type: TTT_BOLD
  62  *
  63  * - Italic.
  64  * Full name sequence: [italic] ... [/italic]
  65  * Abbreviation sequence: [i] ... [/i]
  66  * Text tag type: TTT_ITALIC
  67  *
  68  * - Strike.
  69  * Full name sequence: [strike] ... [/strike]
  70  * Abbreviation sequence: [s] ... [/s]
  71  * Text tag type: TTT_STRIKE
  72  *
  73  * - Underline.
  74  * Full name sequence: [underline] ... [/underline]
  75  * Abbreviation sequence: [u] ... [/u]
  76  * Text tag type: TTT_UNDERLINE
  77  *
  78  * - Color.
  79  * Full name sequence: [color] ... [/color]
  80  * Abbreviation sequence: [c] ... [/c]
  81  * Text tag type: TTT_COLOR
  82  * Option: foreground (abbreviation fg): a color name or a hex specification
  83  * such as #3050b2 or #35b.
  84  * Option: background (abbreviation bg): same type of data.
  85  *
  86  * - Link.
  87  * Full name sequence: [link] ... [/link] or [link/]
  88  * Abbreviation sequence: [l] ... [/l] or [l/]
  89  * Text tag type: TTT_LINK
  90  * Option: target (abbreviation tgt): absolutely needed.  It is set to
  91  * "city" (then link type is TLT_CITY), "tile" (TLT_TILE) or "unit"
  92  * (TLT_UNIT).
  93  * Option: id: if target type is TLT_CITY or TLT_UNIT, it is the id of
  94  * the target.
  95  * Option: name: if target type is TLT_CITY or TLT_UNIT, it is an additional
  96  * string to display if the target is not known by the receiver.
  97  * Options: x and y: if target type is TLT_TILE, they are the coordinates
  98  * of the target.
  99  */
 100
 101 /* Offset type (in bytes). */
 102 typedef int ft_offset_t;
 103 /* Unset offset value. */
 104 #define FT_OFFSET_UNSET ((ft_offset_t) -1)
 105
 106 /* Opaque type. */
 107 struct text_tag;
 108
 109 /* Define struct text_tag_list. */
 110 #define SPECLIST_TAG text_tag
 111 #define SPECLIST_TYPE struct text_tag
 112 #include "speclist.h"
 113
 114 #define text_tag_list_iterate(tags, ptag) \
 115   TYPED_LIST_ITERATE(struct text_tag, tags, ptag)
 116 #define text_tag_list_iterate_end  LIST_ITERATE_END
 117
 118 /* The different text_tag types.
 119  * Chaning the order doesn't break the network compatiblity. */
 120 enum text_tag_type {
 121   TTT_BOLD = 0,
 122   TTT_ITALIC,
 123   TTT_STRIKE,
 124   TTT_UNDERLINE,
 125   TTT_COLOR,
 126   TTT_LINK
 127 };
 128
 129 /* The different text_tag link types.
 130  * Chaning the order doesn't break the network compatiblity. */
 131 enum text_link_type {
 132   TLT_CITY,
 133   TLT_TILE,
 134   TLT_UNIT
 135 };
 136
 137 /* Default maximal link size */
 138 #define MAX_LEN_LINK    128
 139
 140 /* Simplification for colors. */
 141 struct ft_color {
 142   const char *foreground;
 143   const char *background;
 144 };
 145 #define FT_COLOR(fg, bg) { fg, bg }
 146 /**************************************************************************
 147   Constructor.
 148 **************************************************************************/
 149 static inline struct ft_color ft_color_construct(const char *foreground,
 150                                                  const char *background)
 151 {
 152   struct ft_color color = FT_COLOR(foreground, background);
 153
 154   return color;
 155 }
 156
 157 /**************************************************************************
 158   Returns whether a color is requested.
 159 **************************************************************************/
 160 static inline bool ft_color_requested(const struct ft_color color)
 161 {
 162   return ((NULL != color.foreground && '\0' != color.foreground[0])
 163           || (NULL != color.background && '\0' != color.background[0]));
 164 }
 165
 166 /* Predefined colors. */
 167 extern const struct ft_color ftc_any;
 168
 169 extern const struct ft_color ftc_warning;
 170 extern const struct ft_color ftc_log;
 171 extern const struct ft_color ftc_server;
 172 extern const struct ft_color ftc_client;
 173 extern const struct ft_color ftc_editor;
 174 extern const struct ft_color ftc_command;
 175 extern       struct ft_color ftc_changed;
 176 extern const struct ft_color ftc_server_prompt;
 177 extern const struct ft_color ftc_player_lost;
 178 extern const struct ft_color ftc_game_start;
 179
 180 extern const struct ft_color ftc_chat_public;
 181 extern const struct ft_color ftc_chat_ally;
 182 extern const struct ft_color ftc_chat_private;
 183 extern const struct ft_color ftc_chat_luaconsole;
 184
 185 extern const struct ft_color ftc_vote_public;
 186 extern const struct ft_color ftc_vote_team;
 187 extern const struct ft_color ftc_vote_passed;
 188 extern const struct ft_color ftc_vote_failed;
 189 extern const struct ft_color ftc_vote_yes;
 190 extern const struct ft_color ftc_vote_no;
 191 extern const struct ft_color ftc_vote_abstain;
 192
 193 extern const struct ft_color ftc_luaconsole_input;
 194 extern const struct ft_color ftc_luaconsole_error;
 195 extern const struct ft_color ftc_luaconsole_normal;
 196 extern const struct ft_color ftc_luaconsole_verbose;
 197 extern const struct ft_color ftc_luaconsole_debug;
 198
 199 /* Main functions. */
 200 size_t featured_text_to_plain_text(const char *featured_text,
 201                                    char *plain_text, size_t plain_text_len,
 202                                    struct text_tag_list **tags,
 203                                    bool replace_link_text);
 204 size_t featured_text_apply_tag(const char *text_source,
 205                                char *featured_text, size_t featured_text_len,
 206                                enum text_tag_type tag_type,
 207                                ft_offset_t start_offset,
 208                                ft_offset_t stop_offset,
 209                                ...);
 210
 211 /* Text tag list functions. NB: Overwrite the ones defined in speclist.h. */
 212 #define text_tag_list_new() \
 213   text_tag_list_new_full(text_tag_destroy)
 214 #define text_tag_list_copy(tags) \
 215   text_tag_list_copy_full(tags, text_tag_copy, text_tag_destroy)
 216
 217
 218 /* Text tag functions. */
 219 struct text_tag *text_tag_new(enum text_tag_type tag_type,
 220                               ft_offset_t start_offset,
 221                               ft_offset_t stop_offset,
 222                               ...);
 223 struct text_tag *text_tag_copy(const struct text_tag *ptag);
 224 void text_tag_destroy(struct text_tag *ptag);
 225
 226 enum text_tag_type text_tag_type(const struct text_tag *ptag);
 227 ft_offset_t text_tag_start_offset(const struct text_tag *ptag);
 228 ft_offset_t text_tag_stop_offset(const struct text_tag *ptag);
 229
 230 /* Specific TTT_COLOR text tag type functions. */
 231 const char *text_tag_color_foreground(const struct text_tag *ptag);
 232 const char *text_tag_color_background(const struct text_tag *ptag);
 233
 234 /* Specific TTT_LINK text tag type functions. */
 235 enum text_link_type text_tag_link_type(const struct text_tag *ptag);
 236 int text_tag_link_id(const struct text_tag *ptag);
 237
 238 /* Tools. */
 239 const char *city_link(const struct city *pcity);
 240 const char *city_tile_link(const struct city *pcity);
 241 const char *tile_link(const struct tile *ptile);
 242 const char *unit_link(const struct unit *punit);
 243 const char *unit_tile_link(const struct unit *punit);
 244
 245 #ifdef __cplusplus
 246 }
 247 #endif /* __cplusplus */
 248
 249 #endif /* FC__FEATURED_TEXT_H */