add a script function to flash parts of the target box

Add the `hu.flashTargetBox()` function.  Also move the `STR` macro to scp_defines.h and rename it `SCP_TOKEN_TO_STR`.

code/globalincs/scp_defines.h

@@ -6,6 +6,11 @@
 #define SCP_TOKEN_CONCAT1(x, y) x ## y
 #define SCP_TOKEN_CONCAT(x, y) SCP_TOKEN_CONCAT1(x, y)
 
+// these are useful for embedding numbers in strings
+// see https://stackoverflow.com/questions/5459868/concatenate-int-to-string-using-c-preprocessor
+#define SCP_TOKEN_TO_STR1(x) #x
+#define SCP_TOKEN_TO_STR(x) SCP_TOKEN_TO_STR1(x)
+
 #define SCP_UNUSED(x) (void)(x)
 
 #endif // SCP_DEFINES_H

code/parse/sexp.cpp

@@ -115,11 +115,6 @@
 #undef MessageBox
 #endif
 
-// these are useful for embedding numbers in SEXP help strings
-// see https://stackoverflow.com/questions/5459868/concatenate-int-to-string-using-c-preprocessor
-#define STR_HELPER(x) #x
-#define STR(x) STR_HELPER(x)
-
 
 SCP_vector<sexp_oper> Operators = {
 //   Operator, Identity, Min / Max arguments
@@ -34013,7 +34008,7 @@ SCP_vector<sexp_help_struct> Sexp_help = {
 	// Goober5000
 	{ OP_AI_IGNORE_NEW, "Ai-ignore-new (Ship goal)\r\n"
 		"\tTells the specified ship to ignore the given target and not consider it when picking something "
-		"to attack.  Up to " STR(MAX_IGNORE_NEW_OBJECTS) " targets can be ignored at a time.  Targets ignored by "
+		"to attack.  Up to " SCP_TOKEN_TO_STR(MAX_IGNORE_NEW_OBJECTS) " targets can be ignored at a time.  Targets ignored by "
 		"any given ship do not affect targets ignored by any other ship.\r\n\r\n"
 		"Takes 2 arguments...\r\n"
 		"\t1:\tName of target to ignore.\r\n"
@@ -34849,7 +34844,7 @@ SCP_vector<sexp_help_struct> Sexp_help = {
 		"\t4: List of subsys names not to be randomized\r\n"},
 
 	{ OP_SUPERNOVA_START, "supernova-start\r\n"
-		"\t1: Time in seconds that the supernova lasts.  Note that it will actually hit the player at " STR(SUPERNOVA_CUT_TIME) " seconds.  If you want the HUD gauge to adjust for this, use the '$Supernova hits at zero' game_settings.tbl option.\r\n"},
+		"\t1: Time in seconds that the supernova lasts.  Note that it will actually hit the player at " SCP_TOKEN_TO_STR(SUPERNOVA_HIT_TIME) " seconds.  If you want the HUD gauge to adjust for this, use the '$Supernova hits at zero' game_settings.tbl option.\r\n"},
 
 	{ OP_SUPERNOVA_STOP, "supernova-stop\r\n"
 		"\t Stops a supernova in progress.\r\n"

code/scripting/api/libs/hud.cpp

@@ -2,10 +2,12 @@
 //
 
 #include "hud.h"
+#include "scripting/api/objs/enums.h"
 #include "scripting/api/objs/hudgauge.h"
 
 #include "hud/hud.h"
 #include "hud/hudconfig.h"
+#include "hud/hudtargetbox.h"
 
 namespace scripting {
 namespace api {
@@ -190,7 +192,51 @@ ADE_FUNC(getHUDGaugeHandle, l_HUD, "string Name", "Returns a handle to a specifi
 		return ade_set_args(L, "o", l_HudGauge.Set(gauge));
 }
 
+ADE_FUNC(flashTargetBox, l_HUD, "enumeration section, [number duration_in_milliseconds]", "Flashes a section of the target box with a default duration of " SCP_TOKEN_TO_STR(TBOX_FLASH_DURATION) " milliseconds", nullptr, nullptr)
+{
+	enum_h section;
+	int num_args, duration;
+	
+	num_args = ade_get_args(L, "o|i", l_Enum.Get(&section), &duration);
+	if (num_args == 1)
+		duration = TBOX_FLASH_DURATION;
+	else if (num_args != 2)
+		return ADE_RETURN_NIL;
+
+	if (duration <= 1)
+		return ADE_RETURN_NIL;
+
+	int section_index = 0;
+	if (section.IsValid())
+	{
+		switch (section.index)
+		{
+			case LE_TBOX_FLASH_NAME:
+				section_index = TBOX_FLASH_NAME;
+				break;
+			case LE_TBOX_FLASH_CARGO:
+				section_index = TBOX_FLASH_CARGO;
+				break;
+			case LE_TBOX_FLASH_HULL:
+				section_index = TBOX_FLASH_HULL;
+				break;
+			case LE_TBOX_FLASH_STATUS:
+				section_index = TBOX_FLASH_STATUS;
+				break;
+			case LE_TBOX_FLASH_SUBSYS:
+				section_index = TBOX_FLASH_SUBSYS;
+				break;
+			default:
+				Warning(LOCATION, "Invalid targetbox section enumeration!");
+				return ADE_RETURN_NIL;
+		}
+	}
+
+	hud_targetbox_start_flash(section_index, duration);
+
+	return ADE_RETURN_NIL;
+}
+
 
 }
 }
-

code/scripting/api/objs/enums.cpp

@@ -131,6 +131,11 @@ flag_def_list Enumerations[] = {
 	{ "MOVIE_PRE_DEBRIEF", MOVIE_PRE_DEBRIEF, 0 },
 	{ "MOVIE_END_CAMPAIGN", MOVIE_END_CAMPAIGN, 0 },
 	// end of MOVIE_ definitions
+	{"TBOX_FLASH_NAME", LE_TBOX_FLASH_NAME, 0},
+	{"TBOX_FLASH_CARGO", LE_TBOX_FLASH_CARGO, 0},
+	{"TBOX_FLASH_HULL", LE_TBOX_FLASH_HULL, 0},
+	{"TBOX_FLASH_STATUS", LE_TBOX_FLASH_STATUS, 0},
+	{"TBOX_FLASH_SUBSYS", LE_TBOX_FLASH_SUBSYS, 0},
 };
 // clang-format on
 

code/scripting/api/objs/enums.h

@@ -104,8 +104,13 @@ const int32_t LE_GR_RESIZE_FULL_CENTER       = 100;
 const int32_t LE_GR_RESIZE_MENU              = 101;
 const int32_t LE_GR_RESIZE_MENU_ZOOMED       = 102;
 const int32_t LE_GR_RESIZE_MENU_NO_OFFSET    = 103;
+const int32_t LE_TBOX_FLASH_NAME             = 104;
+const int32_t LE_TBOX_FLASH_CARGO            = 105;
+const int32_t LE_TBOX_FLASH_HULL             = 106;
+const int32_t LE_TBOX_FLASH_STATUS           = 107;
+const int32_t LE_TBOX_FLASH_SUBSYS           = 108;
 
-const int ENUM_NEXT_INDEX = 104; // <<<<<<<<<<<<<<<<<<<<<<
+const int ENUM_NEXT_INDEX = 109; // <<<<<<<<<<<<<<<<<<<<<<
 extern flag_def_list Enumerations[];
 extern size_t Num_enumerations;