gdharness 1.2.39 → 1.2.40

package/build/godot/addons/gdharness_runtime/runtime_input.gd

@@ -12,6 +12,7 @@ const Values = preload("runtime_values.gd")
 const Queries = preload("runtime_queries.gd")
 const Read = preload("reading.gd")
 const Hover = preload("runtime_hover.gd")
+const Items = preload("runtime_items.gd")
 const Screen = preload("runtime_screen.gd")
 const Targets = preload("runtime_targets.gd")
 const Mouse = preload("runtime_mouse.gd")
@@ -509,6 +510,7 @@ func click(params: Dictionary) -> Dictionary:
 	var node_path: String = str(params.get("path", ""))
 	var wanted: String = str(params.get("says", ""))
 	var found: Variant = null
+	var item: Variant = null
 	if not wanted.is_empty():
 		var picked: Dictionary = Targets.control_saying(
 			_host.get_tree().root, "/root" if node_path.is_empty() else node_path, wanted, params.get("index")
@@ -517,6 +519,7 @@ func click(params: Dictionary) -> Dictionary:
 			return picked
 		node_path = picked["path"]
 		found = picked["found"]
+		item = picked.get("item")
 	if node_path.is_empty():
 		return {"type": "error", "message": "click needs a path, or says to find the control by its words"}
 
@@ -541,6 +544,16 @@ func click(params: Dictionary) -> Dictionary:
 	# other words, a link among them. Said either way, so a press on the middle is never read as one
 	# on the words.
 	var aim: Vector2 = control.size * 0.5
+	var item_scrolled: bool = false
+	if item != null:
+		var found_by_words: Dictionary = found
+		var placed_item: Dictionary = await Items.in_view(
+			_host.get_tree(), control, node_path, item, wanted, found_by_words
+		)
+		if placed_item.has("message"):
+			return placed_item
+		aim = placed_item["point"]
+		item_scrolled = placed_item["scrolled"]
 	var rich: RichTextLabel = control as RichTextLabel
 	if found != null and rich != null:
 		var placed: Dictionary = Targets.point_on_words(rich, wanted)
@@ -568,9 +581,9 @@ func click(params: Dictionary) -> Dictionary:
 	# off the top of its container is inside the viewport, behind whatever is drawn up there, so
 	# the click went to that instead and said so. Measured on a hall whose staff panel had been
 	# scrolled past: the button was at y 69 and its container started at y 166.
-	var scrolled: bool = false
+	var scrolled: bool = item_scrolled
 	if not _in_sight(control, own, local):
-		scrolled = await _scroll_into_view(control)
+		scrolled = await _scroll_into_view(control) or item_scrolled
 		var left: String = Values.afterwards(control)
 		if left != "in_tree":
 			return {

package/build/godot/addons/gdharness_runtime/runtime_items.gd

@@ -0,0 +1,175 @@
+extends RefCounted
+
+## Where a control drawing a list draws one of its items, for a click by words: a tab, a list entry,
+## a tree row or a menu bar title. Each is drawn by the control rather than held as a node, so a click
+## on the control's path presses its middle, which is whichever item happens to sit there.
+
+const Says = preload("runtime_says.gd")
+const Values = preload("runtime_values.gd")
+const Words = preload("runtime_words.gd")
+
+
+## Where [param control] draws [param item], one of [method Words.items_of], in the control's own
+## space, or an empty rectangle while it draws it nowhere a pointer reaches: a tab scrolled off its
+## bar, an entry or a row scrolled out of its list, a menu bar the operating system draws. A tree
+## row is the cell saying [param wanted] when one does, and the whole row otherwise.
+##
+## Each one checked against the control's own answer to which item is under a point, where it has
+## one, since an entry's rectangle is kept in the list's unscrolled space and a row's is computed
+## from the scroll as of the last draw.
+static func item_rect(control: Control, item: Variant, wanted: String) -> Rect2:
+	var bounds: Rect2 = Rect2(Vector2.ZERO, control.size)
+	var bar: TabBar = control as TabBar
+	if bar != null:
+		var tab: int = item
+		var placed: Rect2 = bar.get_tab_rect(tab)
+		return placed if bar.get_tab_idx_at_point(placed.get_center()) == tab else Rect2()
+	var list: ItemList = control as ItemList
+	if list != null:
+		var entry: int = item
+		var scrolled: Vector2 = Vector2(list.get_h_scroll_bar().value, list.get_v_scroll_bar().value)
+		var placed: Rect2 = list.get_item_rect(entry, false)
+		placed.position -= scrolled
+		var reached: bool = bounds.has_point(placed.get_center())
+		return (
+			placed if reached and list.get_item_at_position(placed.get_center(), true) == entry else Rect2()
+		)
+	var tree: Tree = control as Tree
+	if tree != null:
+		var row: TreeItem = item
+		var column: int = tree_column(tree, row, wanted)
+		var placed: Rect2 = tree.get_item_area_rect(row, column)
+		var centre: Vector2 = placed.get_center()
+		if not bounds.has_point(centre) or tree.get_item_at_position(centre) != row:
+			return Rect2()
+		return placed if column == -1 or tree.get_column_at_position(centre) == column else Rect2()
+	var menus: MenuBar = control as MenuBar
+	if menus != null and not menus.is_native_menu():
+		var menu: int = item
+		return _menu_title_rect(menus, menu)
+	return Rect2()
+
+
+## The column of [param row] whose cell says [param wanted], or -1 when only the row as a whole
+## does, its cells read together.
+static func tree_column(tree: Tree, row: TreeItem, wanted: String) -> int:
+	for column: int in tree.columns:
+		if Says.matches(Words.cell_says(tree, row, column), wanted):
+			return column
+	return -1
+
+
+## [param item] of [param control] as an answer names it: what it is, its number where the control
+## numbers its items, and what it says.
+static func item_named(control: Control, item: Variant, says: String) -> Dictionary:
+	if control is Tree:
+		return {"kind": "row", "says": says}
+	var kind: String = "tab" if control is TabBar else ("menu" if control is MenuBar else "item")
+	return {"kind": kind, "index": item, "says": says}
+
+
+## Where in [param control] to press for [param item], the one of its items a click by
+## [param wanted] matched, as {"point", "scrolled"}, or a refusal saying why there is nowhere.
+##
+## Scrolled into the control's own view first when it is drawn nowhere yet, the way a player brings
+## a tab or an entry into view before pressing it. A disabled item is refused as a disabled button
+## is. A tree row is pressed on the cell saying the words, whose column goes into [param found].
+static func in_view(
+	scene: SceneTree, control: Control, node_path: String, item: Variant, wanted: String, found: Dictionary
+) -> Dictionary:
+	var named: Dictionary = found.get("item", {})
+	var naming: String = 'the %s "%s" of %s' % [named.get("kind", "item"), named.get("says", ""), node_path]
+	var index: int = item if item is int else -1
+	var bar: TabBar = control as TabBar
+	var list: ItemList = control as ItemList
+	var menus: MenuBar = control as MenuBar
+	if (
+		(bar != null and bar.is_tab_disabled(index))
+		or (list != null and list.is_item_disabled(index))
+		or (menus != null and menus.is_menu_disabled(index))
+	):
+		return {"type": "error", "message": "%s is disabled, so clicking it presses nothing" % naming}
+	var placed: Rect2 = item_rect(control, item, wanted)
+	var scrolled: bool = false
+	if placed.size == Vector2.ZERO:
+		scrolled = _scroll_to(control, item)
+		if scrolled:
+			# A tree places its rows by the scroll it last drew with.
+			await scene.process_frame
+			var left: String = Values.afterwards(control)
+			if left != "in_tree" or (typeof(item) == TYPE_OBJECT and not is_instance_valid(item)):
+				return {
+					"type": "error",
+					"message":
+					"%s went while it was being scrolled into view, so nothing was clicked" % naming
+				}
+			placed = item_rect(control, item, wanted)
+	if placed.size == Vector2.ZERO:
+		var tried: String = " even scrolled to" if scrolled else ""
+		return {
+			"type": "error",
+			"message": "%s is drawn nowhere a pointer reaches%s, so nothing was clicked" % [naming, tried]
+		}
+	var tree: Tree = control as Tree
+	if tree != null:
+		var row: TreeItem = item
+		var column: int = tree_column(tree, row, wanted)
+		if column != -1:
+			named["column"] = column
+	return {"point": placed.get_center(), "scrolled": scrolled}
+
+
+## Where [param menus] draws the title of [param menu], worked out as the engine works it out,
+## since the bar keeps it to itself: each title shaped in the bar's font, padded by its normal style
+## and spaced by its separation, counting only the menus it shows.
+static func _menu_title_rect(menus: MenuBar, menu: int) -> Rect2:
+	var style: StyleBox = menus.get_theme_stylebox("normal")
+	var separation: int = menus.get_theme_constant("h_separation")
+	var offset: int = 0
+	for before: int in menu:
+		if not menus.is_menu_hidden(before):
+			offset += int(_menu_title_size(menus, before, style).x + separation)
+	var size: Vector2 = _menu_title_size(menus, menu, style)
+	var x: float = menus.size.x - offset - size.x if menus.is_layout_rtl() else float(offset)
+	return Rect2(Vector2(x, 0), size)
+
+
+static func _menu_title_size(menus: MenuBar, menu: int, style: StyleBox) -> Vector2:
+	var line: TextLine = TextLine.new()
+	var _shaped: bool = line.add_string(
+		menus.atr(menus.get_menu_title(menu)),
+		menus.get_theme_font("font"),
+		menus.get_theme_font_size("font_size"),
+		menus.language
+	)
+	return line.get_size() + style.get_minimum_size()
+
+
+## Scrolls [param control] until it draws [param item], and answers whether it asked anything to
+## move. A tab bar and a tree have a call for it; a list is scrolled by its own bar, by as little as
+## brings the whole entry in.
+static func _scroll_to(control: Control, item: Variant) -> bool:
+	var index: int = item if item is int else -1
+	var bar: TabBar = control as TabBar
+	if bar != null:
+		var before: int = bar.get_tab_offset()
+		bar.ensure_tab_visible(index)
+		return bar.get_tab_offset() != before
+	var tree: Tree = control as Tree
+	if tree != null:
+		var row: TreeItem = item
+		var was: float = tree.get_scroll().y
+		tree.scroll_to_item(row)
+		return tree.get_scroll().y != was
+	var list: ItemList = control as ItemList
+	if list == null:
+		return false
+	var rows: VScrollBar = list.get_v_scroll_bar()
+	var entry: Rect2 = list.get_item_rect(index, false)
+	var top: float = entry.position.y - list.get_theme_stylebox("panel").get_offset().y
+	var was_at: float = rows.value
+	if top < rows.value:
+		rows.value = top
+	elif top + entry.size.y > rows.value + rows.page:
+		rows.value = top + entry.size.y - rows.page
+	return rows.value != was_at

package/build/godot/addons/gdharness_runtime/runtime_items.gd.uid

@@ -0,0 +1 @@
+uid://mynpfgtjyipe

package/build/godot/addons/gdharness_runtime/runtime_paths.gd

@@ -254,12 +254,17 @@ static func can_read(holder: Variant, named: String) -> bool:
 ## reports an engine error for one of another type, so a step into a map typed by an enum read the
 ## right entry and left four errors in the game's log for each of the two walks, and the run was
 ## counted as unclean for a read.
+##
+## A step written in double quotes is the key inside them, so a key holding a colon is one step:
+## Alchemill keys its stock by namespaced ids, "stock:\"base:dew\"", and split at that colon the
+## step named a key "base" the map had never had.
 static func _key_in(map: Dictionary, named: String) -> Array:
-	var spellings: Array = [named, StringName(named)]
-	if named.is_valid_int():
-		spellings.append(int(named))
-	if named.is_valid_float():
-		spellings.append(float(named))
+	var word: String = key_written(named)
+	var spellings: Array = [word, StringName(word)]
+	if word.is_valid_int():
+		spellings.append(int(word))
+	if word.is_valid_float():
+		spellings.append(float(word))
 	var typed: int = map.get_typed_key_builtin() if map.is_typed_key() else TYPE_NIL
 	for key: Variant in spellings:
 		if typed != TYPE_NIL and typeof(key) != typed:
@@ -269,9 +274,35 @@ static func _key_in(map: Dictionary, named: String) -> Array:
 	return []
 
 
+## The key a step names: the words inside the quotes of one written in double quotes, read as JSON
+## reads a string so a quote inside is written \", and the step itself otherwise.
+static func key_written(named: String) -> String:
+	if named.length() < 2 or not named.begins_with('"') or not named.ends_with('"'):
+		return named
+	var reader: JSON = JSON.new()
+	if reader.parse(named) != OK or not reader.data is String:
+		return named
+	return reader.data
+
+
+## [param key] written as a step that names it: in double quotes when it holds what a bare step
+## cannot, a colon a path splits at, a bracket that reads as a call, a quote, or nothing at all.
+static func step_naming(key: Variant) -> String:
+	var text: String = str(key)
+	if not (key is String or key is StringName):
+		return text
+	if text.is_empty():
+		return JSON.stringify(text)
+	for character: String in [":", "(", ")", '"']:
+		if text.contains(character):
+			return JSON.stringify(text)
+	return text
+
+
 ## [param reaching] split into its steps at each colon, except one inside a call's brackets or a
-## quoted argument: `get_node("/root/Main"):name` is two steps, and split at every colon a quoted
-## argument holding one became a step that names nothing.
+## quoted argument or key: `get_node("/root/Main"):name` is two steps, and so is
+## `stock:"base:dew"`; split at every colon a quoted argument holding one became a step that names
+## nothing.
 static func steps_of(reaching: String) -> PackedStringArray:
 	var steps: PackedStringArray = []
 	var step: String = ""
@@ -569,17 +600,19 @@ static func nothing_there(holder: Variant, named: String, called_as: String) ->
 		var keys: Array = map.keys()
 		# A key reading as the step and still not reached is one of a type a step cannot spell, and
 		# saying the map has no key 3 while listing 3 among its keys contradicts itself.
+		var word: String = key_written(named)
 		for key: Variant in keys:
-			if str(key) == named:
+			if str(key) == word:
 				return (
 					"%s has a key that reads %s, but it is %s, which a path step cannot name"
 					% [called_as, named, type_string(typeof(key))]
 				)
 		# Eight of them, because a map keyed by something unexpected is told by the first few and a
-		# map of two hundred would bury the sentence saying which key was missing.
+		# map of two hundred would bury the sentence saying which key was missing. Each written as a
+		# step reaching it, so the list says how to name a key holding a colon.
 		var some: Array[String] = []
 		for key: Variant in keys.slice(0, 8):
-			some.append(str(key))
+			some.append(step_naming(key))
 		var rest: String = ""
 		if keys.size() > 8:
 			rest = " and %d more" % [keys.size() - 8]

package/build/godot/addons/gdharness_runtime/runtime_targets.gd

@@ -2,6 +2,7 @@ extends RefCounted
 
 ## Which control a click means when it names the control by the words on it rather than by path.
 
+const Items = preload("runtime_items.gd")
 const Queries = preload("runtime_queries.gd")
 const Read = preload("reading.gd")
 const Says = preload("runtime_says.gd")
@@ -24,7 +25,8 @@ const WHOLE: int = 1
 
 ## The control a click by [param wanted] words presses, found under [param root_path] in the tree
 ## [param root] heads, or the refusal saying why there is none or which of several:
-## {"path", "found"} or {"type", "message"}.
+## {"path", "found"} or {"type", "message"}, with `item` as well when the match is an item of a
+## control drawing a list, which [method Items.item_rect] places.
 ##
 ## Matched the way a find matches `says`, against a control's own words, and only among controls
 ## the player can see. A match inside a button presses the button, because the label is what says
@@ -57,6 +59,10 @@ static func control_saying(root: Node, root_path: String, wanted: String, which:
 	# that only says them as part of more stands in for.
 	var exact_out_of_reach: Array[Node] = []
 	var out_of_reach_as: Array[String] = []
+	# The item of a control drawing a list that matched, null for a control matched as a whole, and
+	# the point in the control a pointer would go to for it.
+	var items: Array = []
+	var aims: Array[Vector2] = []
 	var pending: Array[Node] = [reached["node"]]
 	while not pending.is_empty():
 		var node: Node = pending.pop_front()
@@ -66,6 +72,26 @@ static func control_saying(root: Node, root_path: String, wanted: String, which:
 				if _says_exactly(Words.said_by(node), wanted):
 					exact_out_of_reach.append(node)
 					out_of_reach_as.append("hidden")
+			elif Words.draws_a_list(node):
+				# Each item a match of its own, so the words of one tab are matched as a whole and the
+				# index picks between two items saying them as it does between two buttons.
+				var drawing: Control = node
+				for entry: Dictionary in Words.items_of(drawing):
+					var words: String = entry["says"]
+					if not Says.matches(words, wanted):
+						continue
+					var whole: bool = _says_exactly(words, wanted)
+					var drawn_at_now: Rect2 = Items.item_rect(drawing, entry["item"], wanted)
+					matched.append(drawing)
+					said.append(words)
+					exact.append(whole)
+					inside.append(not whole and _inside_a_word(words, wanted))
+					items.append(entry["item"])
+					# An item drawn nowhere yet, scrolled out of its list, is judged at the list's middle,
+					# which is where the click scrolls it towards.
+					aims.append(
+						drawing.size * 0.5 if drawn_at_now.size == Vector2.ZERO else drawn_at_now.get_center()
+					)
 			else:
 				var control: Control = node
 				var target: Control = _pressed_through(control)
@@ -78,6 +104,8 @@ static func control_saying(root: Node, root_path: String, wanted: String, which:
 					said.append(words)
 					exact.append(whole)
 					inside.append(buried)
+					items.append(null)
+					aims.append(target.size * 0.5)
 				elif (whole and not exact[at]) or (inside[at] and not buried):
 					said[at] = words
 					exact[at] = whole
@@ -93,13 +121,13 @@ static func control_saying(root: Node, root_path: String, wanted: String, which:
 	var outside: int = 0
 	var open: Array[int] = []
 	for index: int in matched.size():
-		if _off_screen(matched[index]):
+		if _off_screen(matched[index], aims[index]):
 			outside += 1
 			if exact[index]:
 				exact_out_of_reach.append(matched[index])
 				out_of_reach_as.append("outside what the screen shows")
 			continue
-		var over: Node = _cover_of(matched[index], drawn, areas)
+		var over: Node = _cover_of(matched[index], drawn, areas, aims[index])
 		if over == null:
 			open.append(index)
 		else:
@@ -125,12 +153,14 @@ static func control_saying(root: Node, root_path: String, wanted: String, which:
 	var lines: Array[String] = []
 	var wholes: Array[bool] = []
 	var insides: Array[bool] = []
+	var picked_items: Array = []
 	for index: int in open:
 		targets.append(matched[index])
 		ranks.append(_rank(matched[index], exact[index]))
 		lines.append(said[index])
 		wholes.append(exact[index])
 		insides.append(inside[index])
+		picked_items.append(items[index])
 
 	var under: String = "" if root_path == "/root" else " under %s" % root_path
 	if targets.is_empty():
@@ -257,7 +287,11 @@ static func control_saying(root: Node, root_path: String, wanted: String, which:
 		found["picked"] = "%s; %s" % [_described(1, ranks[0], wanted, under), others]
 	if covered > 0:
 		found["covered"] = covered
-	return {"path": str(targets[index].get_path()), "found": found}
+	var answer: Dictionary = {"path": str(targets[index].get_path()), "found": found}
+	if picked_items[index] != null:
+		answer["item"] = picked_items[index]
+		found["item"] = Items.item_named(targets[index], picked_items[index], lines[index])
+	return answer
 
 
 ## How good a match [param target] is for a click: a control the pointer can reach over one it
@@ -451,7 +485,7 @@ static func _pressed_through(control: Control) -> Control:
 ## What a pointer at [param target]'s centre would reach instead of it, drawn over it, or null.
 static func drawn_over(target: Control) -> Node:
 	var drawn: Array[Node] = _pointer_takers(target.get_tree().root)
-	return _cover_of(target, drawn, _areas_of(drawn))
+	return _cover_of(target, drawn, _areas_of(drawn), target.size * 0.5)
 
 
 ## Why [param node], which is not visible in the tree, is not, as a parenthesis to follow its path:
@@ -631,7 +665,8 @@ static func _areas_of(drawn: Array[Node]) -> Array[Rect2]:
 	return areas
 
 
-## What a pointer at [param target]'s centre reaches instead of it, or null when nothing does.
+## What a pointer at [param aim] in [param target], its centre or the middle of the item a click is
+## for, reaches instead of it, or null when nothing does.
 ##
 ## The engine's own order for which control takes the pointer: an embedded window over everything
 ## in the viewport that holds it, then the higher canvas layer, then the later in the tree. A
@@ -650,10 +685,10 @@ static func _areas_of(drawn: Array[Node]) -> Array[Rect2]:
 ## point is passed over before anything costlier is asked of it. A window's box is in the space of
 ## the viewport it is embedded in, which is not the target's when the target is in another window,
 ## so a window is judged by [method _window_over] instead.
-static func _cover_of(target: Control, drawn: Array[Node], areas: Array[Rect2]) -> Node:
+static func _cover_of(target: Control, drawn: Array[Node], areas: Array[Rect2], aim: Vector2) -> Node:
 	var viewport: Viewport = target.get_viewport()
 	var moves: Dictionary[ScrollContainer, Vector2] = _scrolls_for(target)
-	var point: Vector2 = _centre_of(target) + _moved_by(target, moves)
+	var point: Vector2 = target.get_global_transform_with_canvas() * aim + _moved_by(target, moves)
 	var layer: int = _layer_of(target)
 	for at: int in drawn.size():
 		var other: Node = drawn[at]
@@ -770,13 +805,14 @@ static func _where_it_lands(target: Control, point: Vector2) -> Dictionary[Scrol
 	return moves
 
 
-## Whether a click could not reach [param target] however it scrolled: its centre, where the click
-## would bring it, outside its viewport or the one showing that on the screen, or clipped away by a
-## container the click does not scroll. A drawer parked off the side of the screen, or anything
-## outside the viewport of a game with no window, was listed among the controls on screen.
-static func _off_screen(target: Control) -> bool:
+## Whether a click could not reach [param aim] in [param target] however it scrolled: the point,
+## where the click would bring it, outside its viewport or the one showing that on the screen, or
+## clipped away by a container the click does not scroll. A drawer parked off the side of the
+## screen, or anything outside the viewport of a game with no window, was listed among the controls
+## on screen.
+static func _off_screen(target: Control, aim: Vector2) -> bool:
 	var moves: Dictionary[ScrollContainer, Vector2] = _scrolls_for(target)
-	var point: Vector2 = _centre_of(target) + _moved_by(target, moves)
+	var point: Vector2 = target.get_global_transform_with_canvas() * aim + _moved_by(target, moves)
 	if _clipped_away(target, point, moves) or not target.get_viewport().get_visible_rect().has_point(point):
 		return true
 	var reached: Dictionary = Screen.reach(target.get_viewport(), point)

package/build/godot/addons/gdharness_runtime/runtime_words.gd

@@ -23,7 +23,7 @@ static func said_by(node: Node) -> String:
 	var label: Label = node as Label
 	if label != null:
 		return _label_says(label)
-	if _draws_a_list(node):
+	if draws_a_list(node):
 		return "\n".join(lines_said_by(node))
 	var own: String = _text_of(node)
 	# A control showing a picture rather than words is named for a player who cannot see it, and that
@@ -41,37 +41,54 @@ static func said_by(node: Node) -> String:
 ## every label on it and none of those, and a wait for a tab's title or a list item was never met.
 static func lines_said_by(node: Node) -> Array[String]:
 	var lines: Array[String] = []
+	if not draws_a_list(node):
+		_keep(_text_of(node), lines)
+		return lines
+	var tree: Tree = node as Tree
+	if tree != null and tree.column_titles_visible:
+		var titles: Array[String] = []
+		for column: int in tree.columns:
+			_keep(node.atr(tree.get_column_title(column)), titles)
+		_keep("  ".join(titles), lines)
+	for entry: Dictionary in items_of(node):
+		lines.append(str(entry["says"]))
+	return lines
+
+
+## Each item [param node] draws as one of a list, as {"says", "item"}: a tab, a menu title, a list
+## entry or a menu item by its index, and a tree row by its TreeItem. Empty for a node drawing none.
+## Held apart rather than joined, so a click on a tab's title presses that tab: the bar's middle is
+## whichever tab happens to sit there.
+static func items_of(node: Node) -> Array[Dictionary]:
+	var items: Array[Dictionary] = []
 	if node is TabBar:
 		var bar: TabBar = node
 		for tab: int in bar.tab_count:
 			if not bar.is_tab_hidden(tab):
-				_keep(node.atr(bar.get_tab_title(tab)), lines)
+				_keep_item(node.atr(bar.get_tab_title(tab)), tab, items)
 	elif node is MenuBar:
 		var menus: MenuBar = node
 		for menu: int in menus.get_menu_count():
 			if not menus.is_menu_hidden(menu):
-				_keep(node.atr(menus.get_menu_title(menu)), lines)
+				_keep_item(node.atr(menus.get_menu_title(menu)), menu, items)
 	elif node is ItemList:
 		var list: ItemList = node
 		for item: int in list.item_count:
-			_keep(_as_drawn(node, list.get_item_text(item), list.get_item_auto_translate_mode(item)), lines)
+			_keep_item(
+				_as_drawn(node, list.get_item_text(item), list.get_item_auto_translate_mode(item)),
+				item,
+				items
+			)
 	elif node is PopupMenu:
 		# A separator too, by its title: the popup draws a titled one as a heading over the items
 		# below it, and one without a title says nothing and is dropped as an empty line.
 		var menu: PopupMenu = node
 		for item: int in menu.item_count:
-			_keep(item_says(menu, item), lines)
+			_keep_item(item_says(menu, item), item, items)
 	elif node is Tree:
 		var tree: Tree = node
-		if tree.column_titles_visible:
-			var titles: Array[String] = []
-			for column: int in tree.columns:
-				_keep(node.atr(tree.get_column_title(column)), titles)
-			_keep("  ".join(titles), lines)
-		_tree_rows(tree, tree.get_root(), tree.hide_root, lines)
-	else:
-		_keep(_text_of(node), lines)
-	return lines
+		_tree_rows(tree, tree.get_root(), tree.hide_root, items)
+	return items
 
 
 ## What item [param index] of [param menu] shows: the translation where the item has one. A menu is
@@ -86,7 +103,9 @@ static func masked(field: LineEdit) -> String:
 	return field.secret_character.repeat(field.text.length())
 
 
-static func _draws_a_list(node: Node) -> bool:
+## Whether [param node] draws a list of items rather than holding words in a `text`; see
+## [method items_of].
+static func draws_a_list(node: Node) -> bool:
 	return node is TabBar or node is MenuBar or node is ItemList or node is PopupMenu or node is Tree
 
 
@@ -96,6 +115,12 @@ static func _keep(line: String, into: Array[String]) -> void:
 		into.append(trimmed)
 
 
+static func _keep_item(line: String, item: Variant, into: Array[Dictionary]) -> void:
+	var trimmed: String = line.strip_edges()
+	if not trimmed.is_empty():
+		into.append({"says": trimmed, "item": item})
+
+
 ## [param words] as [param node] draws them, which for a game with translations is the translation
 ## rather than the key it holds: a control set to `UI_HIRE` shows "Hire", and a wait for "Hire" was
 ## never met. [param mode] is an item's own setting, which the engine reads before the node's.
@@ -113,14 +138,14 @@ static func _as_drawn(
 ## The rows of a tree from [param item] down, a row being its columns' text side by side, and
 ## nothing under a collapsed row or a hidden one, since neither is drawn. A hidden root is only the
 ## place its children hang from.
-static func _tree_rows(tree: Tree, item: TreeItem, skip: bool, into: Array[String]) -> void:
+static func _tree_rows(tree: Tree, item: TreeItem, skip: bool, into: Array[Dictionary]) -> void:
 	if item == null or not item.visible:
 		return
 	if not skip:
 		var cells: Array[String] = []
 		for column: int in tree.columns:
-			_keep(_as_drawn(tree, item.get_text(column), item.get_auto_translate_mode(column)), cells)
-		_keep("  ".join(cells), into)
+			_keep(cell_says(tree, item, column), cells)
+		_keep_item("  ".join(cells), item, into)
 		if item.collapsed:
 			return
 	var child: TreeItem = item.get_first_child()
@@ -129,6 +154,11 @@ static func _tree_rows(tree: Tree, item: TreeItem, skip: bool, into: Array[Strin
 		child = child.get_next()
 
 
+## What [param column] of the row [param item] of [param tree] shows.
+static func cell_says(tree: Tree, item: TreeItem, column: int) -> String:
+	return _as_drawn(tree, item.get_text(column), item.get_auto_translate_mode(column))
+
+
 ## What a node with a `text` says, as it is drawn.
 static func _text_of(node: Node) -> String:
 	var label: Label = node as Label