/*
**      Newton Developer Technical Support Sample Code
**
**      VariRoute, a Newton 2.0 routing example
**
**      by J. Christopher Bell, Newton Developer Technical Support
**
**      Copyright © 1994-7 by Newton, Inc.  All rights reserved.
**
**      You may incorporate this sample code into your applications without
**      restriction.  This sample code has been provided "AS IS" and the
**      responsibility for its operation is 100% yours.  You are not
**      permitted to modify and redistribute the source as "DTS Sample Code."
**      If you are going to re-distribute the source, we require that you
**      make it clear in the source that the code was descended from
**      Newton, Inc-provided sample code, but that you've made changes.
*/

This sample shows how to layout and print items with varying heights, using
three different types of data and corresponding techniques.

The first type of data is "simple variable height" views, in which each view
can determine it's own height. Each child view defines its own height in its
viewSetupFormScript. Then, the views are organized using sibling vertical
justification. This sample shows child views of clView and clParagraphView,
both of which have dynamic heights. This simple mechanism is the most common
and least error-prone way of doing dynamically-sized child views.

The second type of data is clEditView data that might include shapes, sketches,
maps, or other types of grouped data. Because nearby views might need to be
treated as a diagram or other group, we use the Reflow function	to determine
the locations and positions of group data and to properly format paragraphs
that are not in diagrams.

The third type of data is a huge string that must be broken apart into
variable-height paragraphs. The Reflow function can be used to break large
strings apart like this.

The interesting code is in the Print____ files, and the view in each layout
called "NotesView". In that view, the viewSetupChildrenScript has most of the
special code.

If you are copying print layout code into your own project, be sure to copy all
of the same flags from that layout. Specifically, remember to set the viewFlags
and viewJustify flags the same in your project as in the sample code.

==== TIPS FOR VARIABLE-HEIGHT PRINTING

In the view that will be the parent of the variable-height children, set the
vReflow flag in the viewJustification slot. It tells the view system that if a
child view will NOT fit vertically in the parent's bounds, destroy it and
remove it from my stepChildren array. Note: you do NOT have to use the Reflow
function in order to use vReflow.

This feature of vReflow usually used by the view's viewSetupDoneScript to check
the length of the stepChildren array. The viewSetupDoneScript can determine how
many views actually fit on the page and then keep track of this. Store this in
the print format's reflowStart slot -- not in the "NotesView", which will be
destroyed when the print format calls :RedoChildren() between pages.

On the next page, you can avoid creating already-printed views by reading the
reflowStart slot. Also, the printNextPageScript uses reflowStart to determine
all of the views have been printed so it knows whether the print job is
complete. (see the printNextPageScript for more info)


==== CHECKLIST FOR VARIABLE-HEIGHT PRINTING
In the items below, the term "the parent" refers to the parent view of the 
many variable-height items. In all three layouts in this sample, this is the 
view in the print format called NotesView.

* In the print format, add a printFormatKids slot (set to nil)

* In the print format, initialize the reflowStart to 0 (see the
viewSetupFormScript for details!)

* In the parent's viewSetupChildrenScript, prepare an array of child views if
it hasn't been done yet, and store that in the print format's printFormatKids
slot. For clEditViews or big text, use kReflowWrapperFunc to get this array.

* In the parent's viewSetupChildrenScript, use ArrayMunger to skip
already-created kids. (see the viewSetupChildrenScript for details)

* In the parent's viewJustification slot, set the vReflow flag

* In the parent's viewSetupDoneScript, check Length(stepChildren) and increase
reflowStart by this amount.

* In the print format printNextPageScript, check if there are more pages. Use
code like: if printFormatKids and Length(printFormatKids) > reflowStart


==== MORE INFO ABOUT THE REFLOW FUNCTION

There are some arguments to Reflow(...) that must be specific values, and they
are provided in a wrapper function kReflowWrapperFunc in this project to make
things easier for you. See the kReflowWrapperFunc file in this project for
details about what that kReflowWrapperFunc takes as arguments.

Note that the templates returned are not the original view templates, but are
based on them (using _proto slots and additional views as appropriate). Note
that if 'grouping' happens, kReflowWrapperFunc may return fewer view templates
than were originally reflowed.

The idea behind grouping is that without some advance knowledge about the
structure of clEditView data, the OS cannot tell where diagrams are nor what
the bounds of a diagram is. For instance, a square near a paragraph of text
might need to be kept together because it is a street map diagram. In this
case, the width of the text view will not be increased to the width of the
page. Text that appears to be unconnected to other views will be made the width
of the destination view.

We do NOT support using the Reflow function for general-purpose reflowing of
developer-created views. For that type of thing, use the "simple variable
height" technique (see the "PrintSimpleVari" layout for details). One reason is
that Reflow has some bugs that can make the behavior undefined in some
circumstances.


If you have comments about this sample, email J. Christopher Bell at
bell@newton.apple.com.

Version 1 - Jul 2, 1997