Merge branch 'develop' into adv-beta

docs/changelog.txt

@@ -64,13 +64,15 @@ Template for new versions:
 ## Misc Improvements
 
 ## Documentation
+- Lua API document ``dfhack.items.findType(string)`` and ``dfhack.items.findSubtype(string)``
 
 ## API
 - ``Units``: new ``isWildlife`` and ``isAgitated`` property checks
 
 ## Lua
 - ``dfhack.units``: ``isWildlife`` and ``isAgitated`` property checks
 - ``dfhack.units.isDanger``: no longer returns true for intelligent undead
+- Overlay widgets can now assume their ``active`` and ``visible`` functions will only execute in a context that matches their ``viewscreens`` associations
 
 ## Removed
 

docs/dev/Lua API.rst

@@ -1641,8 +1641,9 @@ Units module
 
 * ``dfhack.units.getPosition(unit)``
 
-  Returns true *x,y,z* of the unit, or *nil* if invalid. May not be equal to
-  unit.pos if caged.
+  Returns the true *x,y,z* of the unit, or *nil* if invalid. You should
+  generally use this method instead of reading *unit.pos* directly since
+  that field can be inaccurate when the unit is caged.
 
 * ``dfhack.units.teleport(unit, pos)``
 
@@ -1964,27 +1965,29 @@ Military module
 Items module
 ------------
 
-* ``dfhack.items.getPosition(item)``
+* ``dfhack.items.findType(string)``
 
-  Returns true *x,y,z* of the item, or *nil* if invalid; may be not equal to item.pos
-  if in inventory.
+  Finds an item type by string and returns the ``df.item_type``. String is
+  case-sensitive (e.g., "TOOL").
 
-* ``dfhack.items.getBookTitle(item)``
+* ``dfhack.items.findSubtype(string)``
 
-  Returns the title of the "book" item, or an empty string if the item isn't a "book"
-  or it doesn't have a title. A "book" is a codex or a tool item that has page or
-  writings improvements, such as scrolls and quires.
+  Finds an item subtype by string and returns the subtype or *-1*. String is
+  case-sensitive (e.g., "TOOL:ITEM_TOOL_HIVE").
 
-* ``dfhack.items.getDescription(item, type[, decorate])``
+* ``dfhack.items.isCasteMaterial(item_type)``
 
-  Returns the string description of the item, as produced by the ``getItemDescription``
-  method. If decorate is true, also adds markings for quality and improvements.
+  Returns *true* if this item type uses a creature/caste pair as its material.
 
-* ``dfhack.items.getReadableDescription(item)``
+* ``dfhack.items.getSubtypeCount(item_type)``
 
-  Returns a string generally fit to usefully describe the item to the player.
-  When the item description appears anywhere in a script output or in the UI,
-  this is usually the string you should use.
+  Returns the number of raw-defined subtypes of the given item type, or *-1*
+  if not applicable.
+
+* ``dfhack.items.getSubtypeDef(item_type, subtype)``
+
+  Returns the raw definition for the given item type and subtype, or *nil*
+  if invalid.
 
 * ``dfhack.items.getGeneralRef(item, type)``
 
@@ -2005,7 +2008,7 @@ Items module
 
 * ``dfhack.items.getContainer(item)``
 
-  Returns the container item or *nil*.
+  Returns the item's container item or *nil*.
 
 * ``dfhack.items.getOuterContainerRef(item)``
 
@@ -2026,6 +2029,32 @@ Items module
 
   Returns the holder unit or *nil*.
 
