Merge pull request #4114 from myk002/myk_overlay_descriptions

Add overlay descriptions to all plugins

docs/dev/overlay-dev-guide.rst

@@ -89,11 +89,14 @@ The ``overlay.OverlayWidget`` superclass defines the following class attributes:
 - ``name``
     This will be filled in with the display name of your widget, in case you
     have multiple widgets with the same implementation but different
-    configurations.
+    configurations. You should not set this property yourself.
 - ``version``
     You can set this to any string. If the version string of a loaded widget
     does not match the saved settings for that widget, then the configuration
     for the widget (position, enabled status) will be reset to defaults.
+- ``desc``
+    A short (<100 character) description of what the overlay does. This text
+    will be displayed in `gui/control-panel` on the "Overlays" tab.
 - ``default_pos`` (default: ``{x=-2, y=-2}``)
     Override this attribute with your desired default widget position. See
     the `overlay` docs for information on what positive and negative numbers

plugins/lua/autolabor.lua

@@ -6,6 +6,7 @@ local widgets = require('gui.widgets')
 
 AutolaborOverlay = defclass(AutolaborOverlay, overlay.OverlayWidget)
 AutolaborOverlay.ATTRS{
+    desc='Adds information to the work details screen about whether work details are enabled.',
     default_pos={x=7,y=-13},
     default_enabled=true,
     viewscreens='dwarfmode/Info/LABOR/WORK_DETAILS',

plugins/lua/buildingplan/inspectoroverlay.lua

@@ -63,6 +63,7 @@ end
 
 InspectorOverlay = defclass(InspectorOverlay, overlay.OverlayWidget)
 InspectorOverlay.ATTRS{
+    desc='Adds information to planned buildings about what materials are still needed.',
     default_pos={x=-41,y=14},
     default_enabled=true,
     viewscreens='dwarfmode/ViewSheets/BUILDING',

plugins/lua/buildingplan/mechanisms.lua

@@ -13,6 +13,7 @@ local view_sheets = df.global.game.main_interface.view_sheets
 
 MechanismOverlay = defclass(MechanismOverlay, overlay.OverlayWidget)
 MechanismOverlay.ATTRS{
+    desc='Adds mechanism selection capabilities to the link lever/pressure plate screens.',
     default_pos={x=5,y=5},
     default_enabled=true,
     viewscreens='dwarfmode/LinkingLever',

plugins/lua/buildingplan/planneroverlay.lua

@@ -351,6 +351,7 @@ end
 
 PlannerOverlay = defclass(PlannerOverlay, overlay.OverlayWidget)
 PlannerOverlay.ATTRS{
+    desc='Shows the building planner interface panel when building buildings.',
     default_pos={x=5,y=9},
     default_enabled=true,
     viewscreens='dwarfmode/Building/Placement',

plugins/lua/burrow.lua

@@ -52,6 +52,7 @@ end
 
 BurrowDesignationOverlay = defclass(BurrowDesignationOverlay, overlay.OverlayWidget)
 BurrowDesignationOverlay.ATTRS{
+    desc='Adds flood fill and 3D box select functionality to burrow designations.',
     default_pos={x=6,y=9},
     viewscreens='dwarfmode/Burrow/Paint',
     default_enabled=true,

plugins/lua/dig.lua

@@ -5,6 +5,7 @@ local pathable = require('plugins.pathable')
 
 WarmDampOverlay = defclass(WarmDampOverlay, overlay.OverlayWidget)
 WarmDampOverlay.ATTRS{
+    desc='Makes warm and damp tiles visible when in ASCII mode.',
     viewscreens={
         'dwarfmode/Designate/DIG_DIG',
         'dwarfmode/Designate/DIG_REMOVE_STAIRS_RAMPS',
@@ -26,6 +27,7 @@ end
 
 CarveOverlay = defclass(CarveOverlay, overlay.OverlayWidget)
 CarveOverlay.ATTRS{
+    desc='Makes existing carving designations visible when in ASCII mode.',
     viewscreens={
         'dwarfmode/Designate/SMOOTH',
         'dwarfmode/Designate/ENGRAVE',

plugins/lua/hotkeys.lua

@@ -27,6 +27,7 @@ end
 
 HotspotMenuWidget = defclass(HotspotMenuWidget, overlay.OverlayWidget)
 HotspotMenuWidget.ATTRS{
+    desc='Shows the DFHack logo context menu button.',
     default_pos={x=5,y=1},
     default_enabled=true,
     version=2,

plugins/lua/orders.lua

@@ -68,6 +68,7 @@ end
 
 OrdersOverlay = defclass(OrdersOverlay, overlay.OverlayWidget)
 OrdersOverlay.ATTRS{
+    desc='Adds import, export, and other functions to the manager orders screen.',
     default_pos={x=53,y=-6},
     default_enabled=true,
     viewscreens='dwarfmode/Info/WORK_ORDERS/Default',
@@ -198,6 +199,7 @@ local focusString = 'dwarfmode/Info/WORK_ORDERS/Conditions'
 
 RecheckOverlay = defclass(RecheckOverlay, overlay.OverlayWidget)
 RecheckOverlay.ATTRS{
+    desc='Adds a button to the work order details page to tell the manager to recheck conditions.',
     default_pos={x=6,y=8},
     default_enabled=true,
     viewscreens=focusString,

plugins/lua/overlay.lua

@@ -553,6 +553,7 @@ end
 OverlayWidget = defclass(OverlayWidget, widgets.Panel)
 OverlayWidget.ATTRS{
     name=DEFAULT_NIL, -- this is set by the framework to the widget name
+    desc=DEFAULT_NIL, -- add a short description (<100 chars); displays in control panel
     default_pos={x=DEFAULT_X_POS, y=DEFAULT_Y_POS}, -- 1-based widget screen pos
     default_enabled=false, -- initial enabled state if not in config
     overlay_only=false, -- true if there is no widget to reposition
@@ -581,6 +582,7 @@ end
 
 TitleVersionOverlay = defclass(TitleVersionOverlay, OverlayWidget)
 TitleVersionOverlay.ATTRS{
+    desc='Show DFHack version number and quick links on the DF title page.',
     default_pos={x=11, y=1},
     version=2,
     default_enabled=true,

plugins/lua/sort.lua

@@ -636,6 +636,7 @@ end
 
 SquadAssignmentOverlay = defclass(SquadAssignmentOverlay, overlay.OverlayWidget)
 SquadAssignmentOverlay.ATTRS{
+    desc='Adds search, sort, and filter capabilities to the squad assignment screen.',
     default_pos={x=18, y=5},
     default_enabled=true,
     viewscreens='dwarfmode/UnitSelector/SQUAD_FILL_POSITION',
@@ -1198,6 +1199,7 @@ end
 
 SquadAnnotationOverlay = defclass(SquadAnnotationOverlay, overlay.OverlayWidget)
 SquadAnnotationOverlay.ATTRS{
+    desc='Annotates squad selection candidates with the values of the current sort.',
     default_pos={x=56, y=5},
     default_enabled=true,
     viewscreens='dwarfmode/UnitSelector/SQUAD_FILL_POSITION',

plugins/lua/sort/diplomacy.lua

@@ -12,6 +12,7 @@ local diplomacy = df.global.game.main_interface.diplomacy
 
 DiplomacyOverlay = defclass(DiplomacyOverlay, sortoverlay.SortOverlay)
 DiplomacyOverlay.ATTRS{
+    desc='Adds search and sort functionality to the elevate unit to barony screen.',
     default_pos={x=25, y=7},
     viewscreens='dwarfmode/Diplomacy',
     frame={w=57, h=1},
@@ -110,6 +111,7 @@ end
 
 PreferenceOverlay = defclass(PreferenceOverlay, overlay.OverlayWidget)
 PreferenceOverlay.ATTRS{
+    desc='Adds information about unit preferences to the elevate unit to barony screen.',
     default_pos={x=-34, y=9},
     viewscreens='dwarfmode/Diplomacy/ElevateLandHolder',
     default_enabled=true,

plugins/lua/sort/info.lua

@@ -190,6 +190,7 @@ end
 
 InfoOverlay = defclass(InfoOverlay, sortoverlay.SortOverlay)
 InfoOverlay.ATTRS{
+    desc='Adds search and filter functionality to most info panels.',
     default_pos={x=64, y=8},
     viewscreens='dwarfmode/Info',
     frame={w=40, h=6},
@@ -493,6 +494,7 @@ end
 
 CandidatesOverlay = defclass(CandidatesOverlay, sortoverlay.SortOverlay)
 CandidatesOverlay.ATTRS{
+    desc='Adds search functionality to the noble assignment page.',
     default_pos={x=54, y=8},
     viewscreens='dwarfmode/Info/ADMINISTRATORS/Candidates',
     frame={w=27, h=3},
@@ -547,6 +549,7 @@ end
 
 WorkAnimalOverlay = defclass(WorkAnimalOverlay, overlay.OverlayWidget)
 WorkAnimalOverlay.ATTRS{
+    desc='Annotates units with how many work animals they have assigned on the assign work animal screen.',
     default_pos={x=-33, y=12},
     viewscreens='dwarfmode/Info/CREATURES/AssignWorkAnimal',
     default_enabled=true,
@@ -617,6 +620,7 @@ end
 
 InterrogationOverlay = defclass(InterrogationOverlay, sortoverlay.SortOverlay)
 InterrogationOverlay.ATTRS{
+    desc='Adds search and filter capabilities to the justice screens.',
     default_pos={x=47, y=10},
     viewscreens='dwarfmode/Info/JUSTICE',
     frame={w=27, h=9},

plugins/lua/sort/locationselector.lua

@@ -11,6 +11,7 @@ local location_selector = df.global.game.main_interface.location_selector
 
 LocationSelectorOverlay = defclass(LocationSelectorOverlay, sortoverlay.SortOverlay)
 LocationSelectorOverlay.ATTRS{
+    desc='Adds search and filter capabilities to the temple and guildhall establishment screens.',
     default_pos={x=48, y=6},
     viewscreens='dwarfmode/LocationSelector',
     frame={w=26, h=3},

plugins/lua/sort/places.lua

@@ -147,6 +147,7 @@ end
 
 PlacesOverlay = defclass(PlacesOverlay, sortoverlay.SortOverlay)
 PlacesOverlay.ATTRS{
+    desc='Adds search functionality to the places overview screens.',
     default_pos={x=71, y=9},
     viewscreens='dwarfmode/Info',
     frame={w=40, h=6}

plugins/lua/sort/slab.lua

@@ -12,6 +12,7 @@ local building = df.global.game.main_interface.building
 
 SlabOverlay = defclass(SlabOverlay, sortoverlay.SortOverlay)
 SlabOverlay.ATTRS{
+    desc='Adds search and filter functionality to the slab engraving panel.',
     default_pos={x=-40, y=12},
     viewscreens='dwarfmode/ViewSheets/BUILDING/Workshop',
     frame={w=57, h=3},

plugins/lua/sort/unitselector.lua

@@ -16,6 +16,7 @@ local WIDGET_WIDTH = 31
 
 UnitSelectorOverlay = defclass(UnitSelectorOverlay, sortoverlay.SortOverlay)
 UnitSelectorOverlay.ATTRS{
+    desc='Adds search functionality to the unit assignment screens.',
     default_pos={x=62, y=6},
     viewscreens='dwarfmode/UnitSelector',
     frame={w=31, h=1},

plugins/lua/sort/world.lua

@@ -9,6 +9,7 @@ local widgets = require('gui.widgets')
 
 WorldOverlay = defclass(WorldOverlay, sortoverlay.SortOverlay)
 WorldOverlay.ATTRS{
+    desc='Adds search functionality to the artifact list on the world raid screen.',
     default_pos={x=-18, y=2},
     viewscreens='world/ARTIFACTS',
     frame={w=40, h=1},

plugins/lua/stockpiles.lua

@@ -394,6 +394,7 @@ end
 
 StockpilesOverlay = defclass(StockpilesOverlay, overlay.OverlayWidget)
 StockpilesOverlay.ATTRS{
+    desc='Shows a panel when a stockpile is selected for stockpile automation.',
     default_pos={x=24, y=-6},
     default_enabled=true,
     viewscreens='dwarfmode/Some/Stockpile',

plugins/lua/stocks.lua

@@ -20,6 +20,7 @@ end
 
 StocksOverlay = defclass(StocksOverlay, overlay.OverlayWidget)
 StocksOverlay.ATTRS{
+    desc='Adds a hotkey for collapse all to the stocks page.',
     default_pos={x=-3,y=-20},
     default_enabled=true,
     viewscreens='dwarfmode/Stocks',

plugins/lua/zone.lua

@@ -835,6 +835,7 @@ end
 
 PasturePondOverlay = defclass(PasturePondOverlay, overlay.OverlayWidget)
 PasturePondOverlay.ATTRS{
+    desc='Adds a link to launch the animal assignment UI to pastures and ponds.',
     default_pos={x=7,y=13},
     default_enabled=true,
     viewscreens={'dwarfmode/Zone/Some/Pen', 'dwarfmode/Zone/Some/Pond'},
@@ -952,6 +953,7 @@ end
 
 CageChainOverlay = defclass(CageChainOverlay, overlay.OverlayWidget)
 CageChainOverlay.ATTRS{
+    desc='Adds a link to launch the animal assignment UI to cages and chains.',
     default_pos={x=-40,y=34},
     default_enabled=true,
     viewscreens={'dwarfmode/ViewSheets/BUILDING/Cage', 'dwarfmode/ViewSheets/BUILDING/Chain'},

scripts

@@ -1 +1 @@
-Subproject commit 1880f4a9d528f8ae3a39b619bca89520185061ef
+Subproject commit 596cd5f64ad1759e390cf12cdd97e2698f6bd3b3