redisplay-window

Arguments: window &optional box

This generic function is called by Common Graphics as needed in order to redisplay all or part of a window. Redisplay may happen either when part of the window becomes uncovered, or when the application has called invalidate to explicitly cause the window to be redrawn. An application draws the content of its windows by writing redisplay-window methods for the application's various window subclasses that it has defined.

Note that the application itself should never call redisplay-window. If the content of the window needs to change, the proper technique is to call invalidate to tell the operating system that the window needs to be redrawn, and then to redraw the content inside the redisplay-window method as usual. The operating system will then send the paint message (which causes Common Graphics to call redisplay-window) only when all other event-handling activity in the thread has exited. This design is a feature of the operating system to avoid redundant redisplays, which not only slow down the interface but also may cause annoying screen flashing. If the window needs to be redrawn immediately, the application should call update-window just after calling invalidate. That causes redisplay-window to be called at that time and informs the operating system that the window is now up-to-date so a later paint message is not necessary. To reduce flashing effects when a window is scrolled, resized, or animated, enable the double-buffered property of the window.

The box argument indicates the portion of the window that needs to be redrawn. In the simplest case, a redisplay-window method can just ignore this box and redraw everything on each call; in this case the OS will clip at the box boundaries so that nothing is actually drawn outside the box. But the method will likely be more efficient if it takes note of the box and does not even attempt to draw any objects that are known not to intersect with the box. The box argument is optional for backward compatibility reasons only; in fact, a box is always passed, and so methods do not need to check that a box has been passed.

Certain classes of windows do not need to be given redisplay-window methods. In particular, a bitmap-pane (auto-instantiated with a bitmap-window) already has a redisplay-window method, which simply copies the window's backing store to the visible window. (But remember that the backing store memory bitmap can consume a lot of virtual memory, so it's usually best to use a "plain" window with a custom redisplay-window method unless the extra redisplay speed of a bitmap-pane is really needed.) And a text-edit-pane is redrawn by the operating system, since it is actually a control supplied by the OS.

An application may override the default method of this and several other generic functions in order to implement a custom scrolling scheme that scrolls by logical picture objects rather than by pixels. See the source code of the example entitled Scrolling by arbitrary objects rather than pixels on the Examples tab of the Navigator dialog for a complete example. More on this point and a list of the relevant generic functions can be found on the horizontal-scroll-bar and vertical-scroll-bar pages.

See cg-drawing.htm for a discussion of the uses of redisplay-window, invalidate, and update-window.

Copyright (c) 1998-2016, Franz Inc. Oakland, CA., USA. All rights reserved.
This page was not revised from the 8.1 page.
Created 2010.1.21.