\begindata{text,538476484}
\textdsversion{12}
\template{default}
\define{itemize
menu:[Region,Itemize]
attr:[LeftMargin LeftMargin Inch 32768]}
\define{enumerate
menu:[Region,Enumerate]
attr:[LeftMargin LeftMargin Inch 32768]}
\define{programexample
menu:[Region,ProgramExample]
attr:[Justification LeftJustified Point 0]
attr:[FontFamily Helvetica Int 0]}
\define{notetotypesetter
menu:[Region,NoteToTypesetter]
attr:[Flags PassThru Int Set]}
\define{title
menu:[Heading,Title]
attr:[Justification Centered Point 0]
attr:[FontSize PreviousFontSize Point 4]}
\define{appendix
menu:[Heading,Appendix]
attr:[FontFace Bold Int Set]
attr:[FontSize PreviousFontSize Point 4]}
\define{ibm
menu:[Font,IBM]
attr:[FontFamily ibm Int 0]}
\define{centre
menu:[Region,Centre]
attr:[Justification Centered Point 0]}
\define{passthrough
menu:[Region,Passthrough]
attr:[Flags PassThru Int Set]}
\define{sans
menu:[Font,Sans]
attr:[FontFamily AndySans Int 0]
attr:[FontSize PreviousFontSize Point -2]}
\define{block
menu:[Region,Block]
attr:[LeftMargin LeftMargin Inch 81920]}
\italic{styling}
\begindata{bp,538929224}
\enddata{bp,538929224}
\view{bpv,538929224,1345,0,0}
\center{
\bigger{\bold{\bigger{\bigger{Tree}}
Programming Guide}}
Version
1.0
(ATK Version 11.7)
Information Technology Center
Carnegie-Mellon University
TC Peters
(12/22/88)
8/31/89
\bold{ Working Draft }
\bold{SUBJECT
TO
SIGNIFICANT
REVISION }
\bold{(c) IBM Corporation
1989}}
\begindata{bp,538928520}
\enddata{bp,538928520}
\view{bpv,538928520,1346,0,0}
\bold{Preface}
This document presents the Concepts and Facilities of the \bold{Tree}
class.
This class provides facilities for the management of tree structures and
interactive views that can be employed to display them.
The \bold{Tree} class comprises both a data-object (\sans{\bold{tree}})
and a
view-object (\sans{\bold{treev}}); they are sub-classes of the
\italic{apt}
and \italic{aptv} classes, respectively (see the \italic{Apt Programming
Guide}
for details regarding built-in Iconification, Help, and other common
features). As generic classes, they are meant to be used by clientprograms
to provide both management of Client-program generated structures and
tailorable visual interfaces
\begindata{bp,538269640}
\enddata{bp,538269640}
\view{bpv,538269640,1347,0,0}
\bold{Introduction}
xxx
\begindata{bp,538271624}
\enddata{bp,538271624}
\view{bpv,538271624,1348,0,0}
\chapter{1 Concepts}
Support for trees is provided both for the data-structure itself
(\sans{tree})
and for interactively viewing the data-structure (\sans{treev}). The
Tree
Data-object facilities can be employed without use of a corresponding
Tree
View-object; on the other hand, the same Tree Data-object may be viewed
concurrently through any number of Tree Views.
The Tree Classes are \italic{generic} -- ie, they are designed to be
employed
by other Classes; in themselves, they provide only those facilities
needed to
build, manipulate, and view Trees under the direction of such higherorder
Client classes.
\bold{Trees}
Tree structures are composed of \italic{Nodes} connected hierarchically.
The
top-most Node is termed the \italic{Root} Node; one and only one Root
Node
exists in a Tree.
Immediately beneath the Root Node, zero or more
\italic{Child} Nodes may exist; in turn, each such Child Node may have
zero
or more children of its own, \italic{ad infinitum}. Each Node is
connected to
its \italic{Parent}, its Left and Right \italic{Siblings}, and to its
Children; any one or more of these connections may be Null (eg, the Root
Node
does not have a Parent Node). Nodes that have no children are termed
\italic{Leaf} Nodes; Nodes other than the Root Node and the Leaf Nodes
are
termed \italic{Interior} Nodes.
\center{
*********************************
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*********************************
}
In addition to its connection attributes, each Node may be given a unique
symbolic \italic{Name}, a \italic{Caption}, a \italic{Titl}e, as well as
an
\italic{Datum}.
Whereas support for \italic{manipulating} Trees is
provided
by the Tree Data-object, the \italic{meaning} of a Tree is provided by
the
Client; this is effected by placing into each Node a Client-defined datum
-where a Datum is either a data \italic{value} or a \italic{pointer} to a
value
(eg, a scalar or a structure, or even a pointer to a Procedure).
Trees are built by creating Nodes at specified places within the Tree.
Initially, the Root Node is created, then one or more of its children.
These
children may, in turn, have Nodes created as their children. At any
point
during building, existent Nodes may be destroyed or moved within the
Tree.
Depending upon the requirements of the Client, Trees may be built
\italic{in
toto} or piece-wise.
When created, a Node is given a symbolic Name and a Datum; these may be
Null.
A Node's Name and its Datum may subsequently be queried or changed to
other
values. In addition to Node location via Tree walking support,
individual
Nodes may be located through their Names or their Datum values.
Various facilities are provided to determine a given Node's Name,
Caption,
Title, Datum, Level, etc. These are often utilized to handle interactive
manipulation of the Tree through a Tree View-object.
A Tree View-object may be related to a Tree Data-object to form a Tree
\italic{Inset}. The Tree View-object provides an visual interactive
interface
onto the Tree Data-object. The visual format of a Tree is customizable
by the
Client; appropriate display of the Tree is automatically performed by the
Tree
View-object. Standard scrolling operations, as well as layout, printing,
and
interactions are provided in both default and customized fashions.
Interaction events handled by the Tree View-object are capable of either
default responses (eg, Hiding and Exposing the children of selected
Nodes) or
parochial responses dictated by the Client. The Client may specify a
\italic{Hit Handler} to be invoked by the Tree View-object whenever the
User
selects a Node through its visual representation. In the absence of such
a
Hit Handler, the Tree View-object performs its default actions. Node
selection is usually effected through the mouse, but may also be effected
through the keyboard.
\bold{Nodes}
The Node is the \italic{substance} of a Tree -- it is the
\italic{connections}
amongst Nodes that comprise the Tree structure. A Node is itself a data
structure, containing fields automatically set and manipulated by
facilities
of the Tree Class as well as several fields directly manipulated by the
Client.
Fields accessible to the Client are the Node's -\indent{\bold{\italic{Name}}
Each Node enjoys a symbolic \italic{Name}, which may be null. The
Symbolic
Name may be used to locate the Node within the Tree; it serves, in lieu
of a
Node Caption, as the value displayed when the Node is viewed through the
Tree
View-object.
\bold{\italic{Caption}}
Each Node enjoys a \italic{Caption}, which may be null. The Caption is
displayed when the Node is viewed throught the Tree View-object. Where a
Node
has a null Caption, its symbolic Name is displayed instead.
\bold{\italic{Title}}
Each Node enjoys a \italic{Title}, which may be null. The Title is
displayed
when the Node is viewed throught the Tree View-object. Where a Node has
a
null Title, none is displayed.
\bold{\italic{Datum}}
Each Node enjoys an \italic{Datum}, which may be null. The Datum contain
a
scalar value (type \sans{long}), which is of any value set by the
Client.}
\section{1.1
Features}
\subsection{1.1.1 Arrangements}
\subsection{1.1.2 Scrolling}
\subsection{1.1.3 Data/View Dichotomy}
Tree facilities are partitioned into those that deal with the Tree Dataobject
and those that deal with the Tree View-object. The facilities are
partitioned
to support multiple Views onto a given Data-object.
Due to the generic nature of the Tree class, it does not provide methods
either to Read or to Write Tree datastreams; this is the responsibility
of the
Client.
\section{1.2
Attribute Specification}
The fashion in which Trees are manipulated and displayed, as well as the
nature and format of its Nodes, is governed by the Specification argument
optionally provided when the Tree object is created. (See the
\sans{Create}
facilities, discussed in the chapters \italic{Facilities -- Data Object
Instantiation} and \italic{View Object Instantiation.})
The syntax of specifications is best shown through examples:
\sans{\indent{
tree_Specification
my_tree[ ] =
\{
tree_TraversalMode( tree_PreOrder ),
tree_TitleCaption( "My Own Tree" ),
Null
\};}}
\sans{\indent{
treev_Specification
my_treev[ ] =
\{
treev_Arrangement( treev_Fold ),
treev_BackgroundShade( 50 ),
treev_NodeBorderStyle( treev_Oval ),
treev_HitHandler( My_Tree_Hit ),
Null
\};}}
A Specification is composed of macros, each requiring an argument.
argument is sometimes a \italic{symbolic} (eg, \sans{treev_Oval}),
sometimes a
The
\italic{numeric value} (eg, the value 50 in
\sans{treev_BackgroundShade}),
sometimes a \italic{character-string} (eg, the quoted characters
\italic{My
Own Tree} in \sans{tree_TitleCaption}), and sometimes a
\italic{procedure-pointer} (eg, \sans{My_Tree_Hit} in
\sans{treev_HitHandler}). Note that all symbolics are prefixed with
"\sans{tree_}" or "\sans{treev_}" to avoid name-clashes within the
Client-program.. There is no required ordering amongst the items in the
Specification structure: it is parsed sequentially, such that a
subsequent
attribute overrides an earlier conflicting attribute.
See chapter \italic{Sample Programs} for more complete examples.
The Data and View attributes of the Tree and its Nodes, their defaults
and
alternatives, are discussed below. (In each section attributes are
listed
\italic{alphabetically}, for ease of reference.)
\subsection{1.2.1 Data Specifications}
The manner in which Trees are structured is controlled by the
Specification
optionally provided when the Tree Data-object is created. (See the
\sans{Create} facility, discussed in the chapter \italic{Facilities -Data
Object Instantiation.})
The structural attributes of the Tree and its Nodes, their defaults and
alternatives, are discussed below.
\paragraph{1.2.1.1
Tree Data Attributes}
This section lists those data attributes that are applicable to the Tree
as a
whole, including those Node attributes that are inherited by all Nodes,
unless
overridden for individual Nodes.
\bold{\sans{tree_Datum}}
\indent{Any Client-program datum (eg, a scalar or a pointer to a
Client-program defined structure). Dynamically accessible via the
\sans{SetTreeAttribute} and \sans{TreeAttribute} facilities. (Also see
the
\sans{NodeDatum} attribute, which provides the node-specific data
attribute.)}
\bold{\sans{tree_NodeCaption}}
\indent{A character-string.
unless overridden.}
All Nodes will contain this \sans{Caption},
\bold{\sans{tree_NodeDatum}}
\indent{Any Client-program datum (eg, a scalar or a pointer to a
Client-program defined structure). Dynamically accessible via the
\sans{SetNodeAttribute} and \sans{NodeAttribute} facilities. (Also see
the
\sans{Datum }attribute, which provides the Tree data attribute.)}
\bold{\sans{
tree_NodeName}}
\indent{A Node may be given a \italic{symbolic name} for use during
execution.
(See the facilities \sans{NodeOfName} and \sans{NodesOfName}.)
}
\bold{\sans{tree_NodeTitleCaption}}
\indent{A Node may contain a caption as a Title. By default, the Title
is
centered at the top of the Node, beneath the Node's Border This
Placement and
its Alignment within the title-area can be overridden via the
\sans{NodeTitlePlacement} and \sans{NodeTitleAlignment} attributes.. (A
Node
Title may instead be an Inset.)}
\bold{\sans{tree_TitleCaption}}
\indent{A Tree may contain a \italic{Title}. The Title may be a caption
or an
Inset. By default, the Title is centered at the top of the Container,
within
the Container's Border. A Title caption may contain \italic{new-line}
characters: the Title then occupies multiple vertical lines. (See
\sans{TitleAlignment} and \sans{TitlePlacement}.)}
\sans{\bold{tree_TraversalMode}}
\indent{By default, Trees are traversed in a Top-Down, Left-Right order
known
as \italic{PreOrder}. Alternatively, the sequence used to traverse the
Tree
may be specified as \italic{PostOrder},
\indent{
\sans{tree_PreOrder}
\sans{tree_PostOrder}
}}
\center{
*********************************
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*********************************
}
\paragraph{1.2.1.2
Node Data Attributes}
Each Node can be individually specified. Such specification may be as
minimal
as just its Caption or as elaborate as necessary to individualize each
Node.
Node data attributes are inherited from the Tree data specification,
except
where an attribute is overridden for that Node via a Node Specification.
The
attributes that may appear in a Node data Specification are those defined
above, \italic{Tree Data Specifications}. Note that either generic or
Node-specific spellings may be employed; thus, to specify a Node's
Datum,
either
\sans{tree_Datum} or \sans{tree_NodeDatum} may be used within
a
Node specification.
\subsection{1.2.2 View Specifications}
The fashion in which Trees are displayed is controlled by the
Specification
optionally provided when the Tree View-object is created. The visual
attributes of the Tree and its Nodes, their defaults and alternatives,
are
discussed below.
\paragraph{1.2.2.1
Tree View Attributes}
This section lists those view attributes that are applicable to the
displayed
Tree as a whole, including those Node view attributes that are inherited
by
all Nodes, unless overridden for individual Nodes.
\bold{\sans{treev_Arrangement}}
\indent{By default, Trees are displayed \italic{Vertically}: children are
beneath parent nodes. Alternatively, Tree may be displayed
\italic{horizontally}: children are displayed to the right of their
parent
nodes.
By default, when the children of a Node are exposed and their combined
widths
exceed the width of the enclosing area, the set of children are
\italic{folded}
into two or more rows to fit within the given width; the set of folded
Nodes
is enclosed by a rectangular outline indicating the folded nature of the
set.
Folding may be suppressed, resulting in the clipping of those children
outside the given area. (When non-folded displays are specified, the
\italic{Horizontal Scroll} feature is defaulted.)
\indent{\sans{treev_Vertical}
\sans{treev_Horizontal}
\sans{treev_Fold
|
treev_NoFold}}}
\bold{\sans{treev_BackgroundShade}}
\indent{The Container is transparent, by default. It is the Clientprogram's
responsibility to set the background appropriately (usually white). You
may,
however, specify a gray-shade for the background. The
\sans{BackgroundShade}
values are -\indent{0
Transparent
1
White
2
Lightest shade of gray
...
(Darker shades of gray)
100
Darkest shade of gray (black)}}
\bold{\sans{treev_BorderStyle}}
\indent{The Container may be bordered; by default, the border is a
rectangle,
whose line-width is one. Its style may be specified in various other
fashions:
\indent{\sans{treev_Rectangle}
\sans{treev_Roundangle}
\sans{treev_Circle}
\sans{treev_Oval}
\sans{treev_Invisible}
\sans{treev_None}}}
\bold{\sans{treev_BorderSize}}
\indent{Where the \sans{BorderStyle} is other than \sans{None}, the width
of
the line (default is one) may be specified.}
\bold{\sans{treev_Cursor}}
\indent{The cursor for the Tree may be specified; the value -- either an
ASCII
characer literal or a symbolic name. If the \sans{CursorFontName} is not
specified, the default font is \italic{icon12}. The default cursor is
the
standard Arrow.
Example:
\sans{treev_Cursor( 'E' )}
\sans{treev_Cursor( Cursor_Gunsight )}}
\bold{\sans{treev_CursorFontName}}
\indent{The font for the Tree's cursor may be specified.
font is
\italic{icon12}.
Example:
The default
\sans{treev_CursorFontName( "treeicon20" )}}
\bold{\sans{treev_FootPrintStyle}}
\indent{In addition to highlighting a Node, it is often useful to provide
a
visual indication of the Nodes along the \italic{path} leading to the
highlighted Node. By default, these footprints are indicated by making
\sans{Pale} the ancestor Nodes along that path.
\indent{
\sans{treev_Pale}
\sans{treev_Invert}
\sans{treev_Border}
\sans{treev_NoFootPrint}}}
\bold{\sans{treev_HitHandler}}
\indent{A Tree may specify a Client-program procedure to be invoked
whenever a
Node is hit. (See the section \italic{HitHandlers}.)}
\bold{\sans{treev_LeafNodeStyle}}
\indent{By default, Leaf Nodes are displayed in the same fashion as all
other
Nodes. Special display of Leaf Nodes can be specified: suppression of
Drop
Shadow, different Node Border Style, or ???.}
\bold{\sans{treev_NodeBorderStyle}}
\indent{By default, Nodes are displayed as \italic{Rectangle}s.
be
displayed as:
\indent{\sans{treev_Rectangle}
\sans{treev_Roundangle}
\sans{treev_Circle}
\sans{treev_Oval}
\sans{treev_Invisible}
\sans{treev_None}}}
\bold{\sans{treev_NodeConnectorStyle}}
They may
\indent{By default, Nodes are connected to their children by "Dog Legs" lines that run from the bottom of the Parent Node to the top of each
Child
Node in vertical and horizontal segments. They may be connected in a
Direct
fashion -- single lines that run diagonally from the bottom of the Parent
to
the top of each Child.
\sans{\indent{treev_Direct}}
\sans{\indent{treev_DogLeg}}}
\bold{\sans{treev_NodeFiligree}}
\indent{By default, Nodes are displayed with \italic{Drop Shadows} -- an
illusory shadow of the Node's Border. The Drop Shadow may be suppressed.
\sans{\indent{treev_DropShadow
|
treeev_NoDropShadow}}}
\bold{\sans{treev_NodeFontName}}
\indent{By default, Node Captions are displayed in the User's preferred
BodyFont. A specific font may be specified instead.}
\bold{\sans{treev_NodeHighlightStyle}}
\indent{By default, Nodes are highlighted using inverse-video. They may
be
highlighted by changing the Node Caption to Bold or Italic font. The
styles
for Highlighting, which may be used in combination, are:
\indent{\sans{treev_Invert}
\sans{treev_Border}
\sans{treev_Bold}
\sans{treev_Italic}}}
\bold{\sans{treev_NodeOrder}}
\indent{By default, Folded Nodes are displayed in \italic{ColumnMajor}
order.
Alternatively, they may be displayed in \italic{RowMajor} order.}
\bold{\sans{treev_NodeWidth}
\sans{treev_NodeHeight}}
\indent{By default, Nodes are automatically sized to fit the largest
Caption
or Title to be displayed -- depending upon the font specified and the
characters found within the Captions and Titles; all Nodes are displayed
in
the same size. The width and height may be specified as fixed values;
where a
Caption or Title exceeds the available width, it is wrapped to the next
line.}
\bold{\sans{treev_Scroll}}
By default, a \italic{Vertical} Scroll is provided to the left of the
display;
this Scroll may be suppressed. Additionally, a \italic{Horizontal}
Scroll may
be specified. Where Folding is specified, the horizontal Scroll is
suppressed; where Folding is suppressed, a horizontal Scroll is provided
by
default, but may be suppressed.
\indent{\sans{treev_Left}
\sans{treev_Right}
\sans{treev_Top}
\sans{treev_Bottom}
\sans{treev_NoVertical}
\sans{treev_NoHorizontal}}
\paragraph{1.2.2.2
Node View Attributes}
Each Node can be individually specified.
minimal
Such specification may be as
as just its Caption or as elaborate as necessary to individualize each
Node.
Node view attributes are inherited from the Tree view specification,
except
where an attribute is overridden for that Node via a Node Specification.
The
attributes that may appear in a Node view Specification are those defined
above, \italic{Tree View Specifications}. Note that either generic or
Node-specific spellings may be employed; thus, to specify a Node's
Caption
Font, either
\sans{treev_CaptionFontName} or
\sans{treev_NodeCaptionFontName} may be used within a Node view
specification.
\section{1.3
Handlers}
Whereas the tree class provides appropriate housekeeeping to reflect User
interaction with a Tree through its view, it is the Client-program's
Handlers
(also known as "call-back procedures") that effect whatever functionality
such
interaction implies. There are various interactions and events that will
cause a Handler to be invoked.
A Handler may be specified for the Tree as a whole or for individual
Nodes.
In the absence of individual Node Handlers, the Tree Handler is
employed.
Where both a Tree Handler and Node Handlers are specified, the latter
are
employed.
There are two kinds of Handlers: those that cope with Hits and those
that
deal with Nodes specified as Objects (ie, not simply captions).
\subsection{1.3.1 Hit Handlers}
Upon invocation, a Hit Handler is passed these arguments:
\indent{\bold{Argument-1:}
The Client-program Anchor associated with the Tree View (as provided via
the
\sans{treev_Create} facility).
\bold{Argument-2:}
Identifier of the Tree.
\bold{Argument-3:}
Identifier of the object hit.
\bold{Argument 4:}
Hit-object type (\sans{treev_TitleObject}, \sans{treev_NodeObject}, or
Null).
\bold{Arguments 5-8: }
Standard ATK Mouse information -- action, x, y, clicks.}
Thus, a typical Hit Handler would be written:
\indent{\sans{My_Hit_Handler( self, tree, object, type, action, x, y,
clicks )}}
(The parameter \sans{self} is the value specified as the \italic{Anchor}
by
the Client-program via \sans{treev_Create}.)
Note that all mouse-actions (including DownMovement) are passed through
to the
HitHandler, whether or not a Node or Title is affected (this provides
support
for such actions as client-program controlled movement of Nodes from one
parent to another).
\subsection{1.3.2 Object Handlers}
Handlers may specified to deal with instantiation of Data and View
objects.
...
Upon invocation, an Object Handler is passed these arguments:
\indent{\bold{Argument-1:}
The Anchor associated with the Tree.
\bold{Argument-2:}
Identifier of the Tree.
\bold{Argument 3:}
Identifier of the object.
\bold{Argument 4:}
Object-type (\sans{treev_TitleObject} or \sans{treev_NodeObject}).
}
Thus, a typical Object Handler would be written:
\sans{\indent{My_Object_Handler( self, tree, object, type )}}
\section{1.4
Printing}
Printed output is in PostScript form.
xxx
\begindata{bp,538271496}
\enddata{bp,538271496}
\view{bpv,538271496,1349,0,0}
\chapter{2 Facilities}
Facilities are ClassProcedures, Methods, or MacroMethods provided by a
Class
to facilitate communication between an object and its creator. There are
two
groups of facilities: those for the Tree itself, and those for the Nodes
of
the Tree.
The facilities are presented in a standard form:
A brief \italic{\bold{description}}of the facility, followed by these
topics
-\italic{\bold{Synopsis}}
types of
arguments.
Prototype statement syntax and data-
\italic{\bold{Returns}}
returned.
Data-type and description of value
\italic{\bold{Exceptions}}
Name of any exceptions raised.
\italic{\bold{Discussion}}
its role
and usage.
Elaboration of the nature of the facility,
\bold{Syntax Conventions}
To provide examples of their usage, both sample statements and a chapter
of
Sample Programs are listed; these are shown in the syntax of the ATK
\italic{Class} extension.
Of particular interest are certain implications upon naming-conventions
and
required arguments:
\indent{
o The ATK Class feature requires methods to be prefixed with the name of
the
Class to which they belong. Further, it requires that the first argument
always be the Identifier (handle or pointer) of the instantiated Object
being
invoked. Thus -\sans{\bold{\indent{tree_CreateRootNode( \italic{object}, \italic{name},
\italic{datum} );}}}
\indent{
where :
\sans{\bold{object }}
is the Identifier of the instance of the Class (as returned from the
\sans{tree_Create} facility);
\sans{\bold{name }}
is a pointer to a character-string;
\sans{\bold{datum}}
is a scalar value.}
o All symbolic-names (eg, those of the options and exception-codes) are
prefixed with the character "tree_" or "treev_" to preclude nameclashes
with Client-program names.}
\section{2.1
Data Object Facilities}
These facilities deal with the Tree Data-object.
\subsection{2.1.1 Data Object Instantiation}
Tree Data-objects are instantiated through either the \sans{Create} or
the
\sans{New} facility. Where the \sans{Create} facility is employed, you
can
override the default object attributes.
\paragraph{2.1.1.1
Create}
Creates a Data-object of the class \sans{tree}. Parses the optional
Specification to establish initial attributes; reserves the requesting
object's Identifier (for subsequent call-backs).
\bold{Synopsis}\block{ \sans{tree_Create( specification, anchor )
tree_Specification
struct basicobject
specification
*anchor
|
|
NULL}}
NULL
\bold{Returns}\block{
object
identifier.}}
\sans{struct tree
\bold{Exceptions}\block{
\sans{AttributeConflict}}
*}
\italic{Tree Data-
\sans{InsufficientSpace},
\bold{Discussion}\block{
When created, the Tree data-object contain
the Null
Tree. You subsequently employ the \italic{Node Creation} methods (below)
to
build the Tree.}
\subsection{2.1.2 Tree Dataobject Facilities}
These facilities deal with the Tree structure (see \italic{Tree
Viewobject
Facilities} for those dealing with Tree presentation and interaction).
\paragraph{2.1.2.1
Tree Dataobject Attributes}
Tree attributes may be set either at compile-time, through the static
declaration of the Specification vector passed as an optional argument
to the
\sans{Create} facility, or dynamically through the
\sans{SetTreeAttribute}
facility. In most instances, the static fashion suffices.
\paragraph{2.1.2.1.1
SetTreeAttribute}
Sets the specifed attribute of the Tree to the given value.
\bold{Synopsis}\block{ \sans{tree_SetTreeAttribute( object,
attribute_value)
struct tree
*object
tree_Specification
}}
\bold{Returns}\block{
attribute_value
\sans{long} \italic{
\bold{Exceptions}\block{
None.}
Result-code.}}
\bold{Discussion}\block{
Each of the attributes listed in the section
\italic{Tree Specifications} can be set either statically or dynamically.
Where the given\sans{ attribute value} is \sans{NULL}, that Tree
attribute is
set to Null. The syntax for this facility is that employed in the static
declaration of attributes, for example -Example: \sans{tree_SetTreeAttribute( object, tree_TitleCaption( "Local
Personnel" ) )}
}
\paragraph{2.1.2.1.2
TreeAttribute}
Yields the value of the given attribute for the Tree.
\bold{Synopsis}\block{ \sans{tree_TreeAttribute( object, attribute)
struct tree
*object
long
attribute
}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
Value.}}
None.}
\bold{Discussion}\block{
Each of the attributes listed in the section
\italic{Tree Specifications} can be queried.
The syntax of this facility is similar to that of the SetTreeAttribute
facility, but differs in that the parenthesized argument is 0 (Null).
Example:
\sans{tree_TreeAttribute( object, tree_Datum(0) )}
\sans{tree_TreeAttribute( object, tree_Title(0) )}
}
\paragraph{2.1.2.2
Tree Dataobject Structuring}
These facilities deal with the Tree structure.
\paragraph{2.1.2.2.1
NodeCount}
Computes the total number of Nodes in the Tree or sub-Tree.
\bold{Synopsis}\block{ \sans{tree_NodeCount( object, node )
struct tree
*object
struct tree_node
*node
\bold{Returns}\block{
\sans{long}
\bold{Exceptions}\block{
|
NULL}}
\italic{Node Count.}}
None.}
\bold{Discussion}\block{
Where the given node is Null, the count
commences at
the Root Node; otherwise, the count commences at the sub-Tree headed by
the
given Node. Note that the count includes the given Node.}
\paragraph{2.1.2.2.2
Computes the number of
PeerNodeCount}
Siblings for the given Node.
\bold{Synopsis}\block{ \sans{tree_PeerNodeCount( object, node )
struct tree
*object
struct tree_node
*node
\bold{Returns}\block{
\sans{long}
\bold{Exceptions}\block{
|
NULL}}
\italic{Peer Node Count.}}
None.}
\bold{Discussion}\block{
Where the given node is Null, the count is 0
(zero).
Note that the count excludes the given Node.}
\paragraph{2.1.2.2.3
Computes the number of
ChildNodeCount}
Children of the given Node.
\bold{Synopsis}\block{ \sans{tree_ChildNodeCount( object, node )
struct tree
*object
struct tree_node
*node
\bold{Returns}\block{
\sans{long}
\bold{Exceptions}\block{
|
NULL}}
\italic{Child Node Count.}}
None.}
\bold{Discussion}\block{
Where the given node is Null, the count is
of the
children of the Root Node.}
\paragraph{2.1.2.2.4
Computes the number of
LeafNodeCount}
Leaf Nodes in the Tree.
\bold{Synopsis}\block{ \sans{tree_LeafNodeCount( object )
struct tree
*object}}
\bold{Returns}\block{
\sans{long}
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
None.}
\paragraph{2.1.2.2.5
\italic{Leaf Node Count.}}
NodeLevel}
Computes the Level of the given Node within the Tree.
\bold{Synopsis}\block{ \sans{tree_NodeLevel( object, node )
struct tree
*object
struct tree_node
*node
|
NULL}}
\bold{Returns}\block{
\sans{long}
\italic{Node Level.}}
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
Where the given node is Null, the level is
that of
the RootNode -- viz, 1. The immediate Children of the Root Node are at
Level-2, their Children are at Level-3, etc}
\paragraph{2.1.2.2.6
NodePosition}
Computes the Position of the given Node -- ie, the count of its left
Siblings
plus 1.
\bold{Synopsis}\block{ \sans{tree_NodePosition( object, node )
struct tree
*object
struct tree_node
*node
\bold{Returns}\block{
\sans{long}
\bold{Exceptions}\block{
|
NULL}}
\italic{Node Position.}}
None.}
\bold{Discussion}\block{
The Position of the left-most sibling is 1.
Where
the given node is Null, the Position is that of the Root Node -- viz, 1.}
\paragraph{2.1.2.2.7
NodeIndex}
Yields formatted character-string of
given
node.
the "dewey-decimal" index of the
\bold{Synopsis}\block{ \sans{tree_NodeIndex( object, node )
struct tree
*object
struct tree_node
*node}}
\bold{Returns}\block{
string Pointer.}}
\sans{char *}
\italic{Character-
\bold{Exceptions}\block{
\sans{NonExistentNode}}
\bold{Discussion}\block{
An entire sample tree is indexed thus --
0
|
1
2
3
|
1.1
...
2.1
2.2
2.3
...
3.1
|
2.2.1 2.2.2 2.2.3
|
2.2.2.1
2.2.2.2
2.2.2.3
The \sans{Index} facility is useful for developing \italic{Table of
Content}
listings: the Indices returned from a \italic{PreOrder} walk through the
Tree
provide an appropriate string for identifying each section of a book -eg,
\indent{
1
1.1
1.1.1
1.1.2
1.2
1.2.1
1.2.2
1.2.2.1
1.2.2.2
1.2.3
1.3
2
2.1
2.1.1
2.1.1.1
2.1.1.2
2.2
3
3.1
etc. etc.}
}
\paragraph{2.1.2.2.8
NodeAncestry}
Generates a character-string composed of the names of the given Node's
ancestors, the Root Node's name being first. Each Node name is separated
from
the next by the specified \sans{separator} character-string.
\bold{Synopsis}\block{ \sans{tree_NodeAncestry( object, node, separator )
struct tree
*object
struct tree_node
char
*node
|
NULL
*separator;}}
\bold{Returns}\block{
char *
\bold{Exceptions}\block{
\italic{Node Ancestry.}}
None.}
\bold{Discussion}\block{
Where the given node is Null or the Root
Node, the
Null pointer is returned. The returned character-string pointer
identifies
dynamically allocated storage; it is the client's responsibility to free
that
storage when no longer needed.
The generated string does \italic{not} include the name of the given
Node;
also, note that the \sans{separator} string \italic{separates} and
neither
preceeds nor succeeds the generated string.}
\paragraph{2.1.2.2.9
TreeWidth}
Computes the width of the Tree..
\bold{Synopsis}\block{ \sans{tree_TreeWidth( object )
struct tree
*object}}
\bold{Returns}\block{
\sans{long}
\bold{Exceptions}\block{
\italic{Tree width}}
None.}
\bold{Discussion}\block{
The width of a Tree is the count of the
maximum
number of Nodes at any one level. Thus the width of the following Tree
is 7
--
}
\paragraph{2.1.2.2.10
TreeHeight}
Computes the height (depth) -- ie, the longest path -- of the Tree..
\bold{Synopsis}\block{ \sans{tree_TreeHeight( object )
struct tree
*object}}
\bold{Returns}\block{
\sans{long}
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
None.}
\italic{Tree height}}
\paragraph{2.1.2.3
Tree Dataobject Walking}
\paragraph{2.1.2.3.1
RootNode}
Yields Identifier of the Root Node.
\bold{Synopsis}\block{ \sans{tree_RootNode( object )
struct tree
*object}}
\bold{Returns}\block{
Identifier.}}
\sans{struct tree_node *}
\italic{Node
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
Null is
returned.}
In the absence of a Root Node, the value
\paragraph{2.1.2.3.2
NextNode}
Yields Identifier of next node, relative to the given node, in the
current
traversal mode (\italic{PreOrder} or \italic{PostOrder}).
\bold{Synopsis}\block{ \sans{tree_NextNode( object, node )
struct tree
*object
struct tree_node
*node
|
NULL}}
\bold{Returns}\block{
Identifier.}}
\sans{struct tree_node *}
\italic{Node
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
the
Tree walking may commence at any Node.
If
\sans{node} argument is Null, the walk begin with the Root Node. Where a
walk
limited to a given sub-tree is desired, this may be accomplished by
inspecting
the Node-Level of each Node returned by this facility: when the Node
returned
is at or above the Level of the root of the sub-tree, this indicates that
you
have walked out of the sub-tree. Where the \sans{node} argument is Null,
the
\italic{Root Node} is yielded. Upon reaching the end of the traversal,
the
value Null is yielded.}
\paragraph{2.1.2.3.3
PriorNode}
Yields Identifier of prior node, relative to the given node, in the
current
traversal mode (\italic{PreOrder} or \italic{PostOrder}).
\bold{Synopsis}\block{ \sans{tree_PriorNode( object, node )
struct tree
*object
struct tree_node
*node
\bold{Returns}\block{
Identifier.}}
\sans{struct tree_node *}
\bold{Exceptions}\block{
|
NULL}}
\italic{Node
None.}
\bold{Discussion}\block{
Tree walking may commence at any Node. If
the
\sans{node} argument is Null, the walk begin with the Root Node. Where a
walk
limited to a given sub-tree is desired, this may be accomplished by
inspecting
the Node-Level of each Node returned by this facility: when the Node
returned
is at or above the Level of the root of the sub-tree, this indicates that
you
have walked out of the sub-tree. Where the \sans{node} argument is Null,
the
\italic{Root Node} is yielded. Upon reaching the end of the traversal,
the
value Null is yielded.}
\paragraph{2.1.2.3.4
ParentNode}
Yields Identifier of the Parent of the given Node.
\bold{Synopsis}\block{ \sans{tree_ParentNode( object, node )
struct tree
*object
struct tree_node
*node}}
\bold{Returns}\block{
Identifier.}}
\sans{struct tree_node *}
\italic{Node
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
Null is
returned.}
In the instance of the Root Node, the value
\paragraph{2.1.2.3.5
ChildNode}
Yields Identifier of the first Child of the given Node.
\bold{Synopsis}\block{ \sans{tree_ChildNode( object, node )
struct tree
*object
struct tree_node
*node}}
\bold{Returns}\block{
Identifier.}}
\sans{struct tree_node *}
\italic{Node
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
value Null
is returned.}
Where the given Node has no children, the
\paragraph{2.1.2.3.6
LeftNode}
Yields Identifier of the immediate left-sibling of the given Node.
\bold{Synopsis}\block{ \sans{tree_LeftNode( object, node )
struct tree
*object
struct tree_node
*node}}
\bold{Returns}\block{
Identifier.}}
\sans{struct tree_node *}
\italic{Node
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
the
value Null is returned.}
Where the given Node has no no left-sibling,
\paragraph{2.1.2.3.7
RightNode}
Yields Identifier of the immediate right-sibling of the given Node.
\bold{Synopsis}\block{ \sans{tree_RightNode( object, node )
struct tree
*object
struct tree_node
*node}}
\bold{Returns}\block{
Identifier.}}
\sans{struct tree_node *}
\italic{Node
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
sibling, the
value Null is returned.}
Where the given Node has no no right-
\paragraph{2.1.2.4
Tree Dataobject Manipulation}
These facilities deal with the entire Tree structure.
\paragraph{2.1.2.4.1
Reset}
Resets the Tree to the specified state.
\bold{Synopsis}\block{ \sans{tree_Reset( object, state)
struct tree
*object
long
tree_Clear}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
\sans{tree_Clear}
its empty
state: ie, no Nodes, etc.}
\paragraph{2.1.2.4.2
Result-code.}}
--
returns the tree to
Apply}
Walks over the Nodes of the Tree, in the specified Traversal mode,
invoking
the given \sans{proc} for each Node encountered.
\bold{Synopsis}\block{ \sans{tree_Apply( object, node, proc, anchor,
datum )
struct tree
*object
struct tree_node
*node
long(*)()
procedure
struct basicobject
long
*anchor
datum}}
\bold{Returns}\block{
long
\italic{
Client returned-value.}}
\bold{Exceptions}\block{
\sans{ApplyInterrupte}d}
\bold{Discussion}\block{
arguments,
in the order shown:
The \sans{procedure} is invoked with these
\indent{\sans{anchor}
Given \sans{anchor}-value
\sans{tree}
Identifier of the Tree object
\sans{node}
Identifier of present Node
\sans{datum}
Given \sans{datum}-value}
Within the \sans{procedure}, all Tree facilities may be employed; note
that
alteration of the Tree structure will affect subsequent invocations to
the
procedure.
Where the \sans{node} argument is Null, the walk begins at the Root Node;
otherwise, it begins at the given \sans{node} and stops when its sub-Tree
is
exhausted.
The invoked procedure breaks the walk by returning a non-zero value (a
zero
value continues the walk); the \sans{Apply} facility returns this value
as the
walk stops. When the walk stops because it reaches the end of the
walking
sequence, Null is returned.}
\paragraph{2.1.2.4.3
UnHookNode}
The given Node, with its children, is removed from the Tree.
\bold{Synopsis}\block{ \sans{tree_UnHookNode( object, node )
struct tree
*object
struct tree_node
*node}}
\bold{Returns}\block{
Node}}
\sans{struct tree_node *}
\italic{Unhooked
\bold{Exceptions}\block{
\sans{NonExistentNode}}
\bold{Discussion}\block{
The sub-Tree rooted at the unhooked Node is
preserved, pending a subsequent \sans{HookNode} operation. Should you
elect,
you may use \sans{DestroyNode} upon it to purge the entire sub-Tree.}
\paragraph{2.1.2.4.4
HookNode}
The given Node, with its children, is placed into the Tree at the given
target
position.
\bold{Synopsis}\block{ \sans{tree_HookNode( object, node, parent_node,
left_node, right_node )
struct tree
*object
struct tree_node
*node
struct tree_node
*parent_node
struct tree_node
*left_node
struct tree_node
*right_node
\bold{Returns}\block{
Node}}
\sans{struct tree_node *}
\bold{Exceptions}\block{
UnspecifiedTargetNode,
NonExistentTargetNode}}
|
|
|
NULL
NULL
NULL}}
\italic{Hooked
\sans{NonExistentNode,
\bold{Discussion}\block{
If the Node is not in the Unhooked state,
the
\sans{Hook} operation is effectively a \sans{Move} operation. At least
one of
the targets (parent, left, and right Nodes) must be specified, otherwise
the
\sans{UnspecifiedTargetNode} exception is raised.}
\paragraph{2.1.2.4.5
MoveNode}
The given Node, with its children, is placed into the Tree at the given
target
position.
\bold{Synopsis}\block{ \sans{tree_MoveNode( object, node, parent_node,
left_node, right_node )
struct tree
*object
struct tree_node
*node
struct tree_node
*parent_node
struct tree_node
*left_node
struct tree_node
*right_node
\bold{Returns}\block{
Node}}
\sans{struct tree_node *}
\bold{Exceptions}\block{
UnspecifiedTargetNode,
NonExistentTargetNode}}
|
|
NULL
NULL
|
NULL}}
\italic{Moved
\sans{NonExistentNode,
\bold{Discussion}\block{
The \sans{Move} operation is a sequence of
the UnHook
and Hook operations. At least one of the targets (parent, left, and
right
Nodes) must be specified, otherwise the \sans{UnspecifiedTargetNode}
exception
is raised.}
\paragraph{2.1.2.4.6
DuplicateNode}
The given Node, with its children, is copied into the Tree at the given
target
position.
\bold{Synopsis}\block{ \sans{tree_DuplicateNode( object, node,
parent_node,
left_node, right_node )
struct tree
*object
struct tree_node
*node
struct tree_node
*parent_node
struct tree_node
*left_node
struct tree_node
*right_node
|
|
|
NULL
NULL
NULL}}
\bold{Returns}\block{ \sans{struct tree_node *}
\italic{Duplicated Node}}
\bold{Exceptions}\block{
UnspecifiedTargetNode,
NonExistentTargetNode}}
\sans{NonExistentNode,
\bold{Discussion}\block{
The duplicated sub-Tree will have the same
symbolic
Node Names, Captions, etc, enjoyed by the original sub-Tree; you will
likely
wish to alter these values. At least one of the targets (parent, left,
and
right Nodes) must be specified, otherwise the
\sans{UnspecifiedTargetNode}
exception is raised.}
\paragraph{2.1.2.5
Tree Dataobject Observation}
When a Tree has been modified (eg, by creation of Nodes) or a Node has
beeen
modified (eg, changing its caption), it is the Client-program's
responsibility
to request the Tree Data-object to Notify its observers, such that they
can
adjust their views accordingly.
\paragraph{2.1.2.5.1
SetNotificationCode}
Indicates the nature of the change effected upon the corresponding
Data-object.
\bold{Synopsis}\block{ \sans{tree_SetNotificationCode( object, code )
struct tree
long
*object
code}}
\bold{Returns}\block{
\sans{long}
\italic{Result-code}}
\bold{Exceptions}\block{
\sans{UnknownCode}}
\bold{Discussion}\block{
The changes are indicated by the codes --
\sans{\indent{tree_NodeCreated
tree_NodeDestroyed
tree_NodeUnhooked
tree_NodeHooked
tree_NodeNameChanged
tree_NodeCaptionChanged
tree_NodeTitleChanged
tree_NodeChildrenDestroyed
tree_NodeChildrenCreated
tree_NodeMoved
tree_NodeDuplicated}}
When then the Tree Data-object is told to Notify it's observers, the
appropriate visual updates will be effected.}
\paragraph{2.1.2.5.2
SetNotificationNode}
\subsection{2.1.3 Node Dataobject Facilities}
\paragraph{2.1.3.1
Node Dataobject Creation}
Nodes are added to the Tree through several Node creation facilities.
Each
facility allocates a Node and sets its symbolic \italic{Name} and
\italic{Item}
fields, optionally provided as arguments of each creation facility.
Connections amongst existent Nodes are modified to incorporate the newly
created Node within the Tree.
The Node creation facilities are designed to minimize Client-program
considerations. Thus, creation of a Child Node does not require
specification
of the position of the Child amongst the zero or more children of a
Parent
Node -- the Child is inserted into the Tree as the Parent's
\italic{right-most}
Child. (You may, of course, employ facilities such as
\sans{CreateRightNode}
or \sans{CreateLeftNode} to insert Nodes at specific positions.)
\paragraph{2.1.3.1.1
CreateRootNode}
Creates a Node as the Root Node.
\bold{Synopsis}\block{ \sans{tree_CreateRootNode( object, name, datum )
struct tree
*object
char
*name
long
|
datum
\bold{Returns}\block{
Identifier}}
NULL
|
NULL}}
\sans{struct tree_node *}
\bold{Exceptions}\block{
\italic{
Node
\sans{InsufficientSpace}, \sans{RootExists}}
\bold{Discussion}\block{
The Root Node must be created before any
other Nodes
can be created. If a Root Node already exists, the exception
\sans{RootExists}
is raised.}
\paragraph{2.1.3.1.2
CreateParentNode}
Creates a Node as the Parent of the given Node.
\bold{Synopsis}\block{ \sans{tree_CreateParentNode( object, name, datum,
child_node )
struct tree
*object
char
*name
long
datum
|
NULL
|
NULL
struct tree_node
*child_node}}
\bold{Returns}\block{
Identifier}}
\sans{struct tree_node *}
\bold{Exceptions}\block{
ParentNodeExists}}
\italic{Node
\sans{InsufficientSpace, NonExistentChild,
\bold{Discussion}\block{
This facility is used to build a Tree in an
\italic{upward}, rather than the usual downward direction. In
particular, it
is used to place a Node above the current Root Node (which then becomes
simply
a Child Node). Where the Child Node already has a Parent Node, the
\sans{ParentNodeExists} exception is raised; where the given Child Node
parameter is Null, xxxx}
\paragraph{2.1.3.1.3
CreateChildNode}
Creates a Node as a Child of the given Parent Node.
\bold{Synopsis}\block{ \sans{tree_CreateChildNode( object, name, datum,
parent_node )
struct tree
*object
char
*name
long
|
datum
NULL
|
NULL
struct tree_node
*parent_node}}
\bold{Returns}\block{
Identifier}}
\sans{struct tree_node *}
\bold{Exceptions}\block{
\sans{NonExistentParent}}
\italic{Node
\sans{InsufficientSpace},
\bold{Discussion}\block{
The Child Node is created as the
\italic{right-most}
child of the given Parent Node; where the Parent has no children, the
created
Node becomes its first child.}
\paragraph{2.1.3.1.4
CreateLeftNode}
Creates a Node as the Left sibling of the given Node.
\bold{Synopsis}\block{ \sans{tree_CreateLeftNode( object, name, datum,
sibling_node )
struct tree
*object
char
*name
long
|
datum
NULL
|
NULL
struct tree_node
*sibling_node}}
\bold{Returns}\block{
Identifier}}
\sans{struct tree_node *}
\bold{Exceptions}\block{
\sans{NonExistentSibling}}
\italic{Node
\sans{InsufficientSpace},
\bold{Discussion}\block{
The Sibling Node is created as the immediate
left-sibling of the given Node.}
\paragraph{2.1.3.1.5
CreateRightNode}
Creates a Node as the Right sibling of the given Node.
\bold{Synopsis}\block{ \sans{tree_CreateRightNode( object, name, datum,
sibling_node )
struct treee
char
long
*object
*name
|
datum
NULL
|
NULL
struct tree_node
*sibling_node}}
\bold{Returns}\block{
Identifier}}
\sans{struct tree_node *}
\bold{Exceptions}\block{
\sans{NonExistentSibling}}
\sans{InsufficientSpace},
\italic{Node
\bold{Discussion}\block{
The sibling Node is created as the immediate
right-sibling of the given Node.}
\paragraph{2.1.3.2
Node Dataobject Attributes}
Node attributes may be set either at compile-time, through the static
declaration of the Specification vector passed as an optional argument
to the
\sans{Create} facility, or dynamically through the
\sans{SetNodeAttribute}
facility. In most instances, the static fashion suffices.
\paragraph{2.1.3.2.1
SetNodeAttribute}
Sets the specifed attribute of the given Node to the given value.
\bold{Synopsis}\block{ \sans{tree_SetNodeAttribute( object, node,
attribute_value)
struct tree
*object
struct tree_node
*node
tree_Specification
}}
\bold{Returns}\block{
attribute_value
\sans{long} \italic{
\bold{Exceptions}\block{
Result-code.}}
None.}
\bold{Discussion}\block{
Each of the attributes listed in the section
\italic{Node Specifications} can be set either statically or dynamically.
Where the given \sans{node} is Null, the Root Node is implied. Where
the
given\sans{ attribute value} is \sans{NULL}, that Node attribute is set
to
Null. The syntax for this facility is that employed in the static
declaration
of attributes, for example -Example: \sans{tree_SetNodeAttribute( object, node, tree_NodeName(
"Packing
Dept" ) )}
}
\paragraph{2.1.3.2.2
NodeAttribute}
Yields the value of the given attribute for the given Node.
\bold{Synopsis}\block{ \sans{tree_NodeAttribute( object, node, attribute)
struct tree
*object
struct tree_node
*node
tree_Specification
}}
\bold{Returns}\block{
attribute
\sans{long} \italic{
\bold{Exceptions}\block{
Value.}}
None.}
\bold{Discussion}\block{
Each of the attributes listed in the section
\italic{Node Specifications} can be queried.
The syntax of this facility is similar to that of the SetNodeAttribute
facility, but differs in that the parenthesized argument is 0 (Null).
Example:
\sans{tree_NodeAttribute( object, tree_Name(0) )}
\sans{tree_NodeAttribute( object, tree_NodeName(0) )}
}
\paragraph{2.1.3.3
Node Dataobject Destruction}
\paragraph{2.1.3.3.1
DestroyNode}
The given Node, and all its children, is destroyed.
\bold{Synopsis}\block{ \sans{tree_DestroyNode( object, node )
struct tree
struct tree_node
*object
*node}}
\bold{Returns}\block{
\sans{long}
\italic{Result-code}}
\bold{Exceptions}\block{
\sans{NonExistentNode}}
\bold{Discussion}\block{
None.}
\paragraph{2.1.3.3.2
DestroyNodeChildren}
The children of the given Node, and all its children, are destroyed.
\bold{Synopsis}\block{ \sans{tree_DestroyNodeChildren( object, node )
struct tree
*object
struct tree_node
*node}}
\bold{Returns}\block{
\sans{long}
\italic{Result-code}}
\bold{Exceptions}\block{
\sans{NonExistentNode}}
\bold{Discussion}\block{
None.}
\paragraph{2.1.3.4
Node Dataobject Identification}
Identifiers of individual Nodes may be obtained through facilities that
walk
the Tree to locate a Node that matches a given value. These facilities
need
only be employed in those instances where particular Nodes are to be
located
-- in most instances, such as within \sans{HitHandler}s, you will find
that
the identifier of the Node passed to such procedures suffices.
Some of the identification facilities (eg, \sans{NodesOfName}) returns a
pointer to a null-terminated vector of Node identifiers; others return a
Node
identifier.
Note that where a vector is returned, it is automatically
freed
the next time a vectored list is requested.
The walk may be limited to a given sub-Tree through specification of a
starting-Node identifier; where this argument is Null, the walk begins at
the
Root Node and covers the entire Tree.
\paragraph{2.1.3.4.1
NodeOfName}
Yields Identifier of the first Node whose Symbolic Name matches the given
name.
\bold{Synopsis}\block{ \sans{tree_NodeOfName( object, name, node )
struct tree
*object
char
*name
struct tree_node
*node}}
\bold{Returns}\block{
Identifier.}}
\sans{struct tree_node *
\bold{Exceptions}\block{
}
\italic{Node
None.}
\bold{Discussion}\block{
Where no Node name matches the given name,
the value
Null is returned. Where the Null symbolic Name is given, the first Node
whose
symbolic Name is Null is returned.}
\paragraph{2.1.3.4.2
NodesOfName}
Yields Identifier(s) of the Node(s) whose symbolic Name matches the given
name.
\bold{Synopsis}\block{ \sans{tree_NodesOfName( object, name, node )
struct tree
*object
char
*name
struct tree_node
*node}}
\bold{Returns}\block{
Identifier
\sans{struct tree_node **}
\italic{
Node
vector.}}
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
Where no Node name matches the given name,
the value
Null is returned. Where the Null symbolic Name is given, Nodes whose
symbolic
Names are Null are returned.}
\paragraph{2.1.3.4.3
NodeOfDatum}
Yields Identifier of the first Node whose Datum-field matches the given
datum.
\bold{Synopsis}\block{ \sans{tree_NodeOfDatum( object, datum, node )
struct tree
long
*object
datum
struct tree_node
*node}}
\bold{Returns}\block{
Identifier.}}
\sans{struct tree_node *
\bold{Exceptions}\block{
}
\italic{Node
None.}
\bold{Discussion}\block{
Where no Node Datum attribute matches the
given
datum, the value Null is returned. Where the Null datum-value is given,
the
first Node whose Datum is Null is returned.}
\paragraph{2.1.3.4.4
NodesOfDatum}
Yields Identifier(s) of the Node(s) whose Datum matches the given datum.
\bold{Synopsis}\block{ \sans{tree_NodesOfDatum( object, datum, node )
struct tree
long
*object
datum
struct tree_node
*node}}
\bold{Returns}\block{
Identifier
vector.}}
\sans{struct tree_node **}
\bold{Exceptions}\block{
\italic{
Node
None.}
\bold{Discussion}\block{
Where no Node Datum matches the given datum,
the
value Null is returned. Where the Null datum-value is given, Nodes whose
Datum are Null are returned.}
\subsection{2.1.4 Dataobject Exception Handling}
All Tree facilities return either a \italic{result-code}, indicating the
success or failure of an operation, or a \italic{function value} such as
an
Node identifier, a scalar, or a pointer. In the former case, you may
test the
result-code for success or failure; in the latter, the Null value is
returned
for exceptional conditions. When an exception is raised, you can use the
Exception facilities to determine its nature.
You may elect to rely upon the default responses to run-time exceptions
or you
may specify a procedure to be invoked whenever such conditions are
detected.
\paragraph{2.1.4.1
SetExceptionHandler}
Sets the given procedure as the ExceptionHandler.
\bold{Synopsis}\block{ \sans{tree_SetExceptionHandler( object, procedure
)
struct tree
*object
long(*)()
}}
\bold{Returns}\block{
procedure
|
NULL
\sans{long} \italic{
Result-code}}
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
Where the \sans{procedure} is NULL, reverts
to
default Exception-handling operation.
Upon an exception, the \sans{procedure} is invoked with these arguments:
\indent{
\sans{anchor}
Tree's Anchor attribute
\sans{object}
Identifier of the Tree object
\sans{node}
Identifier of present Node
\sans{exception
}
Numeric-code
}
Where the \sans{node} argument identifies the Node (if any) for which the
exception was raised. The \sans{exception} argument is one of the codes
described in the chapter \italic{Problem Determination}.
}
\paragraph{2.1.4.2
ExceptionCode}
Yields the result-code of the most recent exception.
\bold{Synopsis}\block{ \sans{tree_ExceptionCode( object )
struct tree
*object
}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
Result-code}}
None.}
\bold{Discussion}\block{
The \sans{exception_code} is one of the
codes
described in the chapter \italic{Problem Determination}.
}
\paragraph{2.1.4.3
ExceptionNode}
Yields the identifier of the Node that suffered the most recent
exceptional
condition.
\bold{Synopsis}\block{ \sans{tree_ExceptionNode( object)
struct tree
*object
}}
\bold{Returns}\block{
identifier}}
\sans{struct tree_node *}
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
None.
\italic{
Node
}
\paragraph{2.1.4.4
SetDebug}
Sets Debugging On or Off.
\bold{Synopsis}\block{ \sans{tree_SetDebug( object, state)
struct tree
*object
boolean
state
}}
\bold{Returns}\block{
}None
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
Setting the state \sans{true} (1) initiates
tracing
of procedure calls and display of selected data. Output is to stdout.
}
\section{2.2
View Object Facilities}
These facilities deal with the Tree View-object.
\subsection{2.2.1 View Object Instantiation}
Tree View-objects are instantiated through either the \sans{Create} or
the
\sans{New} facility. Where the \sans{Create} facility is employed, you
can
override the default object attributes.
\paragraph{2.2.1.1
Create}
Creates a View-object of the class \sans{treev}. Parses the optional
Specification to establish initial attributes; reserves the requesting
object's Identifier (for subsequent call-backs).
\bold{Synopsis}\block{ \sans{treev_Create( specification, anchor )
struct treev_Specification
*specification
struct basicobject
*anchor
\bold{Returns}\block{
object
Identifier}}
|
|
NULL
NULL}}
\sans{struct treev *}
\italic{Tree View-
\bold{Exceptions}\block{
\sans{InsufficientSpace, AttributeConflict}}
\bold{Discussion}\block{
None.}
\subsection{2.2.2 Tree View Facilities}
\paragraph{2.2.2.1
Tree View Attributes}
\paragraph{2.2.2.1.1
CurrentNode}
Yields Identifier of the current Node.
\bold{Synopsis}\block{ \sans{treev_CurrentNode( object )
struct tree
*object}}
\bold{Returns}\block{
Identifier.}}
\sans{struct tree_node *
}
\italic{Node
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
Null value
is returned..}
Where no Node is currently selected, the
\paragraph{2.2.2.1.2
ChangeTreeAttribute}
Sets the specifed attribute of the Tree to the given value and
immediately
displays the results.
\bold{Synopsis}\block{ \sans{treev_ChangeTreeAttribute( object,
attribute_value)
struct tree
*object
treev_Specification
}}
\bold{Returns}\block{
attribute_value
\sans{long} \italic{
\bold{Exceptions}\block{
Result-code.}}
None.}
\bold{Discussion}\block{
Each of the attributes listed in the section
\italic{Tree Specifications} can be set either statically or dynamically.
Where the given\sans{ attribute value} is \sans{NULL}, that Tree
attribute is
set to Null. The syntax for this facility is that employed in the static
declaration of attributes, for example -Example: \sans{treev_ChangeTreeAttribute( object, tree_Arrangement(
treev_Horizontal ) )}
}
\paragraph{2.2.2.2
Tree View Manipulation}
\paragraph{2.2.2.2.1
HighlightTitle}
Highlights the Tree View Title, in the TitleHighlightStyle specified.
\bold{Synopsis}\block{ \sans{treev_HighlightTitle( object )
struct treev
*object}}
\bold{Returns}\block{
code.}}
\sans{boolean}
\italic{Result-
\bold{Exceptions}\block{
\sans{NonExistentTitle}}
\bold{Discussion}\block{
None.}
\paragraph{2.2.2.2.2
TitleHighlighted}
Yields \sans{true} if the Tree View Title is highlighted, otherwise
\sans{false}.
\bold{Synopsis}\block{ \sans{treev_TitleHighlighted( object )
struct treev
*object}}
\bold{Returns}\block{
code.}}
\sans{boolean}
\italic{Result-
\bold{Exceptions}\block{
None}
\bold{Discussion}\block{
is
returned.}
Where the Title does not exist, \sans{false}
\paragraph{2.2.2.2.3
NormalizeTitle}
Normalizes the Tree View Title.
\bold{Synopsis}\block{ \sans{treev_NormalizeTitle( object )
struct treev
*object}}
\bold{Returns}\block{
code.}}
\sans{boolean}
\italic{Result-
\bold{Exceptions}\block{
\sans{NonExistentTitle}}
\bold{Discussion}\block{
None.}
\subsection{2.2.3 Node View Facilities}
\paragraph{2.2.3.1
Node View Attributes}
\paragraph{2.2.3.1.1
ChangeNodeAttribute}
Sets the specifed attribute of the given Node to the given value and
immediately displays the results.
\bold{Synopsis}\block{ \sans{treev_ChangeNodeAttribute( object, node,
attribute_value)
struct treev
*object
struct tree_node
*node
treev_Specification
}}
\bold{Returns}\block{
attribute_value
\sans{long} \italic{
\bold{Exceptions}\block{
Result-code.}}
None.}
\bold{Discussion}\block{
Each of the attributes listed in the section
\italic{Node Specifications} can be set either statically or dynamically.
Where the given \sans{node} is Null, the Root Node is implied. Where
the
given\sans{ attribute value} is \sans{NULL}, that Node attribute is set
to
Null. The syntax for this facility is that employed in the static
declaration
of attributes, for example --
Example: \sans{treev_ChangeNodeAttribute( object, node, tree_NodeName(
"Packing Dept" ) )}
}
\paragraph{2.2.3.2
Node View Display}
Individual Nodes as well as their children can be exposed and hidden.
\paragraph{2.2.3.2.1
HideNode}
Hides the given Node and its children.
\bold{Synopsis}\block{ \sans{treev_HideNode( object, node )
struct treev
*object
struct tree_node
*node
\bold{Returns}\block{
\sans{long}
|
NULL}}
\italic{Result-code.}}
\bold{Exceptions}\block{
\sans{NonExistentNode}}
\bold{Discussion}\block{
Root Node is
implied.}
Where the given \sans{node} is Null, the
\paragraph{2.2.3.2.2
NodeExposed}
Yields \sans{true} if the given node is exposed, otherwise \sans{false}.
\bold{Synopsis}\block{ \sans{treev_NodeExposed( object, node )
struct treev
*object
struct tree_node
*node
|
NULL}}
\bold{Returns}\block{\sans{ boolean}
code.}}
\bold{Exceptions}\block{
\italic{Result-
\sans{NonExistentNode}}
\bold{Discussion}\block{
Root Node is
implied.}
\paragraph{2.2.3.2.3
Where the given \sans{node} is Null, the
ExposeNode}
Exposes the given Node and its immediate children.
\bold{Synopsis}\block{ \sans{treev_ExposeNode( object, node )
struct treev
*object
struct tree_node
*node
\bold{Returns}\block{
\sans{long}
|
NULL}}
\italic{Result-code.}}
\bold{Exceptions}\block{
\sans{NonExistentNode}}
\bold{Discussion}\block{
Root Node is
implied.}
Where the given \sans{node} is Null, the
\paragraph{2.2.3.2.4
HideNodeChildren}
Hides the given Node's immediate children, and their children.
\bold{Synopsis}\block{ \sans{treev_HideNodeChildren( object, node )
struct treev
*object
struct tree_node
*node
\bold{Returns}\block{
\sans{long}
\bold{Exceptions}\block{
|
NULL}}
\italic{Result-code.}}
\sans{NonExistentNode, UnexposedNode}}
\bold{Discussion}\block{
Where the given \sans{node} is Null, the
Root Node is
implied. The given Node must itself be exposed, otherwise the operation
is
null.}
\paragraph{2.2.3.2.5
NodeChildrenExposed}
Yields \sans{true} if the given node's children are exposed, otherwise
\sans{false}.
\bold{Synopsis}\block{ \sans{treev_NodeChildrenExposed( object, node )
struct treev
*object
struct tree_node
*node
\bold{Returns}\block{
code.}}
\sans{boolean}
|
NULL}}
\italic{Result-
\bold{Exceptions}\block{
\sans{NonExistentNode}}
\bold{Discussion}\block{
Root Node is
implied.}
Where the given \sans{node} is Null, the
\paragraph{2.2.3.2.6
ExposeNodeChildren}
Exposes the given Node's immediate children.
\bold{Synopsis}\block{ \sans{treev_ExposeNodeChildren( object, node )
struct treev
*object
struct tree_node
*node
\bold{Returns}\block{
\sans{long}
\bold{Exceptions}\block{
|
NULL}}
\italic{Result-code.}}
\sans{NonExistentNode, UnexposedNode}}
\bold{Discussion}\block{
Where the given \sans{node} is Null, the
Root Node is
implied. The given Node must itself be exposed, otherwise the operation
is
null.}
\paragraph{2.2.3.2.7
ExplodeNode}
Exposes the given Node and all its children and their children, etc.
\bold{Synopsis}\block{ \sans{treev_ExplodeNode( object, node )
struct treev
*object
struct tree_node
*node
\bold{Returns}\block{
\sans{long}
|
NULL}}
\italic{Result-code.}}
\bold{Exceptions}\block{
\sans{NonExistentNode}}
\bold{Discussion}\block{
Root Node is
implied.}
Where the given \sans{node} is Null, the
\paragraph{2.2.3.2.8
ImplodeNode}
Hides the given Node's children and their children, etc.
\bold{Synopsis}\block{ \sans{treev_ImplodeNode( object, node )
struct treev
*object
struct tree_node
*node
\bold{Returns}\block{
\sans{long}
|
NULL}}
\italic{Result-code.}}
\bold{Exceptions}\block{
\sans{NonExistentNode}}
\bold{Discussion}\block{
Root Node is
implied.}
Where the given \sans{node} is Null, the
\paragraph{2.2.3.3
Node View Selection}
Nodes are selected by the User through mouse-hits within their borders.
In
general, control is passed for all mouse-actions; see the
\italic{Concepts}
discussion regarding HitHandlers.
\paragraph{2.2.3.3.1
HighlightNode}
Highlights the given Node.
\bold{Synopsis}\block{ \sans{treev_HighlightNode( object, node )
struct treev
*object
struct tree_node
*node
\bold{Returns}\block{
code.}}
\sans{boolean}
\bold{Exceptions}\block{
|
NULL}}
\italic{Result-
\sans{NonExistentNode}}
\bold{Discussion}\block{
Where the given \sans{node} is Null, the
Root Node is
implied. Any other highlighted Node is normalized.}
\paragraph{2.2.3.3.2
NodeHighlighted}
Yields \sans{true} if the given node is highlighted, otherwise
\sans{false}.
\bold{Synopsis}\block{ \sans{treev_NodeHighlighted( object, node )
struct treev
*object
struct tree_node
*node
\bold{Returns}\block{
code.}}
\sans{boolean}
|
NULL}}
\italic{Result-
\bold{Exceptions}\block{
\sans{NonExistentNode}}
\bold{Discussion}\block{
Root Node is
implied.}
Where the given \sans{node} is Null, the
\paragraph{2.2.3.3.3
NormalizeNode}
Normalizes the given Node.
\bold{Synopsis}\block{ \sans{treev_NormalizeNode( object, node )
struct treev
*object
struct tree_node
*node
\bold{Returns}\block{
code.}}
\sans{boolean}
|
NULL}}
\italic{Result-
\bold{Exceptions}\block{
\sans{NonExistentNode}}
\bold{Discussion}\block{
Root Node is
implied.}
Where the given \sans{node} is Null, the
\paragraph{2.2.3.3.4
HighlightNodeTitle}
Highlights the given Node's title.
\bold{Synopsis}\block{ \sans{treev_HighlightNodeTitle( object, node )
struct treev
*object
struct tree_node
*node
\bold{Returns}\block{
code.}}
|
NULL}}
\sans{boolean}
\bold{Exceptions}\block{
\italic{Result-
\sans{NonExistentNode}}
\bold{Discussion}\block{
Where the given \sans{node} is Null, the
Root Node is
implied. Any other highlighted Node is normalized.}
\paragraph{2.2.3.3.5
NodeTitleHighlighted}
Yields \sans{true} if the given Node's title is highlighted, otherwise
\sans{false}.
\bold{Synopsis}\block{ \sans{treev_NodeTitleHighlighted( object, node )
struct treev
*object
struct tree_node
*node
|
NULL}}
\bold{Returns}\block{ \sans{ boolean}
code.}}
\italic{Result-
\bold{Exceptions}\block{
\sans{NonExistentNode}}
\bold{Discussion}\block{
Root Node is
implied.}
Where the given \sans{node} is Null, the
\paragraph{2.2.3.3.6
NormalizeNodeTitle}
Normalizes the given Node's title.
\bold{Synopsis}\block{ \sans{treev_NormalizeNodeTitle( object, node )
struct treev *
object
struct tree_node *
node
\bold{Returns}\block{
code.}}
\sans{boolean}
|
NULL}}
\italic{Result-
\bold{Exceptions}\block{
\sans{NonExistentNode}}
\bold{Discussion}\block{
Root Node is
implied.}
Where the given \sans{node} is Null, the
\subsection{2.2.4 View Exception Handling}
All Tree facilities return either a \italic{result-code}, indicating the
success or failure of an operation, or a \italic{function value} such as
an
Node identifier, a scalar, or a pointer. In the former case, you may
test the
result-code for success or failure; in the latter, the Null value is
returned
for exceptional conditions. When an exception is raised, you can use the
Exception facilities to determine its nature.
You may elect to rely upon the default responses to run-time exceptions
or you
may specify a procedure to be invoked whenever such conditions are
detected.
\paragraph{2.2.4.1
SetExceptionHandler}
Sets the given procedure as the ExceptionHandler.
\bold{Synopsis}\block{ \sans{treev_SetExceptionHandler( object, procedure
)
struct treev
long(*)()
}}
\bold{Returns}\block{
*object
procedure
|
NULL
\sans{long} \italic{
\bold{Exceptions}\block{
Result-code}}
None.}
\bold{Discussion}\block{
Where the \sans{procedure} is NULL, reverts
to
default Exception-handling operation.
Upon an exception, the \sans{procedure} is invoked with these arguments:
\sans{\leftindent{anchor}}\leftindent{
\sans{object}
\sans{node}
}\sans{\leftindent{exception_code}}
Where the \sans{node} argument identifies the Node (if any) for which the
exception was raised. The \sans{exception_code} argument is one of the
codes
described in the chapter \italic{Problem Determination}.
}
\paragraph{2.2.4.2
ExceptionCode}
Yields the result-code of the most recent exception.
\bold{Synopsis}\block{ \sans{treev_ExceptionCode( object,)
struct treev
*object
}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
Result-code}}
None.}
\bold{Discussion}\block{
The \sans{exception_code} is one of the
codes
described in the chapter \italic{Problem Determination}.
}
\paragraph{2.2.4.3
ExceptionNode}
Yields the identifier of the Node that suffered the most recent
exceptional
condition.
\bold{Synopsis}\block{ \sans{treev_ExceptionNode( object)
struct treev
*object
}}
\bold{Returns}\block{
identifier}}
\sans{struct tree_node *}
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
None.
}
\paragraph{2.2.4.4
SetDebug}
\italic{
Node
Sets Debugging On or Off.
\bold{Synopsis}\block{ \sans{treev_SetDebug( object, state)
struct treev
*object
boolean
}}
\bold{Returns}\block{
state
}None
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
Setting the state \sans{true} (1) initiates
tracing
of procedure calls and display of selected data. Output is to stdout.
}
\begindata{bp,538271432}
\enddata{bp,538271432}
\view{bpv,538271432,1350,0,0}
\chapter{3 Sample Programs}
Rather diverse displays can be developed for Trees. A potpourri to
stimulate
the imagination:
\center{
*********************************
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*********************************
}
See \italic{Sample Programs}, following.
\begindata{bp,538929032}
\enddata{bp,538929032}
\view{bpv,538929032,1351,0,0}
\begindata{bp,538929736}
\enddata{bp,538929736}
\view{bpv,538929736,1352,0,0}
\chapter{4 Problem Determination}
Compile-time problems are usually merely syntactic difficulties, and
these
would most likely occur in the declaration of a Specification structure
vector. That structure is built up through macros, which expect single
arguments. In particular, be sure to use Null as the last item in the
vector.
Run-time problems can occur at several points:
\indent{When creating the Tree or treev object;
When setting Tree or Node Attributes;
Within HitHandlers.}
All Tree facilities return either an identifier, a scalar, or a Resultcode.
Where a Result-code is returned, it should assist you in tracking down
the
difficulty. Where an identifier or other value is returned, you can
still
access a exception-code that should aid in problem determination. Such a
code, as well as other information, is available through the
\sans{Exception}
facilities; see the section \italic{Exception Handling}.
There is also a built-in tracing feature, used primarily for development.
You
can turn it on and off via the \sans{SetDebug} facility.
\bold{Exception Codes}
\sans{NonExistentNode}
\sans{InsufficientSpace}
\sans{AttributeConflict}
xxx
\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,1354,0,0}
Copyright 1992 Carnegie Mellon University and IBM.
All rights reserved.
\smaller{\smaller{$Disclaimer:
Permission to use, copy, modify, and distribute this software and its
documentation for any purpose and without fee is hereby granted, provided
that the above copyright notice appear in all copies and that both that
copyright notice and this permission notice appear in supporting
documentation, and that the name of IBM not be used in advertising or
publicity pertaining to distribution of the software without specific,
written prior permission.
THE COPYRIGHT HOLDERS DISCLAIM ALL WARRANTIES WITH REGARD
TO THIS SOFTWARE, INCLUDING ALL IMPLIED WARRANTIES OF
MERCHANTABILITY AND FITNESS. IN NO EVENT SHALL ANY COPYRIGHT
HOLDER BE LIABLE FOR ANY SPECIAL, INDIRECT OR CONSEQUENTIAL
DAMAGES OR ANY DAMAGES WHATSOEVER RESULTING FROM LOSS OF USE,
DATA OR PROFITS, WHETHER IN AN ACTION OF CONTRACT, NEGLIGENCE
OR OTHER TORTIOUS ACTION, ARISING OUT OF OR IN CONNECTION
WITH THE USE OR PERFORMANCE OF THIS SOFTWARE.
$
}}\enddata{text,538476484}