30.8 Finding All Frames

Function: frame-list ¶

This function returns a list of all the live frames, i.e., those that have not been deleted. It is analogous to buffer-list for buffers, and includes frames on all terminals. The list that you get is newly created, so modifying the list doesn’t have any effect on the internals of Emacs.

Function: visible-frame-list ¶

This function returns a list of just the currently visible frames. See Visibility of Frames. Frames on text terminals always count as visible, even though only the selected one is actually displayed.

Function: frame-list-z-order &optional display ¶

This function returns a list of Emacs’s frames, in Z (stacking) order (see Raising, Lowering and Restacking Frames). The optional argument display specifies which display to poll. display should be either a frame or a display name (a string). If omitted or nil, that stands for the selected frame’s display. It returns nil if display contains no Emacs frame.

Frames are listed from topmost (first) to bottommost (last). As a special case, if display is non-nil and specifies a live frame, it returns the child frames of that frame in Z (stacking) order.

This function is not meaningful on text terminals.

Function: next-frame &optional frame minibuf ¶

This function lets you cycle conveniently through all the frames on a specific terminal from an arbitrary starting point. It returns the frame following frame, in the list of all live frames, on frame’s terminal. The argument frame must specify a live frame and defaults to the selected frame. It never returns a frame whose no-other-frame parameter (see Frame Interaction Parameters) is non-nil.

The second argument, minibuf, says which frames to consider when deciding what the next frame should be:

nil

Consider all frames except minibuffer-only frames.

visible

Consider only visible frames.

0

Consider only visible or iconified frames.

a window

Consider only the frames using that particular window as their minibuffer window.

anything else

Consider all frames.

Function: previous-frame &optional frame minibuf ¶

Like next-frame, but cycles through all frames in the opposite direction.

See also next-window and previous-window, in Cyclic Ordering of Windows.

Some Lisp programs need to find one or more frames that satisfy a given criteria. The function filtered-frame-list is provided for this purpose.

Function: filtered-frame-list predicate ¶

This function returns the list of all the live frames which satisfy the specified predicate. The argument predicate must be a function of one argument, a frame to be tested against the filtering criteria, and should return non-nil if the frame satisfies the criteria.