gdharness 1.1.21 → 1.1.23

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

@@ -5,6 +5,7 @@ extends RefCounted
 const Queries = preload("runtime_queries.gd")
 const Read = preload("reading.gd")
 const Says = preload("runtime_says.gd")
+const Screen = preload("runtime_screen.gd")
 const Values = preload("runtime_values.gd")
 const Words = preload("runtime_words.gd")
 
@@ -68,8 +69,12 @@ static func control_saying(root: Node, root_path: String, wanted: String, which:
 	var areas: Array[Rect2] = _areas_of(drawn)
 	var covered: int = 0
 	var cover: Node = null
+	var outside: int = 0
 	var open: Array[int] = []
 	for index: int in matched.size():
+		if _off_screen(matched[index]):
+			outside += 1
+			continue
 		var over: Node = _cover_of(matched[index], drawn, areas)
 		if over == null:
 			open.append(index)
@@ -98,8 +103,8 @@ static func control_saying(root: Node, root_path: String, wanted: String, which:
 			"type": "error",
 			"message":
 			(
-				'no control on screen%s says "%s", so nothing was clicked%s%s'
-				% [under, wanted, _hidden_note(hidden), _covered_note(covered, cover)]
+				'no control on screen%s says "%s", so nothing was clicked%s%s%s'
+				% [under, wanted, _hidden_note(hidden), _outside_note(outside), _covered_note(covered, cover)]
 			)
 		}
 	var best: int = ranks.count(ranks[0])
@@ -137,10 +142,13 @@ static func control_saying(root: Node, root_path: String, wanted: String, which:
 	return {"path": str(targets[index].get_path()), "found": found}
 
 
-## How good a match [param target] is for a click: a button over what cannot be pressed, and then
-## the whole of its words over a part of them.
+## How good a match [param target] is for a click: an enabled button over anything else, and then
+## the whole of its words over a part of them. A disabled button ranks with what is not a button,
+## since a click on it presses nothing: counted as a button, one tied with an enabled button saying
+## the same words and the click was refused as not clear.
 static func _rank(target: Control, whole: bool) -> int:
-	return (2 if target is BaseButton else 0) + (1 if whole else 0)
+	var button: BaseButton = target as BaseButton
+	return (2 if button != null and not button.disabled else 0) + (1 if whole else 0)
 
 
 ## Whether one of [param wanted]'s alternatives is the whole of [param said], or the whole of one of
@@ -178,14 +186,17 @@ static func _described(count: int, rank: int, wanted: String, under: String) ->
 	return "%d %ss on screen%s say %s" % [count, what, under, how]
 
 
-## Why the matches below [param rank] were passed over, said of one of them when [param one].
+## Why the matches below [param rank] were passed over, said of one of them when [param one]. As
+## what the code knows, which is whether a control is an enabled button: a card taking clicks in its
+## own `gui_input` is not one, and calling it something that cannot be pressed was a guess.
 static func _passed_over(rank: int, one: bool) -> String:
 	var says: String = "says" if one else "say"
+	var is_not: String = "is not an enabled button" if one else "are not enabled buttons"
 	match rank:
 		3:
-			return "cannot be pressed or %s it as part of more" % says
+			return "%s or %s it as part of more" % [is_not, says]
 		2:
-			return "cannot be pressed"
+			return is_not
 		_:
 			return "%s it as part of more" % says
 
@@ -197,6 +208,14 @@ static func _hidden_note(hidden: int) -> String:
 	return "; %d hidden control%s" % [hidden, " says it" if hidden == 1 else "s say it"]
 
 
+## What to add to a refusal that found nothing on screen, when words matched controls a click cannot
+## reach: off the viewport, or clipped away by a container it does not scroll.
+static func _outside_note(outside: int) -> String:
+	if outside == 0:
+		return ""
+	return "; %d control%s it outside what the screen shows" % [outside, " says" if outside == 1 else "s say"]
+
+
 ## What to add to a refusal that found nothing on screen, when the controls saying it are covered.
 static func _covered_note(covered: int, cover: Node) -> String:
 	if covered == 0:
@@ -271,26 +290,22 @@ static func _areas_of(drawn: Array[Node]) -> Array[Rect2]:
 ## page covered was picked over the ones in view, scrolled up under the page and pressed there.
 ##
 ## [param areas] holds the box around each of [param drawn], so everything whose box misses the
-## point is passed over before anything costlier is asked of it.
+## 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:
 	var viewport: Viewport = target.get_viewport()
-	var point: Vector2 = target.get_global_transform_with_canvas() * (target.size * 0.5)
-	if _clipped_away(target, point):
-		point = _where_it_lands(target, point)
+	var point: Vector2 = _where_it_is_clicked(target)
 	var layer: int = _layer_of(target)
 	for at: int in drawn.size():
-		if not areas[at].has_point(point):
-			continue
 		var other: Node = drawn[at]
 		var window: Window = other as Window
 		if window != null:
-			if (
-				window.get_parent() != null
-				and window.get_parent().get_viewport() == viewport
-				and not window.is_ancestor_of(target)
-			):
+			if _window_over(target, point, window):
 				return window
 			continue
+		if not areas[at].has_point(point):
+			continue
 		var control: Control = other
 		if control == target or control.is_ancestor_of(target) or target.is_ancestor_of(control):
 			continue
@@ -304,6 +319,42 @@ static func _cover_of(target: Control, drawn: Array[Node], areas: Array[Rect2])
 	return null
 
 
+## Where a click at [param target] lands in its viewport: its centre, or where scrolling will bring
+## the centre when a ScrollContainer holding it clips it away, as the click scrolls it first.
+static func _where_it_is_clicked(target: Control) -> Vector2:
+	var point: Vector2 = target.get_global_transform_with_canvas() * (target.size * 0.5)
+	if _clipped_away(target, point):
+		point = _where_it_lands(target, point)
+	return point
+
+
+## Whether the embedded [param window] is drawn over [param point], [param target]'s centre in its
+## own viewport, with that point carried out to the viewport the window is embedded in.
+##
+## Over it when the window holds the point there and is not the window the target is in, and, when
+## the target is in another window embedded in the same place, when it is stacked above that one:
+## the embedder's list of windows runs from the bottom up, measured on 4.7.2. Judged only in the
+## target's own viewport, a confirmation over a settings dialog did not cover the dialog's OK, and
+## a click by words tied it with the confirmation's own.
+static func _window_over(target: Control, point: Vector2, window: Window) -> bool:
+	if window.get_parent() == null or window.is_ancestor_of(target):
+		return false
+	var host: Viewport = window.get_parent().get_viewport()
+	for step: Dictionary in Screen.steps_out(target.get_viewport(), point):
+		if step["viewport"] != host:
+			continue
+		var there: Vector2 = step["point"]
+		if not Rect2(window.position, window.size).has_point(there):
+			return false
+		var through: Variant = step["through"]
+		if not through is Window:
+			return true
+		var own: Window = through
+		var stacked: Array[Window] = host.get_embedded_subwindows()
+		return stacked.find(window) > stacked.find(own)
+	return false
+
+
 ## Whether [param control] holds [param point], given in its viewport's coordinates.
 static func _holds(control: Control, point: Vector2) -> bool:
 	var placed: Transform2D = control.get_global_transform_with_canvas()
@@ -316,17 +367,18 @@ static func _holds(control: Control, point: Vector2) -> bool:
 
 
 ## Where [param target]'s centre, now at [param point], will be once the click has scrolled it into
-## view: moved as little as puts the whole of it inside each container clipping it, innermost first,
-## which is how a scroll container brings a control into view. A target larger than a container is
-## centred in it.
+## view: moved as little as puts the whole of it inside each ScrollContainer holding it, innermost
+## first, which is how one brings a control into view. A target larger than a container is centred
+## in it. Only a ScrollContainer, because that is all a click scrolls: another container clipping
+## what it holds, a collapsed section for one, leaves the target where it is.
 static func _where_it_lands(target: Control, point: Vector2) -> Vector2:
 	var drawn: Transform2D = target.get_global_transform_with_canvas()
 	var half: Vector2 = (drawn * Rect2(Vector2.ZERO, target.size)).size * 0.5
 	var landed: Vector2 = point
 	var walk: Node = target.get_parent()
 	while walk != null:
-		var holder: Control = walk as Control
-		if holder != null and holder.clip_contents:
+		var holder: ScrollContainer = walk as ScrollContainer
+		if holder != null:
 			var shown: Rect2 = holder.get_global_transform_with_canvas() * Rect2(Vector2.ZERO, holder.size)
 			var low: Vector2 = shown.position + half
 			var high: Vector2 = shown.end - half
@@ -338,6 +390,20 @@ static func _where_it_lands(target: Control, point: Vector2) -> Vector2:
 	return landed
 
 
+## 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 64 by 64 viewport of a game with no window, was listed among the controls on screen.
+static func _off_screen(target: Control) -> bool:
+	var point: Vector2 = _where_it_is_clicked(target)
+	if _clipped_away(target, point) or not target.get_viewport().get_visible_rect().has_point(point):
+		return true
+	var reached: Dictionary = Screen.reach(target.get_viewport(), point)
+	var viewport: Viewport = reached["viewport"]
+	var there: Vector2 = reached["point"]
+	return not viewport.get_visible_rect().has_point(there)
+
+
 ## Whether a container clipping what it holds cuts [param point] off from [param control].
 static func _clipped_away(control: Control, point: Vector2) -> bool:
 	var walk: Node = control.get_parent()

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

@@ -0,0 +1,351 @@
+extends RefCounted
+
+## What reaches the running game the way a keyboard reaches it: text typed into the field that has
+## the focus, and an item chosen out of a menu the way a keyboard chooses one.
+
+const Menus = preload("runtime_menus.gd")
+const Read = preload("reading.gd")
+const Values = preload("runtime_values.gd")
+const Words = preload("runtime_words.gd")
+
+## The two characters a field reads as keys rather than as text.
+const NEWLINE: int = 10
+const TAB: int = 9
+
+var _host: Node
+
+
+func _init(host: Node) -> void:
+	_host = host
+
+
+## Types [param text] wherever the focus is, one key event per character.
+##
+## A key on its own cannot do this and should not try: which character a key produces is the
+## keyboard layout's business, and shift over a digit is an exclamation mark on one layout and
+## something else on the next. Given the character instead there is nothing to guess, so a field
+## can be filled with anything a player could type, this project's own two typefaces included.
+##
+## A newline and a tab are the two characters a field reads as keys rather than as text, so they
+## are sent as those keys and carry no character of their own: typing a name and submitting it is
+## one call rather than two.
+##
+## Pushed into the viewport for the reason a click is, and it matters more here: the focus is what
+## decides where a character lands, so a caller that clicked a field and then typed would otherwise
+## have both waiting in the same queue with nothing said about the order.
+##
+## [code]replace[/code] is for a field that already says something, which is most of them: typing
+## lands at the caret, so a spin box reading 2.1 typed "0.3" at reads 2.10.3 and parses back to
+## 2.1, and the answer said four characters had gone in. What the field holds afterwards is read
+## back now rather than echoed from the request, so a call that typed somewhere unhelpful says so.
+func inject_text(params: Dictionary) -> Dictionary:
+	var text: String = str(params.get("text", ""))
+	var over: bool = Read.as_bool(params.get("replace", false))
+	if text.is_empty() and not over:
+		return {"type": "error", "message": "text needs something to type, or replace to empty a field"}
+
+	var viewport: Viewport = _host.get_tree().root
+	var focused: Control = focus_owner(viewport)
+	var shut: String = _shut_to_typing(focused)
+	if not shut.is_empty():
+		return {"type": "error", "message": shut}
+
+	# Where it goes, which is the one thing a caller cannot see from here, read before the keys: a
+	# name field that swaps its panel out on Enter has left the tree by the time the keys are done,
+	# and a node out of the tree has no path to give. Null is a game reading keys for itself with
+	# nothing focused, which is a real thing to be typing at.
+	var into: Variant = null
+	if focused != null:
+		into = str(focused.get_path())
+
+	var replaced: bool = over and _select_everything(focused)
+	# Emptying a field is a real thing to ask for and the one shape of filling one in that types no
+	# characters. The selection is standing, so the key a player presses over one is what clears it.
+	if replaced and text.is_empty():
+		_press(viewport, _held_down(KEY_DELETE))
+	for index: int in text.length():
+		_press(viewport, _typed(text.unicode_at(index)))
+
+	var holds: Variant = null
+	if is_instance_valid(focused):
+		holds = _what_it_holds(focused)
+	return {
+		"type": "input_injected",
+		"input_type": "text",
+		"text": text,
+		"characters": text.length(),
+		"into": into,
+		"replaced": replaced,
+		"holds": holds,
+	}
+
+
+## The control keys pushed into [param viewport] go to: its focus, or the focus of the window
+## embedded in it that has the focus, followed down.
+##
+## The game's own viewport keeps the control it had focused when a dialog took the focus, and keys
+## pushed at it go on to the dialog, measured on 4.7.2: a root field was reported as typed into and
+## stayed empty while the characters landed in the dialog's field.
+static func focus_owner(viewport: Viewport) -> Control:
+	var at: Viewport = viewport
+	var deeper: bool = true
+	while deeper:
+		deeper = false
+		for window: Window in at.get_embedded_subwindows():
+			if window.has_focus():
+				at = window
+				deeper = true
+				break
+	return at.gui_get_focus_owner()
+
+
+## Selects everything in [param focused] so the next character typed writes over it, and answers
+## whether there was a field to select in.
+##
+## Through the control rather than through a Ctrl+A, which is the one part of filling a field that
+## cannot honestly be sent as a key: the shortcut is Cmd+A on macOS and is an [InputMap] action a
+## project is free to unbind, and a caller asking for the field to be replaced would then be typing
+## on the end of what was there. The replacement itself is still every character a player types.
+static func _select_everything(focused: Control) -> bool:
+	var field: LineEdit = focused as LineEdit
+	if field != null:
+		field.select_all()
+		return true
+	var box: TextEdit = focused as TextEdit
+	if box == null:
+		return false
+	box.select_all()
+	return true
+
+
+## What the field says now, or null where the focus is not a field at all.
+##
+## A spin box rewrites its own text out of the number it parsed, so this is the only thing that
+## says whether what was typed became what the field means. A secret field answers with its mask,
+## which still says how many characters it took.
+static func _what_it_holds(focused: Control) -> Variant:
+	var field: LineEdit = focused as LineEdit
+	if field != null:
+		return Words.masked(field) if field.secret else field.text
+	var box: TextEdit = focused as TextEdit
+	if box == null:
+		return null
+	return box.text
+
+
+## Why nothing typed would reach [param focused], or "" when it would.
+##
+## A field that is not editable takes no characters however it is reached, and a click does not
+## open a read-only [LineEdit] for editing, measured on 4.7.2, so sending the caller to click it
+## would not help.
+##
+## Having the focus is not the same as being edited. Since Godot 4.4 a field is focused and shut
+## until something opens it, which is what a click does and what submitting undoes: press Enter in
+## a box and it keeps the focus and drops every key that arrives afterwards. Typing into one
+## answered that the characters had gone in and put nothing anywhere, which is the shape a refusal
+## exists to prevent. Measured on a spin box in a real game: `has_focus` true, `is_editing` false,
+## three characters reported and the field unchanged. Only a [LineEdit] is refused for that: it is
+## the one control the engine will say it about, since [TextEdit] has no editing state of its own.
+## A game reading keys for itself is typed at with nothing focused at all, and that is not this
+## tool's business to judge.
+static func _shut_to_typing(focused: Control) -> String:
+	var field: LineEdit = focused as LineEdit
+	var box: TextEdit = focused as TextEdit
+	if (field != null and not field.editable) or (box != null and not box.editable):
+		return "%s has the focus and is read-only, so nothing typed lands in it." % focused.get_path()
+	if field == null or field.is_editing():
+		return ""
+	return (
+		"%s has the focus and is not being edited, so nothing typed lands in it. Click it first."
+		% focused.get_path()
+	)
+
+
+## A whole key press into [param viewport]: down, then the release, so nothing is left held down
+## behind the caller.
+static func _press(viewport: Viewport, down: InputEventKey) -> void:
+	viewport.push_input(down)
+	var up: InputEventKey = down.duplicate()
+	up.pressed = false
+	viewport.push_input(up)
+
+
+## A key held down by its keycode, for the ones that stand for an edit rather than a character.
+static func _held_down(code: Key) -> InputEventKey:
+	var event: InputEventKey = InputEventKey.new()
+	event.pressed = true
+	event.keycode = code
+	event.physical_keycode = code
+	event.key_label = code
+	return event
+
+
+## The key press that produces [param glyph], as a keyboard would send it.
+static func _typed(glyph: int) -> InputEventKey:
+	var event: InputEventKey = InputEventKey.new()
+	event.pressed = true
+	if glyph == NEWLINE:
+		event.keycode = KEY_ENTER
+	elif glyph == TAB:
+		event.keycode = KEY_TAB
+	else:
+		var capital: int = String.chr(glyph).to_upper().unicode_at(0)
+		event.keycode = capital as Key
+		event.shift_pressed = capital != glyph
+		event.unicode = glyph
+	event.physical_keycode = event.keycode
+	event.key_label = event.keycode
+	return event
+
+
+## Chooses an item out of a menu, by what it says or by where it is in the list.
+##
+## A menu's items are drawn rather than built, so there is no node under the pointer to aim at and
+## no rectangle to ask for: [PopupMenu] exposes their text, their ids and which one has the focus,
+## and nothing about where any of them is. So a click cannot reach one, and a whole click on the
+## [OptionButton] in front of it opens the menu on the press and closes it again on the release.
+## Every language picker, every filter and every dropdown in a game was unreachable, and the way
+## past it was to call `select` and emit `item_selected`, which sets a number and runs none of the
+## engine's own path.
+##
+## Chosen the way a keyboard chooses: the item takes the focus and then `ui_accept` presses it,
+## which is the same route through [PopupMenu] a pointer takes and which needs no geometry, so it
+## works in a game with no window as well.
+##
+## [param path] may be the menu or the button in front of it. Naming the button is what a caller
+## has, since the menu is an internal child with a generated name that changes between runs.
+func choose(params: Dictionary) -> Dictionary:
+	var node_path: String = str(params.get("path", ""))
+	if node_path.is_empty():
+		return {"type": "error", "message": "Node path required"}
+	var standing: Dictionary = Values.node_at(_host.get_tree().root, node_path)
+	if standing.has("message"):
+		return standing
+	var node: Node = standing["node"]
+
+	var menu: PopupMenu = Menus.menu_of(node)
+	if menu == null:
+		return {
+			"type": "error",
+			"message":
+			(
+				"%s is a %s, which is neither a PopupMenu nor something holding one"
+				% [node_path, node.get_class()]
+			)
+		}
+
+	if not params.has("index") and str(params.get("text", "")).is_empty():
+		return {
+			"type": "error",
+			"message":
+			(
+				"%s needs the item named, by text or index. It holds: %s"
+				% [node_path, ", ".join(Menus.items_of(menu))]
+			)
+		}
+
+	# A button a player cannot use is refused, as a click refuses one: the engine opens the menu of a
+	# disabled or hidden OptionButton when asked to, measured on 4.7.2, and the pick then changed a
+	# selection no player could have changed.
+	var holder: BaseButton = node as BaseButton
+	if holder != null and holder.disabled:
+		return {"type": "error", "message": "%s is disabled, so its menu cannot be opened" % node_path}
+	if holder != null and not holder.is_visible_in_tree():
+		return {"type": "error", "message": "%s is not visible, so its menu cannot be opened" % node_path}
+
+	# Shown first, because a menu nobody has opened has no focus to move and the press would go to
+	# whatever is behind it, and before the item is looked for, because opening is when a game fills
+	# a menu: one rebuilt on about_to_popup was read as it stood before, measured on 4.7.2, and the
+	# index found in the old items chose another item of the new ones. An OptionButton opens its own;
+	# a bare PopupMenu is popped where it already sits, which leaves a menu already open where it is.
+	var opened: bool = Menus.open_the_menu(node, menu)
+	await _host.get_tree().process_frame
+
+	var index: int = Menus.wanted_item(menu, params)
+	var refused: String = _not_a_choice(node_path, menu, index)
+	if not refused.is_empty():
+		if opened and is_instance_valid(menu):
+			menu.hide()
+		return {"type": "error", "message": refused}
+
+	# Read before the press, because the press can take the menu away: a game that rebuilds its
+	# settings screen on item_selected frees the button and its menu inside the pick, and reading
+	# the item afterwards was an engine error in the game's log and an empty answer to a pick that
+	# had taken.
+	var answer: Dictionary = {
+		"type": "chosen",
+		"path": node_path,
+		"index": index,
+		"text": Words.item_says(menu, index),
+		"id": menu.get_item_id(index),
+		"opened": opened,
+		"menu": str(menu.get_path()),
+	}
+	# Heard rather than assumed: an item pressed is the only evidence the menu took it.
+	var fired: Array[int] = []
+	var hear: Callable = func(at: int) -> void: fired.append(at)
+	var _listening: int = menu.index_pressed.connect(hear)
+	menu.scroll_to_item(index)
+	menu.set_focused_item(index)
+	# Through Input rather than pushed at the menu, which is how a keyboard reaches an open one: a
+	# popup is a Window, it takes the focus when it opens, and Input delivers to whichever window
+	# has it. Pushed straight at the menu the event arrived and nothing happened.
+	Input.parse_input_event(_accept(true))
+	await _host.get_tree().process_frame
+	Input.parse_input_event(_accept(false))
+	await _host.get_tree().process_frame
+	if is_instance_valid(menu) and menu.index_pressed.is_connected(hear):
+		menu.index_pressed.disconnect(hear)
+
+	if not fired.has(index):
+		if opened and is_instance_valid(menu) and menu.visible:
+			menu.hide()
+		return {
+			"type": "error",
+			"message":
+			(
+				(
+					"%s item %d, %s, had the focus and ui_accept was pressed, and the menu did not take it,"
+					+ " so nothing was chosen"
+				)
+				% [node_path, index, answer["text"]]
+			)
+		}
+
+	answer["control_afterwards"] = Values.afterwards(node)
+	# What the button in front of the menu reads now: a menu item that fired changes the thing
+	# holding it. A button the pick took away has nothing to read, and that it went is the answer.
+	if answer["control_afterwards"] == "in_tree" and node is OptionButton:
+		var chooser: OptionButton = node
+		answer["selected"] = chooser.get_selected()
+		answer["shows"] = Words.said_by(chooser)
+	return answer
+
+
+## Why item [param index] of [param menu] is not something to choose, or "" when it is.
+static func _not_a_choice(node_path: String, menu: PopupMenu, index: int) -> String:
+	if index < 0:
+		return "%s has no such item. It holds: %s" % [node_path, ", ".join(Menus.items_of(menu))]
+	if menu.is_item_separator(index):
+		var heading: String = Words.item_says(menu, index).strip_edges()
+		if heading.is_empty():
+			return "%s item %d is a separator, not a choice" % [node_path, index]
+		return (
+			"%s item %d, %s, is a separator heading the items below it, not a choice"
+			% [node_path, index, heading]
+		)
+	if menu.is_item_disabled(index):
+		return "%s item %d, %s, is disabled" % [node_path, index, Words.item_says(menu, index)]
+	return ""
+
+
+## The press or release of `ui_accept`, which is what [PopupMenu] takes its focused item on.
+##
+## The action rather than the Enter key it is usually bound to: a project is free to bind it to
+## something else, and with Enter taken off it the key did nothing, measured on 4.7.2, while the
+## action chose the item.
+static func _accept(pressed: bool) -> InputEventAction:
+	var event: InputEventAction = InputEventAction.new()
+	event.action = "ui_accept"
+	event.pressed = pressed
+	return event

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

@@ -0,0 +1 @@
+uid://3a2opgsbkmu