frame-with-single-child

A non-instantiable superclass of the instantiable window classes non-refreshing-window, bitmap-window, and text-edit-window. When a frame-with-single-child subclass is instantiated by calling make-window, the frame window that is created directly serves only as a frame (consisting of a title-bar and/or a border), and a second window is created automatically as child pane that serves as the interior drawing area.

A frame-with-single-child window is most useful when a toolbar or status-bar is to be added to the window, especially if the window has scrollbars. The reason is that these auxilliary windows are created as siblings of the automatically-added child pane, and the scrollbars (if any) are created on the child pane rather than on the frame. This arrangement allows the application to draw in the entire page-box of the child pane without any of the drawing being covered by the toolbar or status-bar, and allows the drawing to scroll without scrolling the toolbar or status-bar along with it.

This double-window arrangement is also needed for a text-edit-window, because a text-edit-pane is actually a control internally and cannot have a frame itself. (For other window classes, frame attributes may be added even when the class excludes them by default for typical usage as a frameless pane.)

A default-pane-class method that specializes on the frame-with-single-child class determines what class is instantiated to make the child pane. When subclassing a frame-with-single-child class for use in an application, it is typically necessary to subclass both the frame class and the pane class, and then to define a trivial default-pane-class method to associate the two with each other. Several of the examples in the Examples tab of the Navigator dialog, including the "Custom Windows" example at the top of the list, illustrate this common technique.

The function frame-child returns the child pane that was automatically added to a frame-with-single-child window. The function owner, as usual, will return the frame window from the pane.

Note that any drawing that is done must be done on the pane window rather than on the frame window, because the frame's interior is covered by the pane. Until version 6.0, Common Graphics would automatically divert drawing to the pane window, but this is no longer done because it was deemed more confusing than useful. Various other functions must be called on the pane itself when it is the true object of interest, even though the two windows are conceptually a single window.

The frame-child pane window resizes itself as needed whenever the frame window (or its interior) is resized by always setting its right-attachment property to :right and its bottom-attachment to :bottom. Applications may use this techique for custom child panes that do not use the built-in frame-with-single-child facility. This may be necessary, for example, if multiple child panes are desired or a single child pane is desired that does not fill the frame window's interior.

A diagram of window and widget classes is shown in Widget and window classes in cgide.htm.

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