mirror
/
OpenTTD
mirror of https://github.com/OpenTTD/OpenTTD
1
0
Fork 0
Code Issues

(svn r11125) -Documentation: add/update the documentation of news*. Based on a patch by Progman.

release/0.6
rubidium 2007-09-17 17:07:24 +00:00
parent c2dc4a4adb
commit 87f62c7109
2 changed files with 149 additions and 79 deletions
Show Stats Download Patch File Download Diff File Expand all files Collapse all files

67
src/news.h
View File

@ -6,16 +6,16 @@
#define NEWS_H #define NEWS_H
struct NewsItem { struct NewsItem {
StringID string_id; StringID string_id; ///< Message text (sometimes also used for storing other info)
uint16 duration; uint16 duration; ///< Remaining time for showing this news message
Date date; Date date; ///< Date of the news
byte flags; byte flags; ///< NewsFlags bits @see NewsFlags
byte display_mode; byte display_mode; ///< Display mode value @see NewsMode
byte type; byte type; ///< News category @see NewsType
byte callback; byte callback; ///< Call-back function
TileIndex data_a; TileIndex data_a; ///< Reference to tile or vehicle
TileIndex data_b; TileIndex data_b; ///< Reference to second tile or vehicle
uint64 params[10]; uint64 params[10];
}; };
@ -24,7 +24,20 @@ typedef bool ValidationProc ( uint data_a, uint data_b );
typedef void DrawNewsCallbackProc(Window *w); typedef void DrawNewsCallbackProc(Window *w);
typedef StringID GetNewsStringCallbackProc(const NewsItem *ni); typedef StringID GetNewsStringCallbackProc(const NewsItem *ni);
/**
* Macro for creating news flags.
* @param mode (bits 0 - 7) Display_mode, one of the NewsMode enums (NM_)
* @param flag (bits 8 - 15) OR-able news flags, any of the NewsFlags enums (NF_)
* @param type (bits 16-23) News category, one of the NewsType enums (NT_)
* @param cb (bits 24-31) Call-back function, one of the NewsCallback enums (DNC_) or 0 if no callback
* @see NewsMode
* @see NewsFlags
* @see NewsType
* @see NewsCallback
* @see AddNewsItem
*/
#define NEWS_FLAGS(mode, flag, type, cb) ((cb) << 24 | (type) << 16 | (flag) << 8 | (mode)) #define NEWS_FLAGS(mode, flag, type, cb) ((cb) << 24 | (type) << 16 | (flag) << 8 | (mode))
void AddNewsItem(StringID string, uint32 flags, uint data_a, uint data_b); void AddNewsItem(StringID string, uint32 flags, uint data_a, uint data_b);
void NewsLoop(); void NewsLoop();
void DrawNewsBorder(const Window *w); void DrawNewsBorder(const Window *w);
@ -32,23 +45,28 @@ void InitNewsItemStructs();
VARDEF NewsItem _statusbar_news_item; VARDEF NewsItem _statusbar_news_item;
/** Type of news. */
enum NewsType { enum NewsType {
NT_ARRIVAL_PLAYER, NT_ARRIVAL_PLAYER, ///< Cargo arrived for player
NT_ARRIVAL_OTHER, NT_ARRIVAL_OTHER, ///< Cargo arrived for competitor
NT_ACCIDENT, NT_ACCIDENT, ///< An accident or disaster has occurred
NT_COMPANY_INFO, NT_COMPANY_INFO, ///< Company info (new companies, bankrupcy messages)
NT_OPENCLOSE, NT_OPENCLOSE, ///< Opening and closing of industries
NT_ECONOMY, NT_ECONOMY, ///< Economic changes (recession, industry up/dowm)
NT_ADVICE, NT_ADVICE, ///< Bits of news about vehicles of the player
NT_NEW_VEHICLES, NT_NEW_VEHICLES, ///< New vehicle has become available
NT_ACCEPTANCE, NT_ACCEPTANCE, ///< A type of cargo is (no longer) accepted
NT_SUBSIDIES, NT_SUBSIDIES, ///< News about subsidies (announcements, expirations, acceptance)
NT_GENERAL, NT_GENERAL, ///< General news (from towns)
NT_END, NT_END, ///< end-of-array marker
}; };
extern const char *_news_display_name[NT_END]; extern const char *_news_display_name[NT_END];
/**
* News mode.
* @see NEWS_FLAGS
*/
enum NewsMode { enum NewsMode {
NM_SMALL = 0, ///< Show only a small popup informing us about vehicle age for example NM_SMALL = 0, ///< Show only a small popup informing us about vehicle age for example
NM_NORMAL = 1, ///< Show a simple news message (height 170 pixels) NM_NORMAL = 1, ///< Show a simple news message (height 170 pixels)
@ -56,6 +74,11 @@ enum NewsMode {
NM_CALLBACK = 3, ///< Do some special processing before displaying news message. Which callback to call is in NewsCallback NM_CALLBACK = 3, ///< Do some special processing before displaying news message. Which callback to call is in NewsCallback
}; };
/**
* Various OR-able news-item flags.
* note: NF_INCOLOR is set automatically if needed
* @see NEWS_FLAGS
*/
enum NewsFlags { enum NewsFlags {
NF_VIEWPORT = (1 << 1), ///< Does the news message have a viewport? (ingame picture of happening) NF_VIEWPORT = (1 << 1), ///< Does the news message have a viewport? (ingame picture of happening)
NF_TILE = (1 << 2), ///< When clicked on the news message scroll to a given tile? Tile is in data_a/data_b NF_TILE = (1 << 2), ///< When clicked on the news message scroll to a given tile? Tile is in data_a/data_b
@ -64,11 +87,13 @@ enum NewsFlags {
NF_INCOLOR = (1 << 5), ///< Show the newsmessage in colour, otherwise it defaults to black & white NF_INCOLOR = (1 << 5), ///< Show the newsmessage in colour, otherwise it defaults to black & white
}; };
/** Special news items */
enum NewsCallback { enum NewsCallback {
DNC_VEHICLEAVAIL = 0, ///< Show new vehicle available message. StringID is EngineID DNC_VEHICLEAVAIL = 0, ///< Show new vehicle available message. StringID is EngineID
DNC_BANKRUPCY = 1, ///< Show bankrupcy message. StringID is PlayerID (0-3) and NewsBankrupcy (4-7) DNC_BANKRUPCY = 1, ///< Show bankrupcy message. StringID is PlayerID (0-3) and NewsBankrupcy (4-7)
}; };
/** Kinds of bankrupcy */
enum NewsBankrupcy { enum NewsBankrupcy {
NB_BTROUBLE = (1 << 4), ///< Company is in trouble (warning) NB_BTROUBLE = (1 << 4), ///< Company is in trouble (warning)
NB_BMERGER = (2 << 4), ///< Company has been bought by another company NB_BMERGER = (2 << 4), ///< Company has been bought by another company

161
src/news_gui.cpp
View File

@ -1,6 +1,5 @@
/* $Id$ */ /* $Id$ */
/** @file news_gui.cpp */
#include "stdafx.h" #include "stdafx.h"
#include "openttd.h" #include "openttd.h"
@ -19,42 +18,50 @@
#include "date.h" #include "date.h"
#include "string.h" #include "string.h"
/* News system /** @file news_gui.cpp
*
* News system is realized as a FIFO queue (in an array) * News system is realized as a FIFO queue (in an array)
* The positions in the queue can't be rearranged, we only access * The positions in the queue can't be rearranged, we only access
* the array elements through pointers to the elements. Once the * the array elements through pointers to the elements. Once the
* array is full, the oldest entry (_oldest_news) is being overwritten * array is full, the oldest entry (\a _oldest_news) is being overwritten
* by the newest (_latest news). * by the newest (\a _latest_news).
* *
* \verbatim
* oldest current lastest * oldest current lastest
* | | | * | | |
* [O------------F-------------C---------L ] * [O------------F-------------C---------L ]
* | * |
* forced * forced
* \endverbatim
* *
* Of course by using an array we can have situations like * Of course by using an array we can have situations like
* *
* \verbatim
* [----L O-----F---------C-----------------] * [----L O-----F---------C-----------------]
* This is where we have wrapped around the array and have * This is where we have wrapped around the array and have
* (MAX_NEWS - O) + L news items * (MAX_NEWS - O) + L news items
* \endverbatim
*/ */
/** Number of news items in the FIFO queue */
#define MAX_NEWS 30 #define MAX_NEWS 30
#define NB_WIDG_PER_SETTING 4 #define NB_WIDG_PER_SETTING 4
typedef byte NewsID; typedef byte NewsID;
#define INVALID_NEWS 255 #define INVALID_NEWS 255
static NewsItem _news_items[MAX_NEWS]; static NewsItem _news_items[MAX_NEWS]; ///< The news FIFO queue
static NewsID _current_news = INVALID_NEWS; // points to news item that should be shown next static NewsID _current_news = INVALID_NEWS; ///< points to news item that should be shown next
static NewsID _oldest_news = 0; // points to first item in fifo queue static NewsID _oldest_news = 0; ///< points to first item in fifo queue
static NewsID _latest_news = INVALID_NEWS; // points to last item in fifo queue static NewsID _latest_news = INVALID_NEWS; ///< points to last item in fifo queue
/* if the message being shown was forced by the user, its index is stored in
* _forced_news. forced_news is INVALID_NEWS otherwise. /** Forced news item.
* (Users can force messages through history or "last message") */ * Users can force an item by accessing the history or "last message".
* If the message being shown was forced by the user, its index is stored in
* _forced_news. Otherwise, \a _forced_news variable is INVALID_NEWS. */
static NewsID _forced_news = INVALID_NEWS; static NewsID _forced_news = INVALID_NEWS;
static byte _total_news = 0; // total news count static byte _total_news = 0; ///< Number of news items in FIFO queue @see _news_items
void DrawNewsNewVehicleAvail(Window *w); void DrawNewsNewVehicleAvail(Window *w);
void DrawNewsBankrupcy(Window *w); void DrawNewsBankrupcy(Window *w);
@ -64,8 +71,8 @@ StringID GetNewsStringNewVehicleAvail(const NewsItem *ni);
StringID GetNewsStringBankrupcy(const NewsItem *ni); StringID GetNewsStringBankrupcy(const NewsItem *ni);
static DrawNewsCallbackProc * const _draw_news_callback[] = { static DrawNewsCallbackProc * const _draw_news_callback[] = {
DrawNewsNewVehicleAvail, //< DNC_VEHICLEAVAIL DrawNewsNewVehicleAvail, ///< DNC_VEHICLEAVAIL
DrawNewsBankrupcy, //< DNC_BANKRUPCY DrawNewsBankrupcy, ///< DNC_BANKRUPCY
}; };
extern GetNewsStringCallbackProc * const _get_news_string_callback[]; extern GetNewsStringCallbackProc * const _get_news_string_callback[];
@ -74,6 +81,7 @@ GetNewsStringCallbackProc * const _get_news_string_callback[] = {
GetNewsStringBankrupcy, ///< DNC_BANKRUPCY GetNewsStringBankrupcy, ///< DNC_BANKRUPCY
}; };
/** Initialize the news-items data structures */
void InitNewsItemStructs() void InitNewsItemStructs()
{ {
memset(_news_items, 0, sizeof(_news_items)); memset(_news_items, 0, sizeof(_news_items));
@ -219,42 +227,52 @@ static void NewsWindowProc(Window *w, WindowEvent *e)
} }
} }
/** Return the correct index in the pseudo-fifo /**
* queue and deals with overflows when increasing the index */ * Return the correct index in the pseudo-fifo
* queue and deals with overflows when increasing the index
*/
static inline NewsID increaseIndex(NewsID i) static inline NewsID increaseIndex(NewsID i)
{ {
assert(i != INVALID_NEWS); assert(i != INVALID_NEWS);
return (i + 1) % MAX_NEWS; return (i + 1) % MAX_NEWS;
} }
/** Return the correct index in the pseudo-fifo /**
* queue and deals with overflows when decreasing the index */ * Return the correct index in the pseudo-fifo
* queue and deals with overflows when decreasing the index
*/
static inline NewsID decreaseIndex(NewsID i) static inline NewsID decreaseIndex(NewsID i)
{ {
assert(i != INVALID_NEWS); assert(i != INVALID_NEWS);
return (i + MAX_NEWS - 1) % MAX_NEWS; return (i + MAX_NEWS - 1) % MAX_NEWS;
} }
/** Add a new newsitem to be shown. /**
* @param string String to display, can have special values based on parameter 'flags' * Add a new newsitem to be shown.
* @param string String to display, can have special values based on parameter \a flags
* @param flags various control bits that will show various news-types. See macro NEWS_FLAGS() * @param flags various control bits that will show various news-types. See macro NEWS_FLAGS()
* @param data_a news-specific value based on news type * @param data_a news-specific value based on news type
* @param data_b news-specific value based on news type * @param data_b news-specific value based on news type
* @note flags exists of 4 byte-sized extra parameters. * @note flags exists of 4 byte-sized extra parameters.
* 1. 0 - 7 display_mode, any of the NewsMode enums (NM_) * -# Bits 0 - 7 display_mode, any of the NewsMode enums (NM_)
* 2. 8 - 15 news flags, any of the NewsFlags enums (NF_) NF_INCOLOR are set automatically if needed * -# Bits 8 - 15 news flags, any of the NewsFlags enums (NF_)
* 3. 16 - 23 news category, any of the NewsType enums (NT_) * -# Bits 16 - 23 news category, any of the NewsType enums (NT_)
* 4. 24 - 31 news callback function, any of the NewsCallback enums (DNC_) * -# Bits 24 - 31 news callback function, any of the NewsCallback enums (DNC_)
* If the display mode is NM_CALLBACK special news is shown and parameter *
* stringid has a special meaning. * If the display mode is NM_CALLBACK, special news is shown and parameter
* DNC_TRAINAVAIL, DNC_ROADAVAIL, DNC_SHIPAVAIL, DNC_AIRCRAFTAVAIL: StringID is * \a string has a special meaning.
* the index of the engine that is shown * - For DNC_TRAINAVAIL, DNC_ROADAVAIL, DNC_SHIPAVAIL, DNC_AIRCRAFTAVAIL messages: StringID is
* DNC_BANKRUPCY: bytes 0-3 of StringID contains the player that is in trouble, * the index of the engine that is shown
* and 4-7 contains what kind of bankrupcy message is shown, NewsBankrupcy enum (NB_) *
* - For DNC_BANKRUPCY: bytes 0-3 of StringID contains the player that is in trouble,
* and 4-7 contains what kind of bankrupcy message is shown.
* @see NewsBankrupcy
*
* @see NewsMode * @see NewsMode
* @see NewsFlags * @see NewsFlags
* @see NewsType * @see NewsType
* @see NewsCallback */ * @see NewsCallback
*/
void AddNewsItem(StringID string, uint32 flags, uint data_a, uint data_b) void AddNewsItem(StringID string, uint32 flags, uint data_a, uint data_b)
{ {
NewsID l_news; NewsID l_news;
@ -310,8 +328,25 @@ void AddNewsItem(StringID string, uint32 flags, uint data_a, uint data_b)
} }
/* Don't show item if it's older than x days, corresponds with NewsType in news.h */ /**
static const byte _news_items_age[] = {60, 60, 90, 60, 90, 30, 150, 30, 90, 180}; * Maximum age of news items.
* Don't show item if it's older than x days, corresponds with NewsType in news.h
* @see NewsType
*/
static const byte _news_items_age[NT_END] = {
60, ///< NT_ARRIVAL_PLAYER
60, ///< NT_ARRIVAL_OTHER
90, ///< NT_ACCIDENT
60, ///< NT_COMPANY_INFO
90, ///< NT_OPENCLOSE
30, ///< NT_ECONOMY
150, ///< NT_ADVICE
30, ///< NT_NEW_VEHICLES
90, ///< NT_ACCEPTANCE
180, ///< NT_SUBSIDIES
60 ///< NT_GENERAL
};
static const Widget _news_type13_widgets[] = { static const Widget _news_type13_widgets[] = {
{ WWT_PANEL, RESIZE_NONE, 15, 0, 429, 0, 169, 0x0, STR_NULL}, { WWT_PANEL, RESIZE_NONE, 15, 0, 429, 0, 169, 0x0, STR_NULL},
@ -385,7 +420,8 @@ const char *_news_display_name[NT_END] = {
"general", "general",
}; };
/** Get the value of an item of the news-display settings. This is /**
* Get the value of an item of the news-display settings. This is
* a little tricky since on/off/summary must use 2 bits to store the value * a little tricky since on/off/summary must use 2 bits to store the value
* @param item the item whose value is requested * @param item the item whose value is requested
* @return return the found value which is between 0-2 * @return return the found value which is between 0-2
@ -396,7 +432,8 @@ static inline byte GetNewsDisplayValue(byte item)
return GB(_news_display_opt, item * 2, 2); return GB(_news_display_opt, item * 2, 2);
} }
/** Set the value of an item in the news-display settings. This is /**
* Set the value of an item in the news-display settings. This is
* a little tricky since on/off/summary must use 2 bits to store the value * a little tricky since on/off/summary must use 2 bits to store the value
* @param item the item whose value is being set * @param item the item whose value is being set
* @param val new value * @param val new value
@ -407,7 +444,7 @@ static inline void SetNewsDisplayValue(byte item, byte val)
SB(_news_display_opt, item * 2, 2, val); SB(_news_display_opt, item * 2, 2, val);
} }
/* open up an own newspaper window for the news item */ /** Open up an own newspaper window for the news item */
static void ShowNewspaper(NewsItem *ni) static void ShowNewspaper(NewsItem *ni)
{ {
Window *w; Window *w;
@ -457,7 +494,7 @@ static void ShowNewspaper(NewsItem *ni)
w->flags4 |= WF_DISABLE_VP_SCROLL; w->flags4 |= WF_DISABLE_VP_SCROLL;
} }
/* show news item in the ticker */ /** Show news item in the ticker */
static void ShowTicker(const NewsItem *ni) static void ShowTicker(const NewsItem *ni)
{ {
Window *w; Window *w;
@ -470,8 +507,10 @@ static void ShowTicker(const NewsItem *ni)
} }
/** Are we ready to show another news item? /**
* Only if nothing is in the newsticker and no newspaper is displayed */ * Are we ready to show another news item?
* Only if nothing is in the newsticker and no newspaper is displayed
*/
static bool ReadyForNextItem() static bool ReadyForNextItem()
{ {
const Window *w; const Window *w;
@ -493,6 +532,7 @@ static bool ReadyForNextItem()
return (ni->duration == 0 || FindWindowById(WC_NEWS_WINDOW, 0) == NULL); return (ni->duration == 0 || FindWindowById(WC_NEWS_WINDOW, 0) == NULL);
} }
/** Move to the next news item */
static void MoveToNextItem() static void MoveToNextItem()
{ {
DeleteWindowById(WC_NEWS_WINDOW, 0); DeleteWindowById(WC_NEWS_WINDOW, 0);
@ -509,26 +549,27 @@ static void MoveToNextItem()
if (_date - _news_items_age[ni->type] > ni->date) return; if (_date - _news_items_age[ni->type] > ni->date) return;
switch (GetNewsDisplayValue(ni->type)) { switch (GetNewsDisplayValue(ni->type)) {
case 0: { // Off - show nothing only a small reminder in the status bar default: NOT_REACHED();
Window *w = FindWindowById(WC_STATUS_BAR, 0); case 0: { // Off - show nothing only a small reminder in the status bar
Window *w = FindWindowById(WC_STATUS_BAR, 0);
if (w != NULL) { if (w != NULL) {
WP(w, def_d).data_2 = 91; WP(w, def_d).data_2 = 91;
SetWindowDirty(w); SetWindowDirty(w);
} }
break;
}
case 1: // Summary - show ticker, but if forced big, cascade to full
if (!(ni->flags & NF_FORCE_BIG)) {
ShowTicker(ni);
break; break;
} }
/* Fallthrough */
case 2: // Full - show newspaper case 1: // Summary - show ticker, but if forced big, cascade to full
ShowNewspaper(ni); if (!(ni->flags & NF_FORCE_BIG)) {
break; ShowTicker(ni);
break;
}
/* Fallthrough */
case 2: // Full - show newspaper
ShowNewspaper(ni);
break;
} }
} }
} }
@ -541,7 +582,7 @@ void NewsLoop()
if (ReadyForNextItem()) MoveToNextItem(); if (ReadyForNextItem()) MoveToNextItem();
} }
/* Do a forced show of a specific message */ /** Do a forced show of a specific message */
static void ShowNewsMessage(NewsID i) static void ShowNewsMessage(NewsID i)
{ {
if (_total_news == 0) return; if (_total_news == 0) return;
@ -561,6 +602,7 @@ static void ShowNewsMessage(NewsID i)
} }
} }
/** Show previous news item */
void ShowLastNewsMessage() void ShowLastNewsMessage()
{ {
if (_forced_news == INVALID_NEWS) { if (_forced_news == INVALID_NEWS) {
@ -594,7 +636,8 @@ static NewsID getNews(NewsID i)
return i; return i;
} }
/** Draw an unformatted news message truncated to a maximum length. If /**
* Draw an unformatted news message truncated to a maximum length. If
* length exceeds maximum length it will be postfixed by '...' * length exceeds maximum length it will be postfixed by '...'
* @param x,y position of the string * @param x,y position of the string
* @param color the color the string will be shown in * @param color the color the string will be shown in
@ -707,6 +750,7 @@ static const WindowDesc _message_history_desc = {
MessageHistoryWndProc MessageHistoryWndProc
}; };
/** Display window with news messages history */
void ShowMessageHistory() void ShowMessageHistory()
{ {
Window *w; Window *w;
@ -733,7 +777,8 @@ enum {
WIDGET_NEWSOPT_START_OPTION = 9, ///< First widget that is part of a group [<] .. [.] WIDGET_NEWSOPT_START_OPTION = 9, ///< First widget that is part of a group [<] .. [.]
}; };
/** Setup the disabled/enabled buttons in the message window /**
* Setup the disabled/enabled buttons in the message window
* If the value is 'off' disable the [<] widget, and enable the [>] one * If the value is 'off' disable the [<] widget, and enable the [>] one
* Same-wise for all the others. Starting value of 4 is the first widget * Same-wise for all the others. Starting value of 4 is the first widget
* group. These are grouped as [<][>] .. [<][>], etc. * group. These are grouped as [<][>] .. [<][>], etc.