\begindata{text,538429064}
\textdsversion{12}
\template{default}
\define{programexample
menu:[Region,ProgramExample]
attr:[Justification LeftJustified Point 0]
attr:[FontFamily Helvetica Int 0]}
\define{itemize
menu:[Region,Itemize]
attr:[LeftMargin LeftMargin Inch 32768]}
\define{enumerate
menu:[Region,Enumerate]
attr:[LeftMargin LeftMargin Inch 32768]}
\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]}
\center{
\bigger{\bigger{\bold{\bigger{\bigger{Org}}
Programming Guide}}}
Version
1.0
(ATK Version 11.7)
Information Technology Center
Carnegie Mellon University
TC Peters
(1/19/89)
8/23/89
\bold{(c) IBM Corporation
1989}}
\passthrough{.bp}
\bold{Preface}
This document presents the Concepts and Facilities of the \bold{Org}
class.
This class provides facilities to develop, edit, and print hierarchical
diagrams, sometimes known as \italic{Organization Charts}.
The \bold{Org} and \bold{Orgv} classes are sub-classes of the
\italic{apt}
and \italic{aptv class} (see the\italic{ Apt Programming Guide} for
details
regarding built-in Iconification, Help, and other common features). The
class provides both a Data-object (\bold{org}) and a View-object
(\bold{\sans{orgv).}} \sans{Org} supports the standard Data-object
operations (Read, Write, etc); \sans{Orgv} supports the standard View
class operations, such as FullUpdate, ReceiveInputFocus, Update, etc,
including the Print operation.
Together, \sans{org} and \sans{orgv} constitute an \italic{Inset}. As
such, they can be inserted into documents and employed by other classes.
Additionally, the \sans{Org} \italic{Application} is provided, to
support
stand-alone usage. Although the Org Inset is primarily intended to be
employed by Users as an editable Inset, it can also be used by
Client-programs to effect parochial display and interaction with Org
Datastreams. (This approach is an alternate to employing the Tree Class
directly.)
\passthrough{.bp}
\bold{Introduction}
The Org class (\sans{org} and \sans{orgv}) utilizes the Tree class
(\sans{tree} and \sans{treev}) along with the Text class (\sans{text} and
\sans{textv}) to facilitate manipulation of visual \italic{Organization
Charts}, with attendant \italic{Descriptive Text} optionally associated
with individual nodes.
Org employs the facilities of the Tree class to build tree structures and
to present them both on screen and as printed objects; it uses features
of
the Tree class to support interactive editing of such trees. Descriptive
text associated with each node is edited through the usual text editing
features (including the insertion of imbedded objects).
When it has the InputFocus, Org provides Menu-actions that support User
editing of the Org Datastream.
\passthrough{.bp}
\chapter{1 Concepts}
The Org class comprises an \italic{Inset}: it is designed to be employed
as
an editable object within a document. As an editable object, it provides
the standard ATK support for reading, writing, displaying, and printing
of
its Datastream. (It is thus employed by EZ -- ie, the Text object -- in
the same manner any other imbedded object is manipulated.)
As well as operating upon a Datastream imbedded within a document, Org
can
be employed by a Client-program that itself generates such a Datastream.
When used in this manner, the Client can request that certain User
actions
(such as selecting a Node in the displayed Tree) be passed onto the
Client
for special responses -- effectively employing the Tree Display as a
hierarchic menu facility.
The Org class interface is rather narrow, unlike the Tree Class interface
-- which provides full access to the Tree structure itself and its
view(s).
\bold{Hit Handling}
Whereas the Org class provides appropriate housekeeeping to reflect User
interaction with a Org through its view, it is the Client-program's
\italic{Hit Handler}s (also known as "call-back procedures") that effect
whatever functionality such interaction implies. Upon invocation, a Hit
Handler is passed these arguments:
\indent{
\bold{Argument-1:}
The Client-program Anchor associated with the Org (as provided via the
\sans{orgv_SetHitHandler} facility).
\bold{Argument-2:}
Identifier of the Org.
\bold{Argument-3:}
Identifier of the object hit.
\bold{Arguments 4-7: }\
Standard ATK Mouse information -- action, x, y, clicks.}
Thus, a typical Hit Handler would be written:
\indent{\sans{My_Hit_Handler( self, org, object, action, x, y, clicks )}}
(The parameter \sans{self} is the value specified as the \italic{Anchor}
by
the Client-program via \sans{orgv_SetHitHandler}.)
All mouse-actions are passed through.
\bold{Printing}
Printed output is in PostScript format.
(At this time, due to the absence of \italic{PostScript} printing support
within the Text object, only the Tree object is printed.)
\passthrough{.bp}
\chapter{2 Facilities}
Facilities are ClassProcedures, Methods, or MacroMethods provided by a
Class to facilitate communication between an object and its creator.
The facilities are presented in a standard style:
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 given; 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{orgv_SetHitHandler( \italic{object},
\italic{handler},
\italic{anchor} );}}}
\indent{
where :
\sans{\bold{object}}
is the Identifier of the instance of the Class (as returned from the
\sans{org_New} facility);
\sans{\bold{handler}}
is a pointer to a procedure;
\bold{\sans{anchor}}
is the identifier of the requesting object instance.
}
o All symbolic-names are prefixed with the character "\sans{org_}"
"\sans{orgv_}" to preclude name-clashes with Client-program names.}
\section{2.1
or
Data-object Facilities}
The Org Data-object is instantiated via the standard ATK facility
\sans{org_New}, which returns a pointer to an Org Data-object.
\subsection{2.1.1 SetFileName}
Sets the name of the Org Datastream file to the specified name..
\bold{Synopsis}\block{ \sans{org_SetFileName( object, name)
struct org
char
*object
*name}}
\bold{Returns}\block{
\sans{long} \italic{
Result-code.}}
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
which
The FileName is used to identify the file in
the Org Datastream exists. The name is emplyed both to locate the fiel
and
in constructing Back-up versions thereof.}
\subsection{2.1.2 FileName}
Yields the name of the Org Datastream file.
\bold{Synopsis}\block{ \sans{org_FileName( object )
struct org
*object}}
\bold{Returns}\block{
\sans{char} \italic{
\bold{Exceptions}\block{
*File-name.}}
None.}
\bold{Discussion}\block{
Where the Org Datastream is one imbedded
within a
document, the name is Null..}
\subsection{2.1.3 NodeName}
Yields the name of the given Node.
\bold{Synopsis}\block{ \sans{org_NodeName( object, node )
struct org
*object
struct tree_node
*node}}
\bold{Returns}\block{
\sans{char} \italic{
\bold{Exceptions}\block{
*Node-name.}}
None.}
\bold{Discussion}\block{
Usually employed to obtain the name of the
\sans{CurrentNode} (which see, under \italic{View-object Facilities}).}
\section{2.2
View-object Facilities}
The Org View-object is instantiated via the standard ATK facility
\sans{orgv_New}, which returns a pointer to an Org View-object.
\subsection{2.2.1 SetHitHandler}
Sets the HitHandler to the specified procedure.
\bold{Synopsis}\block{ \sans{orgv_SetHitHandler( object, proc, anchor)
struct orgv
*object
long
(*proc)()
long
anchor}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
Result-code.}}
None.}
\bold{Discussion}\block{
When a HitHandler is established, all
mouse-actions affecting the Org View-object are passed through to the
specified procedure. (See \italic{Concepts, Hit Handlers}.)}
\subsection{2.2.2 CurrentNode}
Yields the identifier of the currently selected Node
\bold{Synopsis}\block{ \sans{orgv_CurrentNode( object )
struct orgv
*object}}
\bold{Returns}\block{
identifier.}}
\sans{struct tree_node}\italic{
*Node-
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
Null is
returned.}
Where there is no currently selected Node,
\passthrough{.bp}
\chapter{3 Datastream Structure}
Organization Charts are materialized as ATK Datastreams. (Org will
accept
such streams with or without the standard "\sans{\\begindata}" and
"\sans{\\enddata}" enclosures.)
The Org Datastream is a linear representation of a hierarchy, within
which
each Node is represented through its Name along with any associated
Descriptive Text. In its simplest form, with no Descriptive Text, an Org
Datastream appears thus -\indent{
\sans{\\begindata\{org,268631143\}}
The Art of Cooking
\{
Appetizers
Entrees
\{
Vegetarian
Carnivorous
\}
Deserts
Wines
Liquours
\}
\sans{\\enddata\{org,268631143\}}
}
This stream represents the hierarchic structure implied by a typical
\italic{Table of Contents}:
\indent{\bold{
The Art of Cooking
Appetizers
Entrees
Vegetarian
Carnivorous
Deserts
Wines
Liquours
}}
(Obviously, as yet a rather incomplete book.)
As illustrated, the Root-node (\italic{The Art of Cooking}) appears
first;
directly following is a \bold{braced} sequence of its immediate children
(\italic{Appetizers}, \italic{Entrees}, \italic{Deserts}, and
\italic{Wines}); only the \italic{Entrees} child has itself any children
-- and these appear directly following it within braces
(\italic{Vegetarian
}and \italic{Carnivorous}). The hierarchic structure is, accordingly,
fully represented by \italic{nested balanced braces}.
\passthrough{.bp}
To carry the illustration a step further, assume the author began to
flesh
out the \italic{Deserts} chapter -\indent{
\sans{\\begindata\{org,268622155\}}
The Art of Cooking
\{
Appetizers
Entrees
\{
Vegetarian
Carnivorous
\}
Deserts
\{
Chocolates
Others
\{
Cakes
Pies
Ice Cream
\{
Chocolate
Vanilla
Strawberry
\}
\}
\}
Wines
Liquours
\}
\sans{\\enddata\{org,268622155\}}
}
This stream represents the expanded \italic{Table of Contents}:
\indent{\bold{
The Art of Cooking
Appetizers
Entrees
Vegetarian
Carnivorous
Deserts
Chocolates
Others
Cakes
Pies
Ice Cream
Chocolate
Vanilla
Strawberry
Wines
Liquours
}}
Finally, to emphasize the hierarchic structuring, the same \italic{Table
of
Contents} with the usual Dewey Decimal numbering:
\indent{\bold{
The Art of Cooking
1
Appetizers
2
Entrees
2.1
Vegetarian
2.2
Carnivorous
3
Deserts
3.1
Chocolates
3.2
Others
3.2.1
Cakes
3.2.2
Pies
3.2.3
Ice Cream
3.2.3.1
Chocolate
3.2.3.2
Vanilla
3.2.3.3
Strawberry
4
Wines
5
Liquours
}}
\passthrough{.bp}
Reverting to the original simple structure, we find the author has
entered
some \italic{Descriptive Text} to the \italic{Deserts} chapter -\indent{
\sans{\\begindata\{org,268697100\}}
The Art of Cooking
\{
Appetizers
Entrees
\{
Vegetarian
Carnivorous
\}
Deserts
[118
\sans{\\begindata\{text,268796564\}}
\\textdsversion\{12\}
\\template\{default\}
The best part of the Meal.\\
\sans{\\enddata\{text,268796564\}}
]
Wines
Liquours
\}
\sans{\\enddata\{org,268697100\}}
}
Immediately following the Deserts Node are several lines that capture the
Description thus far entered: enclosed within balanced \bold{brackets}
is
a normal Text Datastream. The number (\italic{118}) immediately
following
the opening bracket indicates the count of characters, up to the closing
bracket, comprising the associated Descriptive Text Datastream.
Other examples include: \
\begindata{link,539692296}
Datastream version: 3
$ANDREWDIR/doc/atk/org/example1.org
0
0
\begindata{link,539692296}
Datastream version: 2
example1
2
black
white
\enddata{link,539692296}
\enddata{link,539692296}
\view{linkview,539692296,1,0,0} example1.org - Org example
\begindata{link,539814312}
Datastream version: 3
$ANDREWDIR/doc/atk/org/example2.org
0
0
\begindata{link,539814312}
Datastream version: 2
example2
2
black
white
\enddata{link,539814312}
\enddata{link,539814312}
\view{linkview,539814312,2,0,0} example2.org - Org example
\begindata{link,539814920}
Datastream version: 3
$ANDREWDIR/doc/atk/org/example3.org
0
0
\begindata{link,539814920}
Datastream version: 2
example3
2
black
white
\enddata{link,539814920}
\enddata{link,539814920}
\view{linkview,539814920,3,0,0} example3.org - Org example
\begindata{bp,539393448}
Version 2
n 0
\enddata{bp,539393448}
\view{bpv,539393448,0,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,538429064}