[STUMP] window/frame model

[Eric Abrahamsen]

I've noticed for a while that I don't really understand Stumpwm's model
of splitting windows among frames. I've tried to write a few user
functions that, for instance, send keypresses to a different window
without shifting focus to that window, and that's made it even clearer
to me that I'm not really getting it.

My understanding so far:

One frame is easy: all the windows belong to that frame, and they're
ordered so that `next' and `prev' will cycle through them.

Then you split frames. The original frame keeps the top window and the
rest of the windows, while the "second" window (that would have been
found with `next') goes to the new frame. The new frame *only* contains
this second window, so that `next-in-frame' in the new frame tells you
"No other window". So far so good.

Further frame-splitting follows the same rule, so that with each split
you're popping the next "second" window and placing it alone in the new
frame. Unless the frame you're splitting only has one window to begin
with, in which case the window for the new frame is taken from a frame
that still has un-visible windows.

Things get really confusing when I start using the `pull-hidden-*'
commands.

I understand that I can pull a window from one frame window list into
another using the `pull 0-9' commands. But how does `pull-hidden-*'
decide where to get its frames from? Is it a global list of windows in
the current group? I generally use full-screened frames on two heads,
but when I need to get a little complicated and split a single head, I
find myself fighting to get the right windows in the right frames.
Possibly this is because I use `pull-hidden-other' too much.

Anyway, can anyone enlighten me as to exactly how Stumpwm decides to
pull windows? Would it be nice to have a command that shows the
window-list for the current frame?

In a semi-related question, is anyone doing anything like the following,
and/or could anyone help me fix this?

--8<---------------cut here---------------start------------->8---
(defun send-key-other-window (dir)
  ;; `last' of `group-frames' doesn't actually return the most
  ;; recently focused frame, just the last in a list apparently
  ;; starting at top left. How do we sort according to most recently
  ;; focused?
  (send-fake-key
   (frame-window (car (last (group-frames (current-group)))))
   (kbd dir)))

(defcommand scroll-other-window-down () ()
            "Scroll other window down."
            (send-key-other-window "Next"))
(define-key *root-map* (kbd "d") "scroll-other-window-down")

(defcommand scroll-other-window-up () ()
            "Scroll other window down."
            (send-key-other-window "Prior"))
(define-key *root-map* (kbd "u") "scroll-other-window-up")
--8<---------------cut here---------------end--------------->8---

Thanks in advance! If anyone can provide me with a solid understanding
of how all this works, I'd be happy to write it up as a node in the
Stumpwm Info file.

Eric