diff --git a/src/news.h b/src/news.h --- a/src/news.h +++ b/src/news.h @@ -6,16 +6,16 @@ #define NEWS_H struct NewsItem { - StringID string_id; - uint16 duration; - Date date; - byte flags; - byte display_mode; - byte type; - byte callback; + StringID string_id; ///< Message text (sometimes also used for storing other info) + uint16 duration; ///< Remaining time for showing this news message + Date date; ///< Date of the news + byte flags; ///< NewsFlags bits @see NewsFlags + byte display_mode; ///< Display mode value @see NewsMode + byte type; ///< News category @see NewsType + byte callback; ///< Call-back function - TileIndex data_a; - TileIndex data_b; + TileIndex data_a; ///< Reference to tile or vehicle + TileIndex data_b; ///< Reference to second tile or vehicle uint64 params[10]; }; @@ -24,7 +24,20 @@ typedef bool ValidationProc ( uint data_ typedef void DrawNewsCallbackProc(Window *w); 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)) + void AddNewsItem(StringID string, uint32 flags, uint data_a, uint data_b); void NewsLoop(); void DrawNewsBorder(const Window *w); @@ -32,23 +45,28 @@ void InitNewsItemStructs(); VARDEF NewsItem _statusbar_news_item; +/** Type of news. */ enum NewsType { - NT_ARRIVAL_PLAYER, - NT_ARRIVAL_OTHER, - NT_ACCIDENT, - NT_COMPANY_INFO, - NT_OPENCLOSE, - NT_ECONOMY, - NT_ADVICE, - NT_NEW_VEHICLES, - NT_ACCEPTANCE, - NT_SUBSIDIES, - NT_GENERAL, - NT_END, + NT_ARRIVAL_PLAYER, ///< Cargo arrived for player + NT_ARRIVAL_OTHER, ///< Cargo arrived for competitor + NT_ACCIDENT, ///< An accident or disaster has occurred + NT_COMPANY_INFO, ///< Company info (new companies, bankrupcy messages) + NT_OPENCLOSE, ///< Opening and closing of industries + NT_ECONOMY, ///< Economic changes (recession, industry up/dowm) + NT_ADVICE, ///< Bits of news about vehicles of the player + NT_NEW_VEHICLES, ///< New vehicle has become available + NT_ACCEPTANCE, ///< A type of cargo is (no longer) accepted + NT_SUBSIDIES, ///< News about subsidies (announcements, expirations, acceptance) + NT_GENERAL, ///< General news (from towns) + NT_END, ///< end-of-array marker }; extern const char *_news_display_name[NT_END]; +/** + * News mode. + * @see NEWS_FLAGS + */ enum NewsMode { 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) @@ -56,6 +74,11 @@ enum NewsMode { 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 { 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 @@ -64,11 +87,13 @@ enum NewsFlags { NF_INCOLOR = (1 << 5), ///< Show the newsmessage in colour, otherwise it defaults to black & white }; +/** Special news items */ enum NewsCallback { 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) }; +/** Kinds of bankrupcy */ enum NewsBankrupcy { NB_BTROUBLE = (1 << 4), ///< Company is in trouble (warning) NB_BMERGER = (2 << 4), ///< Company has been bought by another company diff --git a/src/news_gui.cpp b/src/news_gui.cpp --- a/src/news_gui.cpp +++ b/src/news_gui.cpp @@ -1,6 +1,5 @@ /* $Id$ */ -/** @file news_gui.cpp */ #include "stdafx.h" #include "openttd.h" @@ -19,42 +18,50 @@ #include "date.h" #include "string.h" -/* News system +/** @file news_gui.cpp + * * News system is realized as a FIFO queue (in an array) * The positions in the queue can't be rearranged, we only access * the array elements through pointers to the elements. Once the - * array is full, the oldest entry (_oldest_news) is being overwritten - * by the newest (_latest news). + * array is full, the oldest entry (\a _oldest_news) is being overwritten + * by the newest (\a _latest_news). * + * \verbatim * oldest current lastest * | | | * [O------------F-------------C---------L ] * | * forced + * \endverbatim * * Of course by using an array we can have situations like * + * \verbatim * [----L O-----F---------C-----------------] * This is where we have wrapped around the array and have * (MAX_NEWS - O) + L news items + * \endverbatim */ +/** Number of news items in the FIFO queue */ #define MAX_NEWS 30 #define NB_WIDG_PER_SETTING 4 typedef byte NewsID; #define INVALID_NEWS 255 -static NewsItem _news_items[MAX_NEWS]; -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 _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. - * (Users can force messages through history or "last message") */ +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 _oldest_news = 0; ///< points to first item in fifo queue +static NewsID _latest_news = INVALID_NEWS; ///< points to last item in fifo queue + +/** Forced news item. + * 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 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 DrawNewsBankrupcy(Window *w); @@ -64,8 +71,8 @@ StringID GetNewsStringNewVehicleAvail(co StringID GetNewsStringBankrupcy(const NewsItem *ni); static DrawNewsCallbackProc * const _draw_news_callback[] = { - DrawNewsNewVehicleAvail, //< DNC_VEHICLEAVAIL - DrawNewsBankrupcy, //< DNC_BANKRUPCY + DrawNewsNewVehicleAvail, ///< DNC_VEHICLEAVAIL + DrawNewsBankrupcy, ///< DNC_BANKRUPCY }; extern GetNewsStringCallbackProc * const _get_news_string_callback[]; @@ -74,6 +81,7 @@ GetNewsStringCallbackProc * const _get_n GetNewsStringBankrupcy, ///< DNC_BANKRUPCY }; +/** Initialize the news-items data structures */ void InitNewsItemStructs() { memset(_news_items, 0, sizeof(_news_items)); @@ -219,42 +227,52 @@ static void NewsWindowProc(Window *w, Wi } } -/** 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) { assert(i != INVALID_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) { assert(i != INVALID_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 data_a 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. - * 1. 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 - * 3. 16 - 23 news category, any of the NewsType enums (NT_) - * 4. 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. - * DNC_TRAINAVAIL, DNC_ROADAVAIL, DNC_SHIPAVAIL, DNC_AIRCRAFTAVAIL: StringID is - * the index of the engine that is shown - * 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, NewsBankrupcy enum (NB_) + * -# Bits 0 - 7 display_mode, any of the NewsMode enums (NM_) + * -# Bits 8 - 15 news flags, any of the NewsFlags enums (NF_) + * -# Bits 16 - 23 news category, any of the NewsType enums (NT_) + * -# 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 + * \a string has a special meaning. + * - For DNC_TRAINAVAIL, DNC_ROADAVAIL, DNC_SHIPAVAIL, DNC_AIRCRAFTAVAIL messages: StringID is + * the index of the engine that is shown + * + * - 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 NewsFlags * @see NewsType - * @see NewsCallback */ + * @see NewsCallback + */ void AddNewsItem(StringID string, uint32 flags, uint data_a, uint data_b) { NewsID l_news; @@ -310,8 +328,25 @@ void AddNewsItem(StringID string, uint32 } -/* 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[] = { { WWT_PANEL, RESIZE_NONE, 15, 0, 429, 0, 169, 0x0, STR_NULL}, @@ -385,7 +420,8 @@ const char *_news_display_name[NT_END] = "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 * @param item the item whose value is requested * @return return the found value which is between 0-2 @@ -396,7 +432,8 @@ static inline byte GetNewsDisplayValue(b 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 * @param item the item whose value is being set * @param val new value @@ -407,7 +444,7 @@ static inline void SetNewsDisplayValue(b 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) { Window *w; @@ -457,7 +494,7 @@ static void ShowNewspaper(NewsItem *ni) w->flags4 |= WF_DISABLE_VP_SCROLL; } -/* show news item in the ticker */ +/** Show news item in the ticker */ static void ShowTicker(const NewsItem *ni) { Window *w; @@ -470,8 +507,10 @@ static void ShowTicker(const NewsItem *n } -/** 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() { const Window *w; @@ -493,6 +532,7 @@ static bool ReadyForNextItem() return (ni->duration == 0 || FindWindowById(WC_NEWS_WINDOW, 0) == NULL); } +/** Move to the next news item */ static void MoveToNextItem() { DeleteWindowById(WC_NEWS_WINDOW, 0); @@ -509,26 +549,27 @@ static void MoveToNextItem() if (_date - _news_items_age[ni->type] > ni->date) return; switch (GetNewsDisplayValue(ni->type)) { - case 0: { // Off - show nothing only a small reminder in the status bar - Window *w = FindWindowById(WC_STATUS_BAR, 0); + default: NOT_REACHED(); + case 0: { // Off - show nothing only a small reminder in the status bar + Window *w = FindWindowById(WC_STATUS_BAR, 0); - if (w != NULL) { - WP(w, def_d).data_2 = 91; - SetWindowDirty(w); - } - break; - } - - case 1: // Summary - show ticker, but if forced big, cascade to full - if (!(ni->flags & NF_FORCE_BIG)) { - ShowTicker(ni); + if (w != NULL) { + WP(w, def_d).data_2 = 91; + SetWindowDirty(w); + } break; } - /* Fallthrough */ - case 2: // Full - show newspaper - ShowNewspaper(ni); - break; + case 1: // Summary - show ticker, but if forced big, cascade to full + if (!(ni->flags & NF_FORCE_BIG)) { + ShowTicker(ni); + break; + } + /* Fallthrough */ + + case 2: // Full - show newspaper + ShowNewspaper(ni); + break; } } } @@ -541,7 +582,7 @@ void NewsLoop() if (ReadyForNextItem()) MoveToNextItem(); } -/* Do a forced show of a specific message */ +/** Do a forced show of a specific message */ static void ShowNewsMessage(NewsID i) { if (_total_news == 0) return; @@ -561,6 +602,7 @@ static void ShowNewsMessage(NewsID i) } } +/** Show previous news item */ void ShowLastNewsMessage() { if (_forced_news == INVALID_NEWS) { @@ -594,7 +636,8 @@ static NewsID getNews(NewsID 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 '...' * @param x,y position of the string * @param color the color the string will be shown in @@ -707,6 +750,7 @@ static const WindowDesc _message_history MessageHistoryWndProc }; +/** Display window with news messages history */ void ShowMessageHistory() { Window *w; @@ -733,7 +777,8 @@ enum { 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 * Same-wise for all the others. Starting value of 4 is the first widget * group. These are grouped as [<][>] .. [<][>], etc.