cpp/openttd-patchpack/source Changeset - r7598:dfbbf23c60ad

Changeset - r7598:dfbbf23c60ad

Parent rev.

Child rev.

[Not reviewed]

master

0 2 0

rubidium - 17 years ago 2007-09-17 17:07:24
rubidium@openttd.org

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

2 files changed with 149 insertions and 79 deletions:

src/news.h

src/news_gui.cpp

103

0 comments (0 inline, 0 general)

src/news.h

➞

Show inline comments

@@ @@ -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

src/news_gui.cpp

➞

Show inline comments

 /* $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] = {
 ,  ///< 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
 };
 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.

0 comments (0 inline, 0 general)