2
--------------------------------------------------------------------------
4
The process of layout involves setting the size and position of components.
5
All plot components must define two methods: layout() and get_preferred_size().
6
Frames and Containers are used to actually specify and construct the layout.
8
Frames are the top-most Enable component that contain all other Chaco components.
9
They cannot (or at least *should* not) be nested within on another. They define
10
specific layout formats with hard-coded names (called "slots"), and different
11
subclasses of Frames have different fixed layouts. For instance, the SimplePlotFrame
12
consists of a single slot, named "center", that takes up the entire size of the
13
frame. The CrossPlotFrame has a "center" slot as well as "top", "bottom", "left",
14
and "right", which define a plus-shaped arrangement.
16
Containers can be placed within these slots, and other containers can be nested
17
within those, so that within each slot, a very flexible layout can be achieved.
18
For example, geophysical "log plots" generally consist of a SimplePlotFrame with
19
a horizontal plot container (HPlotContainer) in the "center" slot. Tracks in
20
the horizontal container are VPlotContainers, with GeoAxis components stacked
21
above a single plot area, which is an OverlayPlotContainer. (The GeoTrack class
22
is actually a subclass of VPlotContainer that automatically create GeoAxis objects
23
as GeoPlots are added to the plot area.)
27
--------------------------------------------------------------------------
29
In general, the hard work is in determining the size to assign to contained
30
components. Once this is done, setting the correct positions is usually trivial.
31
There are two constraints on layout and size: one from the topmost container downwards,
32
and the other from the innermost components up. The topmost container typically has
33
an area of finite size in which to draw all of its components. The innermost
34
components usually have some notion of what size they need to be. To reconcile
35
these two demands in a flexible way, layout consists of two stages:
37
First pass: the topmost component requests the size of all of its child components,
38
and they in turn query their contained components. The "preferred size"
39
of all the components is used to determine the minimum size that the
40
outermost/topmost component can be.
42
Second pass: The topmost component sets its own size, and then inspects its
43
contained components and sets their sizes. It then tells them to
44
perform layout given the sizes they have been assigned, and they all
45
do the same basic process.
47
The details get more complicated when resizable components and auto-fitting options
48
are taken into account. All components (including containers) can be resizable in
49
one or both dimensions, that is, they allow their container to set their size.
50
Furthermore, all resizable containers can be auto-fitting (the actual option is named
51
"fit_components") in one or both dimensions, which means that they set their size
52
based on the aggregate size of their contained components.
54
(In layout, each dimension is treated independently, so the methods below do
55
the same thing in x/width and y/height.)
58
If a container is not resizable, then this method returns its bounds.
59
If a container is resizable, then this method returns looks at the preferred
60
sizes of the visible contained components and returns an appropriate value.
61
If the container is empty, or none of its components are visible, it will
62
return its default_size.
65
Each non-resizable component gets its fixed size. The remaining space is shared
66
among the resizable components in proportion to their preferred sizes. If
67
the components use up more than the available space, then they are clipped.
68
If the components use up less than the available space, then depending on the
69
value of container.fit_components, either the container shrinks down to
70
tightly wrap the area described by the preferred sizes of all the components,
71
or the resizable components are stretched to fill the size of the container.