find-window

Arguments: window-name &optional (parent-or-owner (screen *system*)) &key owned-p

Returns the window whose name is name and whose parent or owner is parent-or-owner (which can be nil if there is no such window). The default value of parent-or-owner is the screen, and so this argument need not be passed in order to find any top-level window (since the parent of a top-level window is always the screen). The screen is the value returned by (screen *system*). See screen and *system*.

window-name should be the symbol that was passed as the value of the name initarg to make-window (or passed to (setf name) to rename the window later). The parent-or-owner should either be the window or screen that was passed as the value of the owner argument to make-window, or alternately the screen in the case of an owned top-level window (whose owner is another window but whose parent is the screen).

If owned-p is nil (the default), then only child windows of parent-or-owner are searched. If true, then only non-child owned windows of parent-or-owner are searched. A true owned-p argument is useful only when parent-or-owner is a top-level window or the screen, because child windows cannot have non-child owned windows. (A non-child owned window is created by passing the child-p initarg of make-window as nil, along with a top-level window for the owner argument.)

A more general function for finding objects from their names and ancestor objects is find-named-object.

A Warning About Form Windows in Projects

It is dangerous to use find-window to find a top-level window that is designed interactively as a form window in a project in the IDE. (Though if the window is a child window at run time and you pass the optional parent-or-owner argument, then there is no problem.)

The reason is that a form window in a project and its running window have the same name, and find-window will return whichever one it happens to find first. So when running a project in the IDE, find-window could return the form window, and if your code modifies that window then it could modify the form window itself and leave the project confused.

If your project uses the default on-initialization function, and therefore does not have an explicit call to make the main window, then it is best to use find-application-window rather than find-window to get a handle on the main window. In other cases it is usually best to save the window that's returned when calling the function that creates the window. (You can use find-application-window with other windows as well, though you may need to set things up with a call to add-application-window when creating the window.)

Compatibility note

Prior to version 8.1, there was no owned-p argument and both child windows and non-child owned windows were always both searched. This incompatible change was made for efficiency reasons. If an application calls find-window to find a non-child owned window of a top-level window, it should now pass the new owned-p argument as true.

Copyright (c) 1998-2022, Franz Inc. Lafayette, CA., USA. All rights reserved.
This page was not revised from the 10.0 page.
Created 2019.8.20.