\begindata{text,538290028}
\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{styingg}
\passthrough{.bp}
\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{ Working Draft }
\bold{SUBJECT
TO
SIGNIFICANT
REVISION }
\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 Clientprograms
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
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{
\bold{Exceptions}\block{
None.}
Result-code.}}
or
\bold{Discussion}\block{
The FileName is used to identify the file in
which
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 mouseactions
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
Where there is no currently selected Node,
returned.}
\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.
\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,536,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 is hereby granted without fee,
provided that the above copyright notice appear in all copies and that
both that copyright notice, this permission notice, and the following
disclaimer appear in supporting documentation, and that the names of
IBM, Carnegie Mellon University, and other copyright holders, not be
used in advertising or publicity pertaining to distribution of the
software
without specific, written prior permission.
IBM, CARNEGIE MELLON UNIVERSITY, AND THE OTHER COPYRIGHT HOLDERS
DISCLAIM ALL WARRANTIES WITH REGARD TO THIS SOFTWARE, INCLUDING
ALL IMPLIED WARRANTIES OF MERCHANTABILITY AND FITNESS.
IN NO EVENT
SHALL IBM, CARNEGIE MELLON UNIVERSITY, OR ANY OTHER 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,538290028}