Resizing hs help window

[Dakzhakz]

Pulling my hair out on this one...
I'm trying to resize the window for the help screen which I launch from the console.
The icon launches hs.doc.hsdocs.help() just fine, but I can't figure out how to automatically resize it.
Seems simple. Here's what I've tried:
I can run a function to grab the window name and then set it's size:

   function setHelpWin()
local	y = hs.window("Hammerspoon docs")
local qWin = hs.application("Hammerspoon"):allWindows()
	if qWin[2] == y then
		qWin[2]:setFrame({ h=620.0, y=25.0, w=750.0, x=0.0, __luaSkinType= "NSRect", })
	end
end

This works fine if the window has already appeared, but
if I trigger the help win like so:
function getHelp()
hs.doc.hsdocs.help()
setHelpWin()
end
the window hasn't been found yet, so nothing happens. I added a timer to delay resizing the newly-called help window:
function getHelp()
hs.doc.hsdocs.help()
hs.timer.doAfter(2, function() print("Howdy") end )
end
Here's the log result:
2023-04-07 13:41:57: -- Loading extension: doc
2023-04-07 13:41:57: -- Loading extension: timer

The timer function works fine by itself, but not when run inside the getHelp() function.
I also tried to just put the system to sleep briefly:

function test()
	print("pre-sleep")
	hs.timer.usleep(20000)
	print("done sleep")
end

...and the log result:

test()
2023-04-07 13:46:47: pre-sleep
2023-04-07 13:46:47: -- Loading extension: timer
2023-04-07 13:46:47: done sleep
Starting and stopping occur simultaneously. Or likely I'm missing something.
How can I launch the help window, wait for it to appear and then reset its size?

[Rhys-T]

To get Hammerspoon to use a particular size/position when it first creates the help window, you can pass it to hs.doc.hsdocs.browserFrame({...}). Alternately, you can call hs.doc.hsdocs.trackBrowserFrame(true) (or toggle on the window-looking 'track' button in the toolbar), then position the window by hand.

Note that the browserFrame setting is only checked when hs.doc.hsdocs creates the hs.webview that runs that window - in other words, the first time you open the help viewer after launching/reloading Hammerspoon. If you need to set it after the browser has been created, but while it's not necessarily currently open… I don't actually see an 'official' way to do that. However, if you're okay with accessing private/undocumented things, you should be able to get to the webview using hs.doc.hsdocs._browser and call its :frame({...}) method.

---

The reason hs.timer.doAfter(...) isn't working is probably because you're not storing the return value (the timer object) anywhere. That means it can be garbage-collected by Lua, which cancels the timer. Lua's garbage collection isn't deterministic, so in simple cases the timer might stay around long enough to go off, but a webview is complicated enough that it's much more likely to trigger the GC. More info here and here.

usleep expects its argument to be in microseconds, so if you pass 20000, that only comes out to 20 milliseconds, which is why it seems to return immediately. Even with a bigger value, though, the real problem is that usleep will block Hammerspoon's main thread, meaning that graphical parts of HS like the help window won't actually be able to appear or update during that time. You generally want to avoid usleep if you can - it basically tells Hammerspoon to hang for x microseconds.

[Dakzhakz]

Thanks so much for the reply Rhys-T. I'm still struggling with the timer and GC, but for the time being I may have beaten my immediate problem into submission by calling help using:
function getHelp() hs.doc.hsdocs.help() hs.doc.hsdocs._browser:frame({ some Rect table }) end

As for the timer question, even when I do a function with hs.timer.usleep(1000) bracketed by print statements all three lines have the same timestamp, so I was thinking that means the timer didn't really stop anything. Thanks for the refs to the timers discussion. Definitely have more playing to do.

[Rhys-T]

Yeah, to see the timestamp change, you'll need something more like:

print 'before'
hs.timer.usleep(2000000)
print 'after'
-- 2023-04-08 16:58:07: before
-- 2023-04-08 16:58:09: after

The lines will still appear all at once, though, when the code returns and HS's main event loop gets control again.

---

The combination of "Lua doesn't necessarily garbage-collect something right away" and "Hammerspoon's timers/watchers/event taps/etc. cause observable side effects when they get GC'd" can definitely make debugging… interesting - things will seem to be working, then just 'randomly' stop for no apparent reason. I think I have even more trouble with doAfter/doEvery, because their names don't really sound like they're 'creating something' that would need to be stored¹.

I ended up forcing the garbage collector to run at the very end of my init.lua, so that anything that's going to break breaks now, consistently, when I've just written the code, instead of later, intermittently, after I've forgotten that whatever I did isn't a builtin part of the system. It wouldn't have helped in this case, because the timer in question was created long after init.lua had finished running, but it's helped me catch a number of other bugs of this sort.

At the bottom of my ~/.hammerspoon/init.lua:

-- If I'm forgetting to save any watchers, timers, etc. into variables,
-- make sure they break as soon as possible.
-- I don't know if wrapping this in `doAfter` is really necessary or not -
-- I'm trying to make sure this runs after _everything_ the config does.
gcTimer = hs.timer.doAfter(0, function()
	gcTimer = nil
	collectgarbage()
	collectgarbage() -- second pass in case any objects were resurrected for finalizers the first time
end)

I've thought about making something that wraps all the finalizer functions to announce "Hey! The whatever that you created on line n of ~/.hammerspoon/something.lua just got GC'd - you might want to do something about that!", but that's going to be somewhat more involved, and I haven't really needed it yet.

Footnotes

1. And because their closest counterparts in JavaScript, setTimeout/setInterval, don't require you to store the result. ↩

[Dakzhakz]

I appreciate your input into this.