+* ``dfhack.items.getPosition(item)``
+
+  Returns the true *x,y,z* of the item, or *nil* if invalid. You should generally
+  use this method instead of reading *item.pos* directly since that field only stores
+  the last position where the item was on the ground.
+
+* ``dfhack.items.getBookTitle(item)``
+
+  Returns the title of the "book" item, or an empty string if the item isn't a "book"
+  or it doesn't have a title. A "book" is a codex or a tool item that has page or
+  writing improvements, such as scrolls and quires.
+
+* ``dfhack.items.getDescription(item, type[, decorate])``
+
+  Returns the string description of the item, as produced by the ``getItemDescription``
+  method. A ``type`` of ``0`` results in a string like ``prickle berries [2]``. ``1``
+  results in the singular ``prickle berry``, and ``2`` results in the plural
+  ``prickle berries``. If decorate is *true*, also adds markings for quality and
+  improvements, as well as ``(foreign)`` indicator (when applicable).
+
+* ``dfhack.items.getReadableDescription(item)``
+
+  Returns a string generally fit to usefully describe the item to the player.
+  When the item description appears anywhere in a script output or in the UI,
+  this is usually the string you should use.
+
 * ``dfhack.items.moveToGround(item,pos)``
 
   Move the item to the ground at position. Returns *false* if impossible.
@@ -2060,36 +2089,17 @@ Items module
   Turns the item into a projectile, and returns the new object, or *nil*
   if impossible.
 
-* ``dfhack.items.isCasteMaterial(item_type)``
-
-  Returns *true* if this item type uses a creature/caste pair as its material.
-
-* ``dfhack.items.getSubtypeCount(item_type)``
-
-  Returns the number of raw-defined subtypes of the given item type, or *-1*
-  if not applicable.
-
-* ``dfhack.items.getSubtypeDef(item_type, subtype)``
-
-  Returns the raw definition for the given item type and subtype, or *nil*
-  if invalid.
-
 * ``dfhack.items.getItemBaseValue(item_type, subtype, material, mat_index)``
 
   Calculates the base value for an item of the specified type and material.
 
-* ``dfhack.items.getValue(item[, caravan_state])``
+* ``dfhack.items.getValue(item[,caravan_state])``
 
   Calculates the value of an item. If a ``df.caravan_state`` object is given
   (from ``df.global.plotinfo.caravans`` or
-  ``df.global.main_interface.trade.mer``), then the value is modified by civ
+  ``df.global.game.main_interface.trade.mer``), then the value is modified by civ
   properties and any trade agreements that might be in effect.
 
-* ``dfhack.items.isRequestedTradeGood(item[, caravan_state])``
-
-  Returns whether a caravan will pay extra for the given item. If caravan_state
-  is not given, checks all active caravans.
-
 * ``dfhack.items.createItem(unit, item_type, item_subtype, mat_type, mat_index, growth_print, no_floor)``
 
   Creates an item, similar to the `createitem` plugin.
@@ -2116,9 +2126,14 @@ Items module
 
   Marks the given item for trade at the given depot.
 
-* ``dfhack.items.canMelt(item[, game_ui])``
+* ``dfhack.items.isRequestedTradeGood(item[,caravan_state])``
+
+  Returns whether a caravan will pay extra for the given item. If caravan_state
+  is not given, checks all active caravans.
+
+* ``dfhack.items.canMelt(item[,game_ui])``
 
-  Returns true if the item can be designated for melting. Unless ``game_ui`` is
+  Returns true if the item can be melted (at a smelter). Unless ``game_ui`` is
   given and true, bars, non-empty metal containers, and items in unit
   inventories are not considered meltable, even though they can be designated
   for melting using the game UI.

docs/dev/overlay-dev-guide.rst

@@ -152,6 +152,11 @@ The ``overlay.OverlayWidget`` superclass defines the following class attributes:
     updates, set it to ``0`` and it will be noticed immediately.
 
 Common widget attributes such as ``active`` and ``visible`` are also respected.
+Note that those properties are checked *after* matching ``viewscreens`` focus
+string(s), so you can assume they are evaluated in an consistent context. For
+example, if your widget has ``viewscreens='dwarfmode/Trade/Default'``, then you
+can assume your ``visible=function() ... end`` function will be executing while
+the trade screen is active.
 
 Registering a widget with the overlay framework
 ***********************************************

library/LuaApi.cpp

@@ -2111,15 +2111,13 @@ static const LuaWrapper::FunctionReg dfhack_units_module[] = {
     { NULL, NULL }
 };
 
-static int units_getPosition(lua_State *state)
-{
+static int units_getPosition(lua_State *state) {
     return Lua::PushPosXYZ(state, Units::getPosition(Lua::CheckDFObject<df::unit>(state,1)));
 }
 
 static int units_getOuterContainerRef(lua_State *state)
 {
     auto ref = Units::getOuterContainerRef(Lua::CheckDFObject<df::unit>(state, 1));
-
     lua_newtable(state);
     Lua::TableInsert(state, "type", ref.type);
 
@@ -2137,7 +2135,6 @@ static int units_getOuterContainerRef(lua_State *state)
         default:
             Lua::TableInsert(state, "object", NULL);
     }
-
     return 1;
 }
 
@@ -2158,7 +2155,6 @@ static int units_getNoblePositions(lua_State *L) {
     }
     else
         luaL_argerror(L, 1, "Expected a unit or a historical figure");
-
     return 1;
 }
 
@@ -2225,7 +2221,6 @@ static int units_getUnitsByNobleRole(lua_State *L) {
 
 static int units_getCasteRaw(lua_State *state) {
     df::caste_raw *craw = NULL;
-
     if (lua_gettop(state) <= 1)
         craw = Units::getCasteRaw(Lua::CheckDFObject<df::unit>(state, 1));
     else // Use race, caste
@@ -2235,16 +2230,15 @@ static int units_getCasteRaw(lua_State *state) {
     return 1;
 }
 
-static int units_getStressCutoffs(lua_State *L)
-{
+static int units_getStressCutoffs(lua_State *L) {
     lua_newtable(L);
     for (size_t i = 0; i < Units::stress_cutoffs.size(); i++)
         Lua::TableInsert(L, i, Units::stress_cutoffs[i]);
     return 1;
 }
 
 static int units_assignTrainer(lua_State *L) {
-    df::unit * unit = Lua::CheckDFObject<df::unit>(L, 1);
+    auto unit = Lua::CheckDFObject<df::unit>(L, 1);
     int isNum = 0;
     int trainer_id = lua_tointegerx(L, 2, &isNum);
     if (!isNum || trainer_id < 0)
@@ -2311,21 +2305,24 @@ static const LuaWrapper::FunctionReg dfhack_military_module[] = {
 
 /***** Items module *****/
 
-static int16_t items_findType(string token)
-{
+static int16_t items_findType(string token) {
     DFHack::ItemTypeInfo result;
     result.find(token);
     return result.type;
 }
 
-static int32_t items_findSubtype(string token)
-{
+static int32_t items_findSubtype(string token) {
     DFHack::ItemTypeInfo result;
     result.find(token);
     return result.subtype;
 }
 
 static const LuaWrapper::FunctionReg dfhack_items_module[] = {
+    WRAPN(findType, items_findType),
+    WRAPN(findSubtype, items_findSubtype),
+    WRAPM(Items, isCasteMaterial),
+    WRAPM(Items, getSubtypeCount),
+    WRAPM(Items, getSubtypeDef),
     WRAPM(Items, getGeneralRef),
     WRAPM(Items, getSpecificRef),
     WRAPM(Items, getOwner),
@@ -2336,41 +2333,30 @@ static const LuaWrapper::FunctionReg dfhack_items_module[] = {
     WRAPM(Items, getBookTitle),
     WRAPM(Items, getDescription),
     WRAPM(Items, getReadableDescription),
-    WRAPM(Items, isCasteMaterial),
-    WRAPM(Items, getSubtypeCount),
-    WRAPM(Items, getSubtypeDef),
+    WRAPM(Items, moveToGround),
+    WRAPM(Items, moveToContainer),
+    WRAPM(Items, remove),
+    WRAPM(Items, makeProjectile),
     WRAPM(Items, getItemBaseValue),
     WRAPM(Items, getValue),
-    WRAPM(Items, isRequestedTradeGood),
     WRAPM(Items, checkMandates),
     WRAPM(Items, canTrade),
     WRAPM(Items, canTradeWithContents),
     WRAPM(Items, canTradeAnyWithContents),
     WRAPM(Items, markForTrade),
+    WRAPM(Items, isRequestedTradeGood),
     WRAPM(Items, canMelt),
     WRAPM(Items, markForMelting),
     WRAPM(Items, cancelMelting),
     WRAPM(Items, isRouteVehicle),
     WRAPM(Items, isSquadEquipment),
     WRAPM(Items, getCapacity),
-    WRAPM(Items, moveToGround),
-    WRAPM(Items, moveToContainer),
-    WRAPM(Items, makeProjectile),
-    WRAPM(Items, remove),
-    WRAPN(findType, items_findType),
-    WRAPN(findSubtype, items_findSubtype),
     { NULL, NULL }
 };
 
-static int items_getPosition(lua_State *state)
-{
-    return Lua::PushPosXYZ(state, Items::getPosition(Lua::CheckDFObject<df::item>(state,1)));
-}
-
 static int items_getOuterContainerRef(lua_State *state)
 {
     auto ref = Items::getOuterContainerRef(Lua::CheckDFObject<df::item>(state, 1));
-
     lua_newtable(state);
     Lua::TableInsert(state, "type", ref.type);
 
@@ -2388,33 +2374,34 @@ static int items_getOuterContainerRef(lua_State *state)
         default:
             Lua::TableInsert(state, "object", NULL);
     }
-
     return 1;
 }
 
-static int items_getContainedItems(lua_State *state)
-{
+static int items_getContainedItems(lua_State *state) {
     vector<df::item*> pvec;
     Items::getContainedItems(Lua::CheckDFObject<df::item>(state,1),&pvec);
     Lua::PushVector(state, pvec);
     return 1;
 }
 
+static int items_getPosition(lua_State *state) {
+    return Lua::PushPosXYZ(state, Items::getPosition(Lua::CheckDFObject<df::item>(state,1)));
+}
+
 static int items_moveToBuilding(lua_State *state)
 {
     auto item = Lua::CheckDFObject<df::item>(state, 1);
     auto building = Lua::CheckDFObject<df::building_actual>(state, 2);
-    df::building_item_role_type use_mode = (df::building_item_role_type)luaL_optint(state, 3, 0);
+    auto use_mode = (df::building_item_role_type)luaL_optint(state, 3, 0);
     bool force_in_building = lua_toboolean(state, 4);
     lua_pushboolean(state, Items::moveToBuilding(item, building, use_mode, force_in_building));
     return 1;
 }
 
-static int items_moveToInventory(lua_State *state)
-{
+static int items_moveToInventory(lua_State *state) {
     auto item = Lua::CheckDFObject<df::item>(state, 1);
     auto unit = Lua::CheckDFObject<df::unit>(state, 2);
-    df::unit_inventory_item::T_mode use_mode = (df::unit_inventory_item::T_mode)luaL_optint(state, 3, 0);
+    auto use_mode = (df::unit_inventory_item::T_mode)luaL_optint(state, 3, 0);
     int body_part = luaL_optint(state, 4, -1);
     lua_pushboolean(state, Items::moveToInventory(item, unit, use_mode, body_part));
     return 1;
@@ -2436,9 +2423,9 @@ static int items_createItem(lua_State *state)
 }
 
 static const luaL_Reg dfhack_items_funcs[] = {
-    { "getPosition", items_getPosition },
     { "getOuterContainerRef", items_getOuterContainerRef },
     { "getContainedItems", items_getContainedItems },
+    { "getPosition", items_getPosition },
     { "moveToBuilding", items_moveToBuilding },
     { "moveToInventory", items_moveToInventory },
     { "createItem", items_createItem },