\begindata{text,538882080}
\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}
\begindata{bp,538929032}
\enddata{bp,538929032}
\view{bpv,538929032,1355,0,0}
\center{
\bigger{\bigger{\bold{\bigger{\bigger{Suite}}
Programming Guide}}}
Version
1.0
(ATK Version 11.7)
Information Technology Center
Carnegie Mellon University
TC Peters
GW Keim
(12/22/88)
9/8/89
\bold{ Working Draft }
\bold{SUBJECT
TO
SIGNIFICANT
\bold{(c) IBM Corporation
REVISION }
1989}}
\begindata{bp,538271432}
\enddata{bp,538271432}
\view{bpv,538271432,1356,0,0}
\bold{Preface}
This document presents the Concepts and Facilities of the \bold{Suite}
class.
This class provides interactive views that can be employed to display
visuals
known as \italic{Buttons}, \italic{Lists}, \italic{Catalogs},
\italic{Dialogs}, etc. Although these uses differ in certain
characteristics
(viz, various display techniques), their format and substance are
sufficiently
similar to permit a single Inset to satisfy their diverse needs.
The \bold{Suite} class is a sub-class of the \italic{aptv class} (see
the\italic{ Apt Programming Guide} for details regarding built-in
Iconification, Help, and other common features). The class provides a
View-object (\bold{\sans{suite}}) -- it supports the standard View
operations,
such as FullUpdate, ReceiveInputFocus, Update, etc. As a generic class,
it is
meant to be used by client-programs to provide a variety of interactive
visual
interfaces to suites of items.
\begindata{bp,538271496}
\enddata{bp,538271496}
\view{bpv,538271496,1357,0,0}
\bold{Introduction}
The Suite class provides highly tailorable 2-dimensional layouts of items
that
may be presented visually as suites of Buttons or Lists. The distinction
between Buttons and Lists is nominal: both may be formatted across
multiple
Rows and Columns; both may be scrolled; both may be Titled; etc.
A Suite is a view drawn in the rectangle specified by the client-program
in
the normal ATK -- viz, through \sans{InsertView}.
\description{o
Items.}
The Suite may be \italic{Titled}, as may each of its
\description{o Each Item may be a simple caption or any ATK
\italic{Inset}.}
\description{o The style of the Suite's \italic{Border}, as well as each
Item, may be specified.}
\description{o Items may be automatically \italic{scaled} or given a
\italic{fixed sizing}.}
\description{o
individually
specified.}
\italic{Fonts} for titles and captions may be
o
Client-program interaction via the Suite Title and Items is provided via
\italic{call-back}, which provides the client-program with control over
the
manner in which the user interacts with the Suite.
\begindata{bp,538271624}
\enddata{bp,538271624}
\view{bpv,538271624,1358,0,0}
\chapter{1 Concepts}
The \bold{suite} class supports interactive views upon \italic{Suites} of
zero
or more \italic{Items}. The Suite visual is an optionally bordered
rectangle;
this area is termed the \italic{Container}. Suite Items are arranged
within
the Container in various fashions, as specified by the Client-program.
\center{
*********************************
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
CONTAINER
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*
*********************************
}
\begindata{bp,538269640}
\enddata{bp,538269640}
\view{bpv,538269640,1359,0,0}
You can set various attributes to tailor the manner in which a Suite and
its
Items are displayed and manipulated. Note, however, that all have
defaults
that should yield acceptable formatting. You should begin with the
defaults,
and subsequently try experimenting with the attributes.
sample
program in the section \italic{Examples}.)
Some typical Suite views:
\center{
\begindata{zip,539485448}
%ViewWidth 436
%ViewHeight 388
*G;-675,675
G10
>-325,525
*D;-1000,1400
N8.5X11
>-1000,1400
*G;-1300,1300
>-200,100
*G;-1200,1000
>-800,800
*G;-700,1000
>-300,800
*G;-1200,700
>-800,500
*G;-700,700
>-300,500
*G;-1200,400
>-800,200
*G;-700,400
>-300,200
*A;-750,1150
Fandysans10b
TColor Choices
MCM
*A;-1000,900
Fandysans8b
TRed
MCM
*A;-1000,600
Fandysans8b
TGreen
MCM
*A;-1000,300
Fandysans8b
TBlue
MCM
*A;-500,900
Fandysans8b
TYellow
MCM
*A;-500,300
Fandysans8b
TWhite
(See the first
MCM
*A;-500,600
Fandysans8b
TBlack
MCM
*G;100,1200
>1300,-800
*D;100,1000
>1300,1000
*A;700,1100
THistorical Topics
MCM
*A;400,900
Fandy8
TArt
MLM
*A;400,800
Fandy8
TBiography
MLM
*A;400,700
Fandy8
TContentions
MLM
*A;400,600
Fandy8
TDiversions
MLM
*A;400,500
Fandy8
TEconomies
MLM
*A;400,400
Fandy8
TFood
MLM
*A;400,300
Fandy8b
TGround Coverage
MLM
*A;400,200
Fandy8
THonors
MLM
*A;400,100
Fandy8
TIncidents
MLM
*A;400,0
Fandy8
TJustice
MLM
*A;400,-100
Fandy8
TK...
MLM
*A;400,-200
Fandy8
TLabor
MLM
*A;400,-300
Fandy8i
TMaterials
MLM
*A;400,-400
Fandy8i
TNonsense Happenings
MLM
*A;400,-500
Fandy8
TOpportunities
MLM
*A;400,-600
Fandy8
TPeasants
MLM
*C;-1200,0
>-100,0
*C;-1200,-1300
>1200,-1300
*C;0,-100
>0,-600
*C;-1300,-100
>-1300,-600
*C;-1200,-700
>-100,-700
*M;-1200,-100
>-1300,-100;-1200,0;100,100
*M;-1200,-600
>-1200,-700;-1300,-600;100,100
*M;-100,-600
>0,-600;-100,-700;100,100
*M;-100,-100
>-100,0;0,-100;100,100
*A;-1200,-100
Fandysans8
TAlpha
MLM
*A;-1200,-200
Fandysans8
TBeta
MLM
*A;-1200,-300
Fandysans8
TGamma
MLM
*A;-1200,-400
Fandysans8
TDelta
MLM
*A;-1200,-500
Fandysans8
TEpsilon
MLM
*A;-1200,-600
Fandysans8
TZeta
MLM
*A;-800,-100
Fandysans8
TEta
MLM
*A;-800,-200
Fandysans8
TTheta
MLM
*A;-800,-300
Fandysans8b
TIota
MLM
*A;-800,-400
Fandysans8b
TLambda
MLM
*A;-800,-500
Fandysans8b
TMu
MLM
*A;-800,-600
Fandysans8b
TNu
MLM
*A;-400,-100
Fandysans8b
TOmicron
MLM
*A;-400,-200
Fandysans8b
TPi
MLM
*A;-400,-300
Fandysans8
TRho
MLM
*A;-400,-400
Fandysans8
TSigma
MLM
*A;-400,-500
Fandysans8
TTau
MLM
*C;-1200,-900
>1200,-900
*C;1300,-1000
>1300,-1200
*C;-1300,-1000
>-1300,-1200
*M;1200,-1000
>1200,-900;1300,-1000;100,100
*M;1200,-1200
>1300,-1200;1200,-1300;100,100
*M;-1200,-1200
>-1200,-1300;-1300,-1200;100,100
*J;-500,-1100
>100,0
*J;-100,-1100
>100,0
*J;300,-1100
>100,0
*J;700,-1100
G10
>100,0
*J;1100,-1100
>100,0
*A;-500,-1100
Fandysans10b
T1
MCM
*A;-100,-1100
Fandysans10b
T2
MCM
*A;300,-1100
Fandysans10b
T3
MCM
*A;700,-1100
Fandysans10b
T4
MCM
*A;1100,-1100
Fandysans10b
T5
MCM
*A;-1264,-1073
Fandysans12
TPositioning
MLM
*A;400,-700
Fandy8i
TQuarrels
MLM
*M;-1200,-1000
>-1300,-1000;-1200,-900;100,100
*N;-1482,-609
G1
>-381,-918
*A;-1427,-763
Fandy10b
TName:
MLM
*G;100,1000
G50
>250,-800
*G;100,1000
G20
>250,900
*G;100,-700
G20
>250,-800
*G;114,850
G1
>236,350
\enddata{zip,539485448}
\view{zipview,539485448,1360,0,0}
}
(See the section \italic{Samples} for additional Suite visuals.)
The simplest way to use the Suite class is through statically declared
attributes. All that is needed is the set of \italic{Items} to be
displayed
and the name of a\italic{ procedure} to be invoked whenever the User
selects
an Item. Beyond this simple -- and often adequate -- style of usage, you
can
control all the display and interaction attributes through various
\italic{specifications}. You can also generate and modify the Suite and
its
Items \italic{dynamically}, to deal with special considerations found in
your
program: all the Suite and Item attributes can be set or queried through
attribute-access facilities.
\begindata{bp,538930120}
\enddata{bp,538930120}
\view{bpv,538930120,1361,0,0}
By way of example, the following is a complete program
(\italic{\sans{suitex1a}}) employing the Suite class. Its functionality
is
rather simple: it prints the name of the flavor clicked.
\sans{\leftindent{#include
"im.ih"
#include
"suite.ih"
#include
"suitex1a.eh"
struct view
*Flavor_Choice();
char
*list []
=
\{ "Vanilla","Strawberry","Chocolate",
"Grape","Fudge", "Licorice",
"Caramel","Lemon","Orange", NULL \};
suite_Specification
flavors[] =
\{ suite_HitHandler( Flavor_Choice ),
suite_ItemCaptionList ( list ),
NULL
\};
boolean
suitex1app__Start( self )
struct suitex1app
*self;
\{
im_SetView( im_Create(NULL), suite_Create( flavors, self ) );
return TRUE;
\}
void
Flavor_Choice( self, suite, item, type, action, x, y, clicks )
struct suitex1app
*self;
register struct suite
*suite;
register struct suite_item
*item;
\{
printf( "Chosen Flavor is %s\\n",
suite_ItemAttribute( suite, item, suite_ItemCaption(0) ) );
\}
}}
The class-header file for this example is
--
\sans{\leftindent{class suitex1app [suitex1a]: application [app]
\{
overrides:
Start()
returns boolean;
\};}}
Attributes are discussed in the sections \italic{Suite Attributes} and
\italic{Item Attributes}. Other sections detail usage of interactive
programming through \italic{Handlers}, procedures that react to User
selection
of one or more Items.
\section{1.1
Features}
The Suite class provides numerous featrues to support many differnent
visual
effects.
\subsection{1.1.1 Arrangements}
Suite may be arranged in numerous fashions, as specified via the
\sans{suite_Arrangement} attribute.
Given the Items \italic{Alpha},\italic{ Beta},\italic{ Gamma},\italic{
Delta},
and\italic{ Epsilon}, various arrangements would be:
\center{
\begindata{zip,539485192}
%ViewWidth 355
%ViewHeight 288
*D;-1000,1400
N8.5X11
>-1000,1400
*G;-1600,1300
>-500,300
*G;-1500,1200
>-1100,1000
*G;-1500,900
>-1100,700
*G;-1000,1200
>-600,1000
*G;-1000,900
>-600,700
*G;-1250,600
>-850,400
*A;-1300,1100
Fandysans8b
TAlpha
MCM
*A;-1300,800
Fandysans8b
TBeta
MCM
*A;-800,1100
Fandysans8b
TGamma
MCM
*A;-800,800
Fandysans8b
TDelta
MCM
*A;-1050,500
Fandysans8b
TEpsilon
MCM
*G;-300,1300
>800,300
*G;-200,1200
>200,1000
*G;-200,900
>200,700
*G;-200,600
>200,400
*G;300,1200
>700,1000
*G;300,900
>700,700
*A;0,1100
Fandysans8b
TAlpha
MCM
*A;0,800
Fandysans8b
TBeta
MCM
*A;0,500
Fandysans8b
TGamma
MCM
*A;500,1100
Fandysans8b
TDelta
MCM
*A;500,800
Fandysans8b
TEpsilon
MCM
*A;-1100,100
Fandy10i
TDefaults
MCM
*A;200,100
Fandy10i
TUnbalanced
MCM
*G;-1600,-100
>1000,-500
*G;-1500,-200
>-1100,-400
*G;-1000,-200
>-600,-400
*G;-500,-200
>-100,-400
*G;0,-200
>400,-400
*G;500,-200
>900,-400
*A;-1300,-300
Fandysans8b
TAlpha
MCM
*A;-800,-300
Fandysans8b
TBeta
MCM
*A;-300,-300
Fandysans8b
TGamma
MCM
*A;200,-300
Fandysans8b
TDelta
MCM
*A;700,-300
Fandysans8b
TEpsilon
MCM
*G;-1200,-800
>300,-1300
*A;-1100,-1000
Fandysans8b
TAlpha
MLM
*A;-1100,-1100
Fandysans8b
TBeta
MLM
*A;-600,-1000
Fandysans8b
TGamma
MLM
*A;-600,-1100
Fandysans8b
TDelta
MLM
*A;-100,-1000
Fandysans8b
TEpsilon
MLM
*C;-700,-800
>-700,-1300
*C;-200,-800
>-200,-1300
*A;433,-1059
Fandy10i
TColumnLine
MLM
*A;454,-1183
Fandy10i
T(also ...)
MLM
*A;-356,-651
Fandy10i
TSingleRow
MCM
\enddata{zip,539485192}
\view{zipview,539485192,1362,0,0}
}
\begindata{bp,539644360}
\enddata{bp,539644360}
\view{bpv,539644360,1363,0,0}
Title can be placed within the Suit container in any of four places:
\center{
\begindata{zip,539484936}
%ViewWidth 317
%ViewHeight 197
*D;-1000,1400
N8.5X11
>-1000,1400
*G;-1300,1300
>1300,400
*A;0,1200
TA Top Title
MCM
*G;-1500,100
>-100,-1200
*G;-1100,1000
>-900,800
*G;-700,1000
>-500,800
*G;-300,1000
>-100,800
*G;100,1000
>300,800
*G;500,1000
>700,800
*G;900,1000
>1100,800
*G;-1100,700
>-900,500
*G;-700,700
>-500,500
*G;-300,700
>-100,500
*G;100,700
>300,500
*G;500,700
>700,500
*G;900,700
>1100,500
*J;-700,-100
>100,0
*J;-700,-400
>100,0
*J;-700,-700
>100,0
*J;-700,-1000
>100,0
*J;-300,-100
>100,0
*J;-300,-400
>100,0
*J;-300,-700
>100,0
*J;-300,-1000
>100,0
*C;300,0
>1500,0
*C;200,-100
>200,-1100
*C;1600,-100
>1600,-1100
*C;300,-1200
>1500,-1200
*M;1500,-100
>1500,0;1600,-100;100,100
*M;1500,-1100
>1600,-1100;1500,-1200;100,100
*M;300,-1100
>300,-1200;200,-1100;100,100
*M;300,-100
>200,-100;300,0;100,100
*N;400,-200
>600,-400
*N;400,-500
>600,-700
*N;400,-800
>600,-1000
*N;700,-200
>900,-400
*N;700,-500
>900,-700
*N;700,-800
>900,-1000
*A;1500,-500
Fandysans8b
TA\nRight\nTitle
MRM
*A;-1427,-234
Fandy8
TA\nLeft\nSide\nTitle
MLM
\enddata{zip,539484936}
\view{zipview,539484936,1364,319,199}
}
\subsection{1.1.2 Scrolling}
A suite of Items that cannot be fully displayed in the given viewrectangle,
that also enjoys the \sans{Scroll} attribute (which see), will present
subsets
of Items in sequence within each display-frame. Thus, given the 26 Items
"AAAAA", "BBBBB", ..., "ZZZZZ", the following displays result as the User
scrolls forward from the beginning to the end of the suite (assuming a
viewing
width and height sufficient to display only 3 columns and 4 rows).
\center{
\begindata{zip,539484680}
%ViewWidth 277
%ViewHeight 319
*D;-1000,1400
N8.5X11
>-1000,1400
*G;-1000,1300
>1000,800
*A;-700,1200
Fandysans8
TAAAAA
MLM
*A;-700,1100
Fandysans8
TBBBBB
MLM
*A;-700,1000
Fandysans8
TCCCCC
MLM
*A;-700,900
Fandysans8
TEEEEE
MLM
*G;-1000,1300
G50
>-800,800
*G;-1000,1300
G10
>-800,1200
*G;-1000,900
G10
>-800,800
*A;-100,1200
Fandysans8
TFFFFF
MLM
*A;-100,1100
Fandysans8
TGGGGG
MLM
*A;-100,1000
Fandysans8
THHHHH
MLM
*A;-100,900
Fandysans8
TIIIII
MLM
*A;500,1200
Fandysans8
TJJJJJ
MLM
*A;500,1100
Fandysans8
TKKKKK
MLM
*A;500,1000
Fandysans8
TLLLLL
MLM
*A;500,900
Fandysans8
TMMMMM
MLM
*C;-200,1300
>-200,800
*C;400,1300
>400,800
*G;-1000,500
>1000,0
*G;-1000,500
G50
>-800,0
*G;-1000,500
G10
>-800,400
*G;-1000,100
G10
>-800,0
*A;-700,400
Fandysans8
TMMMMM
MLM
*C;-200,500
>-200,0
*C;400,500
>400,0
*G;-1000,-300
>1000,-800
*G;-1000,-300
G50
>-800,-800
*G;-1000,-300
G10
>-800,-400
*G;-1000,-700
G10
>-800,-800
*A;0,-1100
Fandy10b
TMultiColumnar Scrolling
MCM
*A;-700,300
Fandysans8
TNNNNN
MLM
*A;-700,200
Fandysans8
TOOOOO
MLM
*A;-700,100
Fandysans8
TPPPPP
MLM
*A;-100,400
Fandysans8
TQQQQQ
MLM
*A;-100,300
Fandysans8
TRRRRR
MLM
*A;-100,200
Fandysans8
TSSSSS
MLM
*A;-100,100
Fandysans8
TTTTTT
MLM
*A;500,400
Fandysans8
TUUUUU
MLM
*A;500,300
Fandysans8
TVVVVV
MLM
*A;500,200
Fandysans8
TWWWWW
MLM
*A;500,100
Fandysans8
TXXXXX
MLM
*C;-200,-300
>-200,-800
*C;400,-300
>400,-800
*A;-700,-400
Fandysans8
TXXXXX
MLM
*A;-700,-500
Fandysans8
TYYYYY
MLM
*A;-700,-600
Fandysans8
TZZZZZ
MLM
*G;-992,1180
G1
>-808,1070
*G;-992,303
G1
>-808,185
*G;-992,-681
G1
>-808,-639
\enddata{zip,539484680}
\view{zipview,539484680,1365,279,321}
}
In the instance of \sans{List} displays that require scrolling of
multiple
columns, you might wish to use \sans{RowMajor}, to provide the common
textual
scrolling phenomenon; although \sans{ColumnMajor} is often more visually
desirable, its scrolling is "snake-wise", from column to column.
\center{
\begindata{zip,539484424}
%ViewWidth 263
%ViewHeight 145
*D;-1000,1400
N8.5X11
>-1000,1400
*A;1443,-1026
Fandy8
TRow Major Order
MCM
*A;-1508,-995
Fandy8
TColumn Major Order
MCM
*G;1515,943
>1790,668
*G;1515,530
>1790,255
*G;1515,118
>1790,-157
*G;1514,-294
>1789,-569
*G;1927,943
>2202,668
*G;1927,531
>2202,256
*G;1927,118
>2202,-157
*G;1927,-294
>2202,-569
*G;690,943
>965,668
*G;690,530
>965,255
*G;690,118
>965,-157
*G;689,-294
>964,-569
*G;1102,943
>1377,668
*G;1102,531
>1377,256
*G;1102,118
>1377,-157
*G;1102,-294
>1377,-569
*A;827,806
Fandysans8b
TA
MCM
*A;1239,806
Fandysans8b
TB
MCM
*A;1652,806
Fandysans8b
TC
MCM
*A;2064,806
Fandysans8b
TD
MCM
*A;827,393
Fandysans8b
TE
MCM
*A;1239,393
Fandysans8b
TF
MCM
*A;1652,393
Fandysans8b
TG
MCM
*A;2064,393
Fandysans8b
TH
MCM
*A;827,-19
Fandysans8b
TI
MCM
*A;1239,-19
Fandysans8b
TJ
MCM
*A;1652,-19
Fandysans8b
TK
MCM
*A;2064,-19
Fandysans8b
TL
MCM
*A;827,-431
Fandysans8b
TM
MCM
*A;1239,-431
Fandysans8b
TN
MCM
*A;1652,-431
Fandysans8b
TO
MCM
*A;2064,-431
Fandysans8b
TP
MCM
*G;-1432,542
>-1157,267
*G;-1432,130
>-1157,-145
*G;-1433,-282
>-1158,-557
*G;-1009,553
>-734,278
*G;-1020,130
>-745,-145
*G;-1020,-282
>-745,-557
*G;-2257,542
>-1982,267
*G;-2257,130
>-1982,-145
*G;-2258,-282
>-1983,-557
*G;-1845,543
>-1570,268
*G;-1845,130
>-1570,-145
*G;-1845,-282
>-1570,-557
*G;-2257,955
>-1982,680
*G;-1845,955
>-1570,680
*G;-1432,955
>-1157,680
*G;-1020,955
>-745,680
*A;-2120,818
Fandysans8b
TA
MCM
*A;-2120,405
Fandysans8b
TB
MCM
*A;-2120,-7
Fandysans8b
TC
MCM
*A;-2120,-419
Fandysans8b
TD
MCM
*A;-1707,818
Fandysans8b
TE
MCM
*A;-1707,405
Fandysans8b
TF
MCM
*A;-1707,-7
Fandysans8b
TG
MCM
*A;-1707,-419
Fandysans8b
TH
MCM
*A;-1295,818
Fandysans8b
TI
MCM
*A;-1295,405
Fandysans8b
TJ
MCM
*A;-1295,-7
Fandysans8b
TK
MCM
*A;-1295,-419
Fandysans8b
TL
MCM
*A;-882,818
Fandysans8b
TM
MCM
*A;-882,405
Fandysans8b
TN
MCM
*A;-882,-7
Fandysans8b
TO
MCM
*A;-882,-419
Fandysans8b
TP
MCM
\enddata{zip,539484424}
\view{zipview,539484424,1366,265,147}
}
\section{1.2
Attribute Specification}
The fashion in which Suites are displayed, as well as the nature and
format of
its Items, is governed by the Specification argument optionally provided
when
the Suite object is created. (See the \sans{Create} facility, discussed
in
the chapter \italic{Facilities -- Object Instantiation.})
The syntax of a specification is best shown through an example This
Suite is
produced through the following specification (\sans{suitex2a}):
\center{\typewriter{
*****************************************
*
Control Buttons
*
*
*
*
Start
Stop
Continue
*
*
*
*****************************************
}}:\sans{\indent{
char
*controls[ ] =
\{
"Start",
"Stop",
suite_Specification
\{
"Continue",
my_buttons[ ] =
NULL
\};
suite_Arrangement( suite_Row ),
suite_BorderSize( 3 ),
suite_TitleCaption( "Control Buttons" ),
suite_TitleCaptionFontName( "AndySans16b" ),
suite_ItemCaptionList( controls ),
suite_ItemCaptionFontName( "Andy12i ),
NULL
\};}}
A Specification is composed of macros, each requiring an argument. The
argument is sometimes a \italic{symbolic} (eg, \sans{suite_Row}),
sometimes a
\italic{numeric value} (eg, the value 3 in \sans{suite_BorderSize}),
sometimes
a \italic{character-string} (eg, the quoted characters \italic{Control
Buttons}
in \sans{suite_TitleCaption}), sometimes a \italic{pointer} to a
null-terminated vector of pointers (eg, the \sans{controls} pointer in
\sans{suite_ItemCaptionList}), sometimes a \italic{pointer} to an Item
Specification, and sometimes a \italic{procedure-pointer}. Note that all
symbolics are prefixed with \sans{ "suite_" } to avoid name-clashes
within the
Client-program. There is no required ordering amongst the items in the
Specification structure; however, it is parsed \italic{sequentially},
such
that subsequent attributes override any earlier conflicting attributes.
See chapter \italic{Sample Programs} for more complete examples.
\subsection{1.2.1 Suite Attributes}
This section lists those attributes that are applicable to the Suite as a
whole, including those Item attributes that are inherited by all Items,
unless
overridden for individual Items. (Attributes are listed\italic{
alphabetically}, for ease of reference.)
\bold{\sans{suite_AccessMode}}
\indent{The Items of a Suite are by default \sans{ReadOnly}. They may be
specified as \sans{ReadWrite}, to support dialogs with the User.
\indent{\sans{suite_ReadOnly}
\sans{suite_ReadWrite
suite_Proceed}}
User interaction via a \sans{ReadWrite} Item is discussed in the section,
\italic{ReadWrite Item Interaction}. The \sans{AccessMode} of individual
Items can be set via the \sans{ItemAccessMode} attribute.}
\sans{\bold{suite_Arrangement}}
\indent{The Suite can be displayed in a variety of arrangements. Certain
attributes are appropriate for displays of \italic{Buttons}, others for
displays of \italic{Lists}.
\indent{\sans{suite_Matrix
\sans{suite_Balanced
|
|
}\sans{suite_Row
|
}\sans{suite_Column}
}\sans{suite_UnBalanced}
\sans{suite_List}
\sans{suite_RowLine}
\sans{suite_ColumnLine}}
The \sans{Column} and \sans{Row} attributes constrain the Items to a
single
Column or Row, respectively. The default attribute (\sans{Matrix})
arranges
Items into one or more rows and columns.
The \sans{Balanced} attribute arranges \italic{matrixed} Items
symmetrically
within the Container; \sans{UnBalanced} leaves the last row or column
possibly
with fewer Items than the other rows and columns.
The \sans{List} attribute arranges Items in one or more columns; Items
are
vertically positioned in terms of the line-height of their font.
\sans{RowLine} and \sans{ColumnLine} cause horizontal or vertical lines,
respectively, to be drawn between Items.
A typical \italic{Button} display would use the default attributes
\sans{Matrix} and \sans{Balanced}. A simple one-column \italic{List}
display
would specify \sans{Column} and \sans{List}; balancing is then
irrelevant. A
multi-column List display would likely use the \sans{List} and
\sans{UnBalanced} attributes, to ensure that the leftmost columns are
each
filled, while the rightmost column shows the remaining Items at its top.
}
\bold{\sans{suite_BorderStyle}}
\indent{The Container may be bordered; by default, the border is a
\sans{Rectangle}, whose line-size is one pixel. It's style may be
specified
in various other fashions:
\indent{
\sans{suite_Rectangle}
\sans{suite_Roundangle}
\sans{suite_Circle}
\sans{suite_Oval}
\sans{suite_Invisible}
\sans{suite_None}}}
\bold{\sans{suite_BorderSize}}
\indent{Where the \sans{BorderStyle} is other than \sans{None}, the
pixel-width of the line may be specified (default is one).}
\bold{\sans{suite_Cursor}}
\indent{The cursor for the entire Suite may be specified as an ASCII
character
literal. If the \sans{CursorFontName} is not specified, the default font
is
\italic{icon12}. The NULL character is reserved.
Example:
\sans{suite_Cursor( 'E' )}}
\bold{\sans{suite_CursorFontName}}
\indent{The font for the Suite's cursor may be specified.
font is
\italic{icon12}.
Example:
The default
\sans{suite_CursorFontName( "myicon20" )}}
\bold{\sans{suite_CursorType}}
\indent{The cursor for the entire Suite may be specified as a standard
symbolic name. The font employed is \italic{icon12}. The default cursor
is
the standard Arrow (\sans{Cursor_Arrow}).
Example:
\sans{suite_CursorType( Cursor_Gunsight )}}
\bold{\sans{suite_Datum}}
\indent{Any Client-program datum (eg, a scalar or a pointer to a
Client-program defined structure). Dynamically accessible via the
\sans{SetSuiteAttribute} and \sans{SuiteAttribute} facilities. (Also see
the
\sans{ItemDatum }attribute, which provides the Item-specific datum
attribute.)}
\sans{\bold{suite_FontName}}
\indent{The default font for all captions (title captions as well) may be
specified. Otherwise, the default font is that specified via the
preference
for "bodyfont"; in the absence of any specification, the built-in default
is a
10-point, fixed-width typewriter font. }
\sans{\bold{suite_GutterSize}}
\indent{Items are separated from one another, vertically and
horizontally, by
the size of the Gutter, which defaults to 1 pixel.}
\bold{\sans{suite_HitHandler}}
\indent{A Suite may specify a Client-program procedure to be invoked
whenever
any area within the Container is hit; this general HitHandler may be
overridden for particular Items via the \sans{ItemHitHandler} attribute
specified for such Items. (See the section \italic{HitHandlers}.)}
\sans{\bold{suite_HorizontalGutterSize}}
\indent{Items are separated from one another horizontally by the size of
the
\sans{HorizontalGutter}, which defaults to 1 pixel.}
\bold{\sans{suite_Item}}
\indent{Identifies an \italic{Item Specification}: a separate structure
in
which an individual Item is specified. This scheme is used where the
\sans{ItemCaptionList} (which see) item is not suitable. Any number of
\sans{Item} entries may appear in the Specification for the Suite.}
\bold{\sans{suite_ItemAccessMode}}
\indent{An Item is by default \sans{ReadOnly}. It may be specified as
\sans{ReadWrite}, to support dialogs with the User.
\indent{\sans{suite_ReadOnly}
\sans{suite_ReadWrite
suite_Proceed}}
User interaction via a \sans{ReadWrite} Item is discussed in the section,
\italic{ReadWrite Item Interaction}.}
\bold{\sans{suite_ItemBorderStyle}}
\indent{Items may be styled with or without Borders; by default, the
border is
a \sans{Rectangle}, whose line-width is one. Borders may be one of the
styles:
\indent{\sans{suite_Rectangle}
\sans{suite_Roundangle}
\sans{suite_Circle}
\sans{suite_Oval}
\sans{suite_Invisible}
\sans{suite_None}}
The Item Border-style \sans{Invisible} may be used in conjunction with
the
Item Highlight-style \sans{Border}: when the Item is highlighted its
border
becomes \italic{visible}; when Normalized, it is \italic{invisible}.
Note
that where the \sans{List} attribute is specified, this attribute is
ignored.
(\sans{Invisible} is used for \sans{List} displays.)}
\bold{\sans{suite_ItemBorderSize}}
\indent{Where the \sans{ItemBorderStyle} is other than \sans{None}, the
pixel-width of the line may be specified (default is one pixel).}
\bold{\sans{suite_ItemCaption}}
\indent{A character-string. All Items will contain this \sans{Caption},
unless overridden by captions or insets assigned to particular items.
(See
\sans{ItemCaptionList} and other attributes.)}
\bold{\sans{suite_ItemCaptionAlignment}}
\indent{The Item's Caption may be aligned at any of nine points within of
the
Item area:
\indent{\sans{suite_Top}
\sans{suite_Bottom}
\sans{suite_Left}
\sans{suite_Right}
\sans{suite_Center}
\sans{suite_Middle}}
These alignments may be combined to effect alignment at any of 9 points.
The
\sans{Center} and \sans{Middle} alignments refer, respectively, to
horizontal
and vertical positioning. By default, Captions are balanced both
horizontally
and vertically: ie, they enjoy the attribute combination
\sans{suite_Center |
suite_Middle}.
Example: \sans{ suite_ItemCaptionAlignment( suite_Bottom | suite_Right)}}
\bold{\sans{suite_ItemCaptionList}}
\indent{Identifies a null-terminated vector of Caption pointers;
\sans{Item} attribute.}
see the
\bold{\sans{suite_ItemCaptionFontName}}
\indent{Where the Items employ the \italic{caption} feature, the Font of
the
captions may be specified; all Items use the same font. Lacking such a
specification, an Item's caption font is the same as the Suite's
\italic{TitleFontName}, but two point-sizes smaller. Lacking a
\sans{TitleCaptionFontName} specification, the default font is that
specified
via the preference for "bodyfont"; in the absence of any specification,
the
built-in default is a 10-point, fixed-width typewriter font.
(The name
is
formatted in the usual fashion -- eg, "andysans12bi", "andy18", etc).
Example:
\sans{suite_ItemCaptionFontName( "andysans10b" )}}
\bold{\sans{suite_ItemCursor}}
\indent{The cursor for individual Items may be specified as an ASCII
character
literal. If the \sans{CursorFontName} is not specified, the default font
is
\italic{icon12}. The NULL character is reserved.
Example:
\sans{suite_ItemCursor( 'E' )}}
\bold{\sans{suite_ItemCursorFontName}}
\indent{The font for the Item's cursor may be specified.
font is
\italic{icon12}.
Example:
The default
\sans{suite_ItemCursorFontName( " myicons16" )}}
\bold{\sans{suite_ItemCursorType}}
\indent{The cursor for individual Items may be specified as a standard
symbolic name. The font employed is \italic{icon12}. The default cursor
is
the standard Arrow (\sans{Cursor_Arrow}).
Example:
\sans{suite_ItemCursorType( Cursor_Gunsight )}}
\bold{\sans{suite_ItemDatum}}
\indent{Any Client-program datum -- eg, a scalar or a pointer to a
client-program defined structure. Dynamically accessible via the
\sans{SetItemAttribute} and \sans{ItemAttribute} facilities. (Also see
the
\sans{Datum} attribute, which provides the Suite datum attribute.)}
\bold{\sans{suite_ItemDataObject}}
\indent{Instead of a Caption, any ATK inset can be specified as the
substance
of a Item. The object is given via an \italic{object-identifier} (ie, a
pointer). (See also \sans{suite_ItemViewObject}.)}
\bold{\sans{suite_ItemDataObjectName}}
\indent{Instead of a Caption, any ATK inset can be specified as the
substance
of an Item. The object name is given as a \italic{character-string}.
(See
also \sans{suite_ItemViewObjectName}.)}
\bold{\sans{suite_ItemDataObjectHandler}}
\indent{A procedure-name may be specified to be associated with the
Item's
Data-object. That procedure is invoked upon instantiation of the
object.}
\bold{\sans{suite_ItemHeight}
\sans{suite_ItemWidth}}
\indent{The width and height of each Item is normally calculated
automatically. However, those calculations may be overridden by these
attributes; one or both may be specified, the omitted attribute being
automatically calculated. (Use of the \sans{List} attribute will cause
these
attributes to be ignored.) The width and height values are in pixels.}
\bold{\sans{suite_ItemHighlightStyle}}
\indent{Items may be highlighted, either upon User selection or through
Client-program request. The styles for Highlighting, which may be used
in
combination, are:
\indent{\sans{suite_Invert}
\sans{suite_Border}
\sans{suite_Bold}
\sans{suite_Italic}}
The \sans{Border} Highlight-style is used in conjunction with the Item
Border-style \sans{Invisible}: when the Item is highlighted its border
becomes
\italic{visible}; when Normalized, it is \italic{invisible}. To combine
several styles, the syntax is --
\sans{suite_ItemHighlightStyle( suite_Bold | suite_Italic)}}
\bold{\sans{suite_ItemHitHandler}}
\indent{An Item may specify the name of a Client-program procedure to be
invoked whenever the Item is the object of a mouse-action. (See the
section
\italic{HitHandlers}.)}
\bold{\sans{suite_ItemName}}
\indent{An Item may be given a \italic{symbolic name} for use during
execution. (See the facilities \sans{ItemOfName} and
\sans{ItemsOfName}.)}
\bold{\sans{suite_ItemOrder}}
\indent{Items are displayed either in \sans{RowMajor} or
\sans{ColumnMajor}
order; the default is \sans{ColumnMajor} -- the fashion used in telephone
directories.}
\bold{\sans{suite_ItemPassiveStyle}}
\indent{An Item can be made passive or active (default is active). An
\italic{active} Item can be selected, a \italic{passive} Item cannot.
The
visual indication of the passive state is controlled by this attribute.
\indent{\sans{suite_Pale}
\sans{suite_Hidden}
\sans{suite_Removed}}
An item is made \sans{Pale} by shading. \sans{Hidden} simply blanks out
the
area within and including the Item border; where an Item is
\sans{Removed},
the Suite is redrawn without the Item.}
\sans{\bold{suite_ItemPosition}}
\indent{The position of the Item within the Suite. The first Item is at
Position 1 (\italic{not} 0). This attribute can be changed dynamically,
resulting in repositioning of Items amongst themselves. For example, an
Item
currently at position 23 can be repositioned to be the fourth Item by
setting
its \sans{ItemPosition} attribute to 4; the Item that had been the
fourth
Item becomes the fifth, etc.}
\bold{\sans{suite_ItemTitleBorderStyle}}
\indent{The ItemTitle may be bordered; by default, the border is
\sans{None}.
Its style may instead be specified in other fashions:
\indent{\sans{suite_None}
\sans{suite_Rectangle}
\sans{suite_Roundangle}
\sans{suite_Circle}
\sans{suite_Oval}
\sans{suite_Invisible}
\sans{suite_Line}}
Instead of a Border, the Item Title can be separated from the Item
Caption by
a single line. The Item Title Border-style \sans{Invisible} is used in
conjunction with the Item Title Highlight-style \sans{Border}: when the
Item
Title is highlighted its border becomes \italic{visible}; when
Normalized, it
is \italic{invisible}.}
\bold{\sans{suite_ItemTitleBorderSize}}
\indent{Where the \sans{ItemTitleBorderStyle} is other than \sans{None},
the
pixel-width of the line (default is one) may be specified.}
\bold{\sans{suite_ItemTitleCaption}}
\indent{An Item may contain a caption as a Title. By default, the Title
is
centered at the top of the Item, beneath the Item's Border. This
Placement
and its Alignment within the title-area can be overridden via the
\sans{ItemTitlePlacement} and \sans{ItemTitleCaptionAlignment}
attributes.
(An Item Title may instead be an Inset.)}
\bold{\sans{suite_ItemTitleCaptionAlignment}}
\indent{The Item's Title caption may be aligned at any of nine points
within
the Item's title area:
\indent{\sans{suite_Top}
\sans{suite_Bottom}
\sans{suite_Left}
\sans{suite_Right}
\sans{suite_Center}
\sans{suite_Middle}}
These alignments may be combined to effect alignment at any of 9 points.
The
\sans{Center} and \sans{Middle} alignments refer, respectively, to
horizontal
and vertical positioning. By default, alignment is \italic{balanced}:
ie,
\sans{suite_Center | suite_Middle}.
Example: \sans{ suite_ItemTitleCaptionAlignment( suite_Bottom |
suite_Right)}}
\bold{\sans{suite_ItemTitleCaptionFontName}}
\indent{Given a Title that is a caption (ie, not an Inset), its font may
be
specified. By default, the font is that specified via the preference for
"bodyfont"}
\sans{ }\bold{\sans{suite_ItemTitleDataObject}}
\indent{Instead of a caption, any ATK \italic{inset} can be specified as
the
substance of a Item Title. The data-object can be specified via an
\italic{object-identifier} (ie, a pointer).}
\sans{ }\bold{\sans{suite_ItemTitleDataObjectName}}
\indent{Instead of a caption, any ATK \italic{inset} can be specified as
the
substance of a Item Title. The data-object name is a
\italic{character-string}: the object is instantiated automatically.}
\bold{\sans{suite_ItemTitleDataObjectHandler}}
\indent{A \sans{procedure} may be specified to be associated with the
Item
Title Data-object. That procedure is invoked upon instantiation of the
object.}
\bold{\sans{suite_ItemTitleHighlightStyle}}
\indent{Item Titles may be highlighted, either upon User selection or
through
Client-program request. The styles for Highlighting, which may be used
in
combination, are:
\indent{\sans{suite_Invert}
\sans{suite_Border}
\sans{suite_Bold}
\sans{suite_Italic}}
To combine several styles, the syntax is -\sans{suite_ItemTitleHighlightStyle( suite_Bold | suite_Italic)}}
\bold{\sans{suite_ItemTitlePlacement}}
\indent{The Item's Title may be placed at any one of these areas within
the
Item area:
\indent{\sans{suite_Top}
\sans{suite_Bottom}
\sans{suite_Left}
\sans{suite_Right}}}
\sans{ }\bold{\sans{suite_ItemTitleViewObject}}
\indent{Instead of a caption, any ATK \italic{inset} can be specified as
the
substance of a Item Title. The view-object can be specified via an
\italic{object-identifier} (ie, a pointer).}
\sans{ }\bold{\sans{suite_ItemTitleViewObjectName}}
\indent{Instead of a caption, any ATK \italic{inset} can be specified as
the
substance of a Item Title. The view-object name is a
\italic{character-string}: the object is instantiated automatically.}
\bold{\sans{suite_ItemTitleViewObjectHandler}}
\indent{A \sans{procedure} may be specified to be associated with the
Item
Title View-object. That procedure is invoked upon instantiation of the
object.}
\bold{\sans{suite_ItemViewObject}}
\indent{Where a Data-object is specified for an Item, an associated
View-object may be specified; in the absence of a specified
\sans{ViewObject},
the default name implied by the \sans{DataObject} will be employed (as
defined
in the ATK schema).}
\bold{\sans{suite_ItemViewObjectName}}
\indent{Where a Data-object is specified for an Item, an associated
View-object may be specified; in the absence of a specified
\sans{ViewObjectName}, the default name implied by the
\sans{DataObjectName}
will be employed (as defined in the ATK schema).}
\bold{\sans{suite_ItemViewObjectHandler}}
\indent{A procedure-name may be specified to be associated with the
View-object. That procedure is invoked upon instantiation of the
object.}
\bold{\sans{suite_Scroll}}
\indent{A Suite may contain more Items than can fit within its Container
(given contraints optionally placed upon Item fonts, and thus the
dimensions,
of individual Items). Where the \sans{Scroll} attribute is specified,
and if
and only if an overflow condition exists, the specified ScrollBar(s),
will be
displayed -- per the options:
\indent{\sans{suite_Left}
\sans{suite_Right}
\sans{suite_Bottom}
\sans{suite_Top}}
When both vertical and horizontal ScrollBars are specified, the Items are
arranged, by default, with a column-count equal to the row-count. Where
the
\sans{Scroll} attribute is not taken and an overflow condition occurs,
the
overflowing Items are forced to fit in the available space. Multiple
ScrollBars are specified by combining these attribute values, as shown in
the
Example.
Example:
\sans{suite_Scroll( suite_Left | suite_Bottom )}}
\bold{\sans{suite_SelectionMode}}
\indent{A Suite is either \sans{Exclusive}\sans{, Inclusive, or}
\sans{Toggle.}
An \italic{Exclusive} Suite, the default, allows only a single Item to
be
selected at any moment (initially, no Items are selected). An
\italic{Inclusive} Suite allows zero or more Items to be selected at any
moment. A \italic{Toggle} Suite allows zero or more Items to be selected
at
any moment, each Item selected and deselected individually. (See
section,
\italic{HitHandler}, regarding use of either the Suite's HitHandler or
\italic{each} Item's HitHandler when an \italic{Inclusive} Suite is
multiply-selected.)
Selection of Items within an \italic{Inclusive Suite} may be effected by
the
User "dragging" or "sweeping" the mouse across multiple Items, or by use
of
the Right-button to select non-contiguous Items. These rules apply:
\sans{\italic{LeftDown}}
\indent{Selected Item Highlighted, others Normalized.}
\sans{\italic{LeftMovement}}
\indent{Contiguous Items are Highlighted.}
\sans{\italic{LeftUp}}
\indent{Selection ceases.}
\sans{\italic{RightDown}}
\sans{\italic{RightMovement}}
\indent{Iff Item is Highlighted, it is Normalized;
iff Normal, it is Highlighted.}
\sans{\italic{RightUp}}
\indent{Selection ceases.}
Selection of an Item within an \italic{Exclusive Suite} causes the
previously
selected Item (if any) to be Normalized, and the selected Item to be
Highlighted upon the LeftDown action; however, should the User then drag
the
mouse such that the LeftUp action occurs on another Item, that other Item
is
the one selected and Highlighted.
For an Exclusive Suite, actions of
the
Right-button are the same as for the Left-button.
Selection of an Item within a \italic{Toggle Suite} does not affect
previously
selected Items (if any). The individually selected Item is toggled on or
off,
depending upon its current state; toggling is effected only when the
LeftDown
action occurs. When toggled on, an Item is Highlighted; when toggled
off, the
Item is Normalized.
For a Toggle Suite, actions of the Right-button are
the
same as for the Left-button.
}
\bold{\sans{suite_SortMode}}
\indent{A Suite can be sorted in terms of it's Item Captions, Titles, or
Datum
attribute values.
\indent{\sans{suite_Alphabetic}
\sans{suite_Numeric}
\sans{suite_Ascend}
\sans{suite_Descend}
\sans{suite_ByCaption}
\sans{suite_ByTitle}
\sans{suite_ByDatum}}
Sorting may be either Alphabetically or Numerically based, ordering may
be
either Ascending or Descending. Sorting Numerically instead of
Alphabetically
will place, say, \bold{\sans{10}} \italic{after} \sans{\bold{9}}, while
sorting Alphabetically will place it \italic{before} (assuming an
Ascending
sort). Items are sorted per one of the three Item attributes: its
Caption-string, its Title-string, or its Datum-value.
sorted
prior to its visual presentation}
The Suite is
\bold{\sans{suite_TitleBorderStyle}}
\indent{The Title may be bordered; by default, the border style is
\sans{None}. Its style may instead be specified in other fashions:
\indent{
\sans{suite_None}
\sans{suite_Rectangle}
\sans{suite_Roundangle}
\sans{suite_Circle}
\sans{suite_Oval}
\sans{suite_Invisible}
\sans{suite_Line}}
Instead of a Border, the Title can be separated from the Items by a
single
line by specifying \sans{Line} attribute. The Title Border-style
\sans{Invisible} is used in conjunction with the Title Highlight-style
\sans{Border}: when the Title is highlighted its border becomes
\italic{visible}; when Normalized, it is \italic{invisible}.}
\bold{\sans{suite_TitleBorderSize}}
\indent{Where the \sans{TitleBorderStyle} is other than \sans{None}, the
pixel-width of the line (default is one) may be specified.}
\bold{\sans{suite_TitleCaption}}
\indent{A Suite 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{TitleCaptionAlignment} and \sans{TitlePlacement}.)}
\sans{\bold{suite_TitleCaptionAlignment}}
\indent{The alignment of the Title caption within the area it is placed
may be
specified:
\indent{\sans{suite_Top}
\sans{suite_Bottom}
\sans{suite_Left}
\sans{suite_Right}
\sans{suite_Center}
\sans{suite_Middle} }
These alignments may be
The
\sans{suite_Center} and
respectively, to
horizontal and vertical
\italic{balanced}: ie,
Example:
)}
combined to effect alignment at any of 9 points.
\sans{suite_Middle} alignments refer,
positioning. By default, alignment is
\sans{suite_Center | suite_Middle}.
\sans{suite_TitleCaptionAlignment( suite_Bottom | suite_Right
\sans{suite_TitleCaptionAlignment( suite_Right | suite_Middle )}
}
\bold{\sans{suite_TitleCaptionFontName}}
\indent{Given a Title that is a Caption, its font may be specified. By
default, the \sans{TitleCaptionFontName} is that specified via the
preference
for "bodyfont"}
\sans{ }\bold{\sans{suite_TitleDataObject}}
\indent{Instead of a caption, any ATK \italic{inset} can be specified as
the
substance of a Title. The data-object can be specified via an
\italic{object-identifier} (ie, a pointer).}
\sans{ }\bold{\sans{suite_TitleDataObjectName}}
\indent{Instead of a caption, any ATK \italic{inset} can be specified as
the
substance of a Title. The data-object name is a \italic{characterstring}.}
\bold{\sans{suite_TitleDataObjectHandler}}
\indent{A \sans{procedure} may be specified to be associated with the
Title
Data-object. That procedure is invoked upon instantiation of the
object.}
\bold{\sans{suite_TitleHighlightStyle}}
\indent{Titles may be highlighted, either upon User selection or through
Client-program request. The styles for Highlighting, which may be used
in
combination, are:
\indent{\sans{suite_Invert}
\sans{suite_Border}
\sans{suite_Bold}
\sans{suite_Italic}}
The Title Border-style \sans{Invisible} is used in conjunction with the
Title
Highlight-style \sans{Border}: when the Title is highlighted its border
becomes \italic{visible}; when Normalized, it is \italic{invisible}.}
\bold{\sans{suite_TitleHitHandler}}
\indent{A Suite may specify a Client-program \sans{procedure} to be
invoked
whenever the Suite \italic{Title} is the object of a mouse-action. (See
below, \italic{HitHandlers}.)}
\bold{\sans{suite_TitlePlacement}}
\indent{The Title area may be placed at the
\indent{\sans{suite_Top}
\sans{suite_Bottom}
\sans{suite_Left}
\sans{suite_Right}
\sans{suite_Line} }
of the Container. The Title can be separated from the Item-area by a
dividing
line (\sans{Line} attribute).}
\bold{\sans{suite_TitleViewObject}}
\indent{Instead of a caption, any ATK \italic{inset} can be specified as
the
substance of a Title. The view-object is specified via an objectidentifier
(ie, a pointer).}
\bold{\sans{suite_TitleViewObjectName}}
\indent{Where a \sans{TitleDataObjectName} is specified, an associated
\sans{TitleViewObjectName} may be specified; in the absence of a
specified\italic{ }\sans{TitleViewObjectName}, the default
\sans{TitleViewObjectName} implied by the \sans{TitleDataObjectName} will
be
employed.}
\bold{\sans{suite_TitleViewObjectHandler}}
\indent{A \sans{procedure} may be specified to be associated with the
Title
View-object. That procedure is invoked upon instantiation of the
object.}
\sans{\bold{suite_VerticalGutterSize}}
\indent{Items are separated from one another vertically by the size of
the
\sans{VerticalGutter}, which defaults to 1.}
\sans{\bold{suite_WrappingStyle}}
\indent{
Captions that overflow the width of an Item are wrapped to the next
line(s).
The phrase(s) of the next line(s) are:
\indent{
\sans{suite_LeftIndent}
Begun on the same vertical position
\sans{suite_LeftRight} Right-justified.
}
Default is \sans{suite_LeftIndent}.}
\subsection{1.2.2 Item Attributes}
Each Item can be individually specified. Such specification may be as
minimal
as just its Caption or as elaborate as necessary to individualize each
Item.
Item attributes are inherited from the Suite specification, except where
an
attribute is overridden for that Item via an Item Specification. The
attributes that may appear in a Item Specification are those defined
above,
\italic{Suite Attributes}. Note that either generic or Item-specific
spellings may be employed; thus, to specify the name of an Item's
Caption-font, either \sans{suite_FontName} or
\sans{suite_ItemCaptionFontName} may be used within an Item
specification.
\section{1.3
Handlers}
Whereas the suite class provides appropriate housekeeeping to reflect
User
interaction with a Suite 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 Suite as a whole or for individual
Items.
In the absence of individual Item Handlers, the Suite Handler is
employed.
Where both a Suite Handler and Item Handlers are specified, the latter
are
employed.
There are three kinds of Handlers: those that cope with Hits, those
dealing
with ReadWrite Item actions, and those that deal with Items, Titles, etc,
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 Suite (as provided via the
\sans{suite_Create} facility).
\bold{Argument-2:}
Identifier of the Suite.
\bold{Argument-3:}
Identifier of the object hit.
\bold{Argument 4:}
Hit-object type (\sans{suite_TitleObject}, \sans{suite_ItemObject}, 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, suite, object, type, action, x, y,
clicks
)}}
(The parameter \sans{self} is the value specified as the \italic{Anchor}
by
the Client-program via \sans{suite_Create}.)
All mouse-actions are passed through.
In the instance of an \italic{Inclusive} Suite, the complete set of
currently
selected Items can be obtained through the \sans{suite_SelectedItems}
facility.
\subsection{1.3.2 ReadWrite Handlers}
An Item specified with the \sans{AccessMode} of \sans{ReadWrite} supports
interactive dialogs between the Client program and the User. The User
selects
the Item by clicking into it with the left mouse button, and then types
zero
or more characters; the Enter-key terminates the input-sequence. The
Client
program's Hit Handler is invoked twice: first upon the initial click, and
then
when the Enter-key is depressed. At the initial click, the Client
program may
elect either to leave the Item's current caption or inset as is, clear
it, or
replace it with a new value. When the Enter-key is depressed, the Client
program may extract the caption as a plain-text character-string.
Should the User click outside an Item before the Enter-key is depressed,
the
Entry-key action is synthesized: the Hit Handler is entered for the
second
time.
The Client-program can cause automatic movement (selection) from one
ReadWrite
Item to another via the \sans{Proceed} attribute. When the User
completes the
entry of one Item's value (by depressing the Enter-key), the next
\sans{ReadWrite} Item is automatically selected; when the last such Item
is
completed, selection loops back to the initial \sans{ReadWrite} Item.
\subsection{1.3.3 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 Suite.
\bold{Argument-2:}
Identifier of the Suite.
\bold{Argument 3:}
Identifier of the object.
\bold{Argument 4:}
Object-type (Title or Item).
}
Thus, a typical Object Handler would be written:
\sans{\indent{My_Object_Handler( self, suite, object, type )}}
\section{1.4
Printing}
Printed output is in PostScript form.
(Presently, Printing of Suites is not supported.)
\begindata{bp,539670984}
\enddata{bp,539670984}
\view{bpv,539670984,1367,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 Suite itself, and those for the
Items of
the Suite.
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{suite_ChangeSuiteAttribute( \italic{object},
suite_TitleCaption( \italic{caption} ) );}}}
\indent{
where :
\sans{\bold{object }}
is the Identifier of the instance of the Class (as returned from the
\sans{suite_Create} facility);
\sans{\bold{caption}}
is a pointer to a character-string.}
o All symbolic-names (eg, those of the options and exception-codes) are
prefixed with the character "suite_" to preclude name-clashes with
Client-program names.}
\section{2.1
Object Instantiation}
The Suite object is instantiated via the \sans{suite_Create} facility.
This
object is a sub-class of aptv, which is itself a sub-class of the View
class; there is no associated Data-object
\subsection{2.1.1 Create}
Creates an instance of the Suite Class.
Specification
Vector to establish initial attributes.
Parses the optional
\bold{Synopsis}\block{ \sans{suite_Create( specification, anchor )
suite_Specification
specification
struct basicobject
\bold{Returns}\block{
identifier.}}
*anchor
|
NULL
NULL}}
\sans{struct suite *}
\bold{Exceptions}\block{
|
\italic{Suite object
\sans{InsufficientSpace, AttributeConflict}}
\bold{Discussion}\block{
The \sans{Create} facility establishes a
Suite object
through an optional Suite Specification. This \sans{specification}
argument
is a pointer to a vector of symbolics, values, or pointers to values.
Such
vectors are specified within the Client program through special suite
macros,
such as \sans{suite_BorderStyle}, \sans{suite_HitHandler}, etc.
(See
section \italic{Suite Specifications}; also chapter \italic{Sample
Programs}
for illustrations.) The \sans{anchor} argument is usually the
instance-pointer of the object requesting the creation of a Suite object;
this
argument may be NULL.
The vector of \italic{Suite Specifications} is unordered: each item is
self-identifying. Should an item appear more than once, subsequent
appearances override earlier items. However, multiple appearances of the
Item
specification are expected; the sequence in which they appear defines the
initial un-sorted sequence in which the Items will be displayed, unless
changed via a \sans{Sort} attribute.
An \italic{Item Specification} is similarly structured. Note that where
the
\sans{ItemCaptionList} attribute is declared in the Suite specification,
individual \sans{Item} specifications are not allowed; should any appear,
the
AttributeConflict exception is raised and they are ignored. An Item
Specification may contain either a Caption or a DataObject/ViewObject
specification. In the absence of an Item specified \sans{HitHandler}, the
general HitHandler specified in the Suite Specification will be employed;
whether the special or the general HitHandler is employed, the Itemspecified
Datum attribute (which defaults to Null) will be available to the
HitHandler.
The Attribute-Names are symbolics, the Attribute-Values are of the datatype
appropriate to the specific Attribute. The Attributes and associated
Values
are discussed in the \italic{Concepts} chapter.}
\section{2.2
Suite Facilities}
These facilities affect the Suite as a whole.
\subsection{2.2.1 Suite Attributes}
Suite 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{SetAttribute}
facility. In most instances, the static fashion suffices.
\paragraph{2.2.1.1
SetSuiteAttribute}
Sets the specifed attribute of the Suite to the given value.
\bold{Synopsis}\block{ \sans{suite_SetSuiteAttribute( object,
attribute_value)
struct suite
long
*object
attribute_value}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
Result-code.}}
None.}
\bold{Discussion}\block{
Each of the attributes listed in the section
\italic{Suite Specifications} can be set either statically or
dynamically.
The syntax for this facility is that employed in the static declaration
of
attributes, for example -\sans{suite_SetSuiteAttribute( object, suite_Datum( 1234) );
suite_SetSuiteAttribute( object, suite_Title( "News of the Day" ) );}
Note that those Attributes that have an impact upon the Suite display do
not
take effect until either the next FullUpdate or Update request is
effected.
To effect immediate display, use the \sans{ChangeSuiteAttribute}
facility.}
\paragraph{2.2.1.2
ChangeSuiteAttribute}
Sets the specifed attribute of the Suite to the given value and
immediately
updates the display.
\bold{Synopsis}\block{ \sans{suite_ChangeSuiteAttribute( object,
attribute_value)
struct suite
*object
suite_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{Suite Specifications} can be set either statically or
dynamically.
The syntax for this facility is that employed in the static declaration
of
attributes, for example -\sans{\description{suite_ChangeSuiteAttribute( object, suite_BorderStyle(
suite_RoundAngle ) );}
\description{suite_ChangeSuiteAttribute( object, suite_Title( "Latest
News" )
);}}
Note that \italic{changing} Attributes has an immediate impact upon the
Suite
display. To defer display updates, use the \sans{SetSuiteAttribute}
facility.}
\paragraph{2.2.1.3
SuiteAttribute}
Yields the value of the given Suite attribute.
\bold{Synopsis}\block{ \sans{suite_SuiteAttribute( object,
struct suite
*object
attribute)
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{Suite Specifications} can be queried.
The syntax of this facility is similar to that of the \sans{SetAttribute}
facility, but differs in that the parenthesized argument is 0 (Null) -\sans{suite_SuiteAttribute( object, suite_Datum( 0 ) );}
}
\paragraph{2.2.1.4
ItemCount}
Yields count of the Items in the suite.
\bold{Synopsis}\block{ \sans{suite_ItemCount( object )
struct suite
*object}}
\bold{Returns}\block{
\sans{long }
\italic{
Item Count}}
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
Active,Passive,
or Removed.}
The count includes all Items, whether
\paragraph{2.2.1.5
CurrentItem}
Yields identifier of the Item most recently selected.
\bold{Synopsis}\block{ \sans{suite_CurrentItem( object )
struct suite
*object}}
\bold{Returns}\block{
Item}}
\sans{struct suite_item *}
\bold{Exceptions}\block{
\italic{
Current
None.}
\bold{Discussion}\block{
Where no Item has been selected, Null is
returned.
To identify the complete set of selected Items, see the
\sans{suite_SelectedItems} facility.}
\subsection{2.2.2 Suite Manipulation}
These facilities deal with the Suite's entire set of Items.
\paragraph{2.2.2.1
Reset}
Resets the Suite to the specified state -- in particular, Normalizes and
Activates all Items.
\bold{Synopsis}\block{ \sans{suite_Reset( object, state )
struct suite
long
*object
state:
suite_Clear
|
suite_ClearItems
|
suite_ClearTitle
|
suite_Normalize
|
suite_Activate |
suite_Expose |
suite_Immediate | suite_Defer}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
its
\sans{suite_Clear}
Result-code.}}
--
returns the suite to
empty state:
ie,
no Title, no Items, etc.
\sans{suite_ClearItems} -all
other attributes unchanged.
removes the Items from the suite, but leaves
\sans{suite_ClearTitle} -- removes the Title area from the suite, but
leaves
all other attributes unchanged.
\sans{suite_Normalize}
--
\sans{suite_Activate}
\sans{suite_Expose}
---
All Items are Activated.
All Items are Exposed.
\sans{suite_Immediate } -is the
default action.
\sans{suite_Defer } -visuals.
All Items are Normalized.
Immediate re-display of Suite visuals; this
Defer, till FullUpdate, re-display of Suite
}
\paragraph{2.2.2.2
Apply}
Iterates across each of the Suite's \sans{Items}, invoking the given
\sans{procedure} for each \sans{Item }in turn.
\bold{Synopsis}\block{ \sans{suite_Apply( object, procedure, anchor,
datum )
struct suite
long(*)()
*object
procedure
struct basicobject
long
*anchor
datum}}
\bold{Returns}\block{
value.}}
\sans{long} \italic{
Client-returned
\bold{Exceptions}\block{
None}
\bold{Discussion}\block{
arguments,
in the order shown:
The \sans{procedure} is invoked with these
\indent{\sans{anchor}
Given \sans{anchor}-value
\sans{object}
\sans{item}
Identifier of the Suite object
Identifier of present Item
\sans{datum}
Given \sans{datum}-value}
Within the \sans{procedure}, all Suite facilities may be employed; note
that
alteration of the Suite will affect subsequent invocations to the
procedure.
The order in which the Items are accessed is that originally specified
when
the Suite was Created, or that in which it stands following a Sort
action.
The invoked procedure breaks the scan by returning a non-zero value (a
zero-value continues the scan); the \sans{Apply} facility returns this
value
as the scan stops. When the scan stops because it reaches the end of the
Items, Null is returned.}
\paragraph{2.2.2.3
HighlightTitle}
Highlights the Suite Title, in the TitleHighlightStyle specified.
\bold{Synopsis}\block{ \sans{suite_HighlightTitle( object )
struct suite
*object}}
\bold{Returns}\block{
code.}}
\sans{boolean}
\italic{Result-
\bold{Exceptions}\block{
\sans{NonExistentTitle}}
\bold{Discussion}\block{
None.}
\paragraph{2.2.2.4
TitleHighlighted}
Yields \sans{true} if the Suite Title is highlighted, otherwise
\sans{false}.
\bold{Synopsis}\block{ \sans{suite_TitleHighlighted( object )
struct suite
*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.5
NormalizeTitle}
Normalizes the Suite Title.
\bold{Synopsis}\block{ \sans{suite_NormalizeTitle( object )
struct suite
*object}}
\bold{Returns}\block{
code.}}
\sans{boolean}
\italic{Result-
\bold{Exceptions}\block{
\sans{NonExistentTitle}}
\bold{Discussion}\block{
None.}
\paragraph{2.2.2.6
Sort}
Sorts the Suite's Items in the manner specified.
\bold{Synopsis}\block{ \sans{suite_Sort( object, mode, attribute,
procedure )
struct suite
long
*object
mode:
suite_Alphabetic
suite_Ascending
long
|
suite_Numeric
|
NULL
|
suite_Descending
|
NULL
|
suite_ByDatum
suite_ByTitle
attribute :
suite_ByCaption
long(*)()
procedure
}}
\bold{Returns}\block{
|
NULL
\sans{long} \italic{
\bold{Exceptions}\block{
|
Result-code}}
None.}
\bold{Discussion}\block{
Where the sort-procedure is NULL, sorts the
Items,
via their specified \sans{attribute}, in the given \sans{mode} (default
is
Alphabetic & Ascending).
Where a sort-handler is provided, it is invoked in a manner similar to
that
employed by qsort. It is passed four arguments:
\indent{
\sans{anchor}
\sans{suite}
\sans{item_1}
\sans{item_2}
}
As for qsort, the returned value is to be:
\indent{
\sans{-1}
\sans{
First Item is lower than second
0} Items are equal
\sans{+1}
First Item is higher than second.
}}
\section{2.3
Item Facilities}
These facilities affect individual Items.
\subsection{2.3.1 Item Attributes}
Item 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{SetItemAttribute}
facility. In most instances, the static fashion suffices.
\paragraph{2.3.1.1
SetItemAttribute}
Sets the specifed attribute of the given Item to the given value.
\bold{Synopsis}\block{ \sans{suite_SetItemAttribute( object, item,
attribute_value)
struct suite
*object
struct suite_item
*item
suite_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{Item Specifications} can be set either statically or dynamically.
The
syntax for this facility is that employed in the static declaration of
attributes, for example -\sans{\description{suite_SetItemAttribute( object, item,
suite_ItemBorderStyle( suite_RoundAngle ) );}
\description{suite_SetItemAttribute( object, item, suite_ItemTitle(
"Latest
News" ) );}}
Note that those Attributes that have an impact upon the Suite display do
not
take effect until either the next FullUpdate or Update request is
effected.
To effect immediate display, use the \sans{ChangeItemAttribute}
facility.}
\paragraph{2.3.1.2
ChangeItemAttribute}
Sets the specifed attribute of the given Item to the given value and
immediately updates the display.
\bold{Synopsis}\block{ \sans{suite_ChangeItemAttribute( object, item,
attribute_value)
struct suite
*object
struct suite_item
*item
suite_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{Item Specifications} can be set either statically or dynamically.
The
syntax for this facility is that employed in the static declaration of
attributes, for example -\sans{\description{suite_ChangeItemAttribute( object, item,
suite_ItemBorderStyle( suite_RoundAngle ) );}
\description{suite_ChangeItemAttribute( object, item, suite_ItemTitle(
"Latest
News" ) );}}
Note that those Attributes that have an immediate impact upon the Suite
display. To defer display updates, use the \sans{SetItemAttribute}
facility.}
\paragraph{2.3.1.3
ItemAttribute}
Yields the value of the given attribute for the given Item.
\bold{Synopsis}\block{ \sans{suite_ItemAttribute( object, item,
attribute)
struct suite
*object
struct suite_item
*item
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{Item Specifications} can be queried.
The syntax of this facility is similar to that of the
\sans{SetItemAttribute}
facility, but differs in that the parenthesized argument is 0 (Null) -\sans{suite_ItemAttribute( object, item, suite_ItemBorderStyle( 0 ) );}
}
\subsection{2.3.2 Item Identification}
Identifiers of individual Items may be obtained through facilities that
scan
the Item set to locate those that matches a given value. These
facilities
need only be employed in those instances that a particular Item is to be
located -- in most instances, such as within \sans{HitHandler}s, you will
find
that the identifier of the Item passed to such procedures suffices.
Some of the identification facilities (eg, \sans{ItemsOfName}) returns a
pointer to a null-terminated vector of Item identifiers; others return a
scalar Item identifier.
Note that where a vector is returned, it exists
only
until the next request for a vectored list is made.
\paragraph{2.3.2.1
ItemOfName}
Yields Identifier of the first Item whose Name attribute matches the
given
name.
\bold{Synopsis}\block{ \sans{suite_ItemOfName( object, name )
struct suite
char
*object
*name}}
\bold{Returns}\block{
Identifier}}
\sans{struct suite_item *}
\bold{Exceptions}\block{
\italic{
Item
None.}
\bold{Discussion}\block{
Where no Item name matches the given name,
the value
Null is returned. Where the Null name is given, the first Item whose
name is
Null is returned.}
\paragraph{2.3.2.2
ItemsOfName}
Yields Identifier(s) of the Item(s) whose Name attribute matches the
given
name.
\bold{Synopsis}\block{ \sans{suite_ItemsOfName( object, name )
struct suite
char
*object
*name}}
\bold{Returns}\block{
Identifier
vector}}
\sans{struct suite_item **} \italic{Item
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
Where no Item name matches the given name,
the value
Null is returned. Where the Null name is given, Items whose name is Null
are
returned.}
\paragraph{2.3.2.3
ItemOfDatum}
Yields Identifier of the first Item whose Datum attribute matches the
given
datum.
\bold{Synopsis}\block{ \sans{suite_ItemOfDatum( object, datum )
struct suite
long
*object
datum}}
\bold{Returns}\block{
Identifier}}
\sans{struct suite_item *}
\bold{Exceptions}\block{
\italic{
Item
None.}
\bold{Discussion}\block{
Where no Item datum matches the given datum,
the
value Null is returned. Where a Null datum is given, the first Item
whose
datum is Null is returned.}
\paragraph{2.3.2.4
ItemsOfDatum}
Yields Identifier(s) of the Item(s) whose datum attribute matches the
given
datum.
\bold{Synopsis}\block{ \sans{suite_ItemsOfdatum( object, datum )
struct suite
long
*object
datum}}
\bold{Returns}\block{
Identifier
vector}}
\sans{struct suite_item **} \italic{Item
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
Where no Item datum matches the given datum,
the
value Null is returned. Where a Null datum is given, Items whose datum
is
Null are returned.}
\paragraph{2.3.2.5
ItemAtPosition}
Yields Identifier of the Item at the given position within the suite of
Items.
\bold{Synopsis}\block{ \sans{suite_ItemAtPosition( object, position )
struct suite
long
*object
position}}
\bold{Returns}\block{
Identifier}}
\sans{struct suite_item *}
\bold{Exceptions}\block{
\italic{
Item
None.}
\bold{Discussion}\block{
The first Item in the suite is at position
1, the
next at position 2, etc. Where no Item is at the given position (ie, the
position is beyond the end of the suite), the Null Item is returned.
(See
also, \sans{suite_ItemCount} -- which yields the count of Items currently
in
the suite.)}
\subsection{2.3.3 Item Selection}
Items are selected by the User through mouse-hits within their borders.
See
the \italic{Concepts} discussion regarding \sans{Inclusive} versus
\sans{Exclusive} Suites, as well as \sans{ReadWrite} Items.
\paragraph{2.3.3.1
SelectedItems}
Yields Identifier(s) of the Item(s) currently selected.
\bold{Synopsis}\block{ \sans{suite_SelectedItems( object, count )
struct suite
long
*object;
*count
\bold{Returns}\block{
Identifier
vector}}
I
NULL;}}
\sans{struct suite_item **} \italic{
\bold{Exceptions}\block{
Item
None.}
\bold{Discussion}\block{
The total number of selected items is
returned via
\sans{count}, unless this argument is Null. The vector is automatically
freed
the next time a vectored list is requested.}
\paragraph{2.3.3.2
HighlightItem}
Highlights the given Item, in the HighlightStyle specified.
\bold{Synopsis}\block{ \sans{suite_HighlightItem( object, item )
struct suite
*object
struct suite_item
*item
\bold{Returns}\block{
code.}}
\sans{boolean}
\bold{Exceptions}\block{
|
NULL}}
\italic{Result-
\sans{NonExistentItem}}
\bold{Discussion}\block{
This method is only employed when the
Client-program
needs to set an Item's highlight, since the appropriate highlighting is
automatically provided by the Suite whenever the User selects that Item.
Where the Suite is specified to be \sans{Exclusive}, any other
highlighted
Item is normalized.}
\paragraph{2.3.3.3
ItemHighlighted}
Yields \sans{true} if the given Item is highlighted, otherwise
\sans{false}.
\bold{Synopsis}\block{ \sans{suite_ItemHighlighted( object, item )
struct suite
*object
struct suite_Item
*item
\bold{Returns}\block{
code.}}
\sans{boolean}
|
NULL}}
\italic{Result-
\bold{Exceptions}\block{
}None.
\bold{Discussion}\block{
\sans{false} is
returned.}
Where the given \sans{Item} is Null,
\paragraph{2.3.3.4
NormalizeItem}
Normalizes the given Item, with reference to the HighlightStyle
specified.
\bold{Synopsis}\block{ \sans{suite_NormalizeItem( object, item )
struct suite
*object
struct suite_item
*item
\bold{Returns}\block{
code.}}
\sans{boolean}
|
NULL}}
\italic{Result-
\bold{Exceptions}\block{
\sans{NonExistentItem}}
\bold{Discussion}\block{
Client-program
This method is only employed when the
needs to normalize an Item, since the appropriate normalizing is
automatically
provided by the Suite's view-mechanism whenever the User de-selects that
Item.}
\paragraph{2.3.3.5
HighlightItemTitle}
Highlights the Title of the given Item, in the HighlightStyle specified.
\bold{Synopsis}\block{ \sans{suite_HighlightItemTitle( object, item )
struct suite
*object
struct suite_item
*item
\bold{Returns}\block{
code.}}
\sans{boolean}
\bold{Exceptions}\block{
|
NULL}}
\italic{Result-
\sans{NonExistentItem}}
\bold{Discussion}\block{
This method is only employed when the
Client-program
needs to set an Item's Title highlight, since the appropriate
highlighting is
automatically provided by the Suite whenever the User selects that Item.
Where the Suite is specified to be \sans{Exclusive}, any other
highlighted
Item is normalized.}
\paragraph{2.3.3.6
ItemTitleHighlighted}
Yields \sans{true} if the given Item's Title is highlighted, otherwise
\sans{false}.
\bold{Synopsis}\block{ \sans{suite_ItemTitleHighlighted( object, Item )
struct suite
*object
struct suite_Item
*Item
\bold{Returns}\block{
code.}}
\sans{boolean}
|
NULL}}
\italic{Result-
\bold{Exceptions}\block{
}None.
\bold{Discussion}\block{
no Title,
\sans{false} is returned.}
Where the given \sans{Item} is Null or has
\paragraph{2.3.3.7
NormalizeItemTitle}
Normalizes the given Item's Title, with reference to the HighlightStyle
specified.
\bold{Synopsis}\block{ \sans{suite_NormalizeItemTitle( object, Item )
struct suite
*object
struct suite_Item
*Item
\bold{Returns}\block{
code.}}
\sans{boolean}
\bold{Exceptions}\block{
|
NULL}}
\italic{Result-
\sans{NonExistentItem}}
\bold{Discussion}\block{
This method is only employed when the
Client-program
needs to normalize a Item's Title, since the appropriate normalizing is
automatically provided by the Suite's view-mechanism whenever the User
de-selects that Item.}
\paragraph{2.3.3.8
ActivateItem}
Activate the given Item.
\bold{Synopsis}\block{ \sans{suite_ActivateItem( object, item )
struct suite
*object
struct suite_item
*item
\bold{Returns}\block{
code.}}
\sans{boolean}
\bold{Exceptions}\block{
|
NULL}}
\italic{Result-
\sans{NonExistentItem}}
\bold{Discussion}\block{
This method is employed by the Clientprogram to
provide a visual clue that the specified Item is active -- ie, will
respond to
selection hits. By default, all Items are active.}
\paragraph{2.3.3.9
ItemActivated}
Yields \sans{true} if the given Item is activated, otherwise
\sans{false}.
\bold{Synopsis}\block{ \sans{suite_ItemActivated( object, item )
struct suite
*object
struct suite_item
*item
\bold{Returns}\block{
code.}}
\sans{boolean}
|
NULL}}
\italic{Result-
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
\sans{false} is
returned.}
Where the given \sans{Item} is Null,
\paragraph{2.3.3.10
PassivateItem}
Passivate the given Item.
\bold{Synopsis}\block{ \sans{suite_PassivateItem( object, item )
struct suite
*object
struct suite_item
*item
\bold{Returns}\block{
code.}}
\sans{boolean}
\bold{Exceptions}\block{
|
NULL}}
\italic{Result-
\sans{NonExistentItem}}
\bold{Discussion}\block{
This method is employed by the Clientprogram to
provide a visual clue that the specified Item is not active -- ie, will
not
respond to selection hits. By default, all Items are active.}
\subsection{2.3.4 Item Manipulation}
\paragraph{2.3.4.1
CreateItem}
Creates an Item and places it into the suite of Items.
\bold{Synopsis}\block{ \sans{suite_CreateItem( object, name, datum )
struct suite
char
*object
*name
long
|
datum
}}
\bold{Returns}\block{
identifier.}}
NULL
|
NULL
\sans{struct suite_item *}
\bold{Exceptions}\block{
\italic{
Item
\sans{InsufficientSpace}}
\bold{Discussion}\block{
The Item is created with all its attributes
being
inherited from the Suite. You will want to use the
\sans{SetItemAttribute}
facility to set the Item's Caption or Inset, etc. (In the absence of a
\sans{Caption} attribute, the Item's \sans{Name} attribute is used as its
Caption.)}
\paragraph{2.3.4.2
DestroyItem}
Destroys an Item.
\bold{Synopsis}\block{ \sans{suite_DestroyItem( object, item )
struct suite
*object
struct suite_item
*item
}}
\bold{Returns}\block{
\sans{long} \italic{
\bold{Exceptions}\block{
None}
\bold{Discussion}\block{
None.}
\paragraph{2.3.4.3
Result Code.}}
ExposeItem}
Exposes the given Item.
\bold{Synopsis}\block{ \sans{suite_ExposeItem( object, item )
struct suite
*object
struct suite_item
*item
\bold{Returns}\block{
long
\bold{Exceptions}\block{
|
NULL}}
\italic{Result-code.}}
\sans{NonExistentItem}}
\bold{Discussion}\block{
Item exposure will cause the displayed suite
of items
to be re-arranged to accomodate it.}
\paragraph{2.3.4.4
ItemExposed}
Yields \sans{true} if the given Item is exposed, otherwise \sans{false}.
\bold{Synopsis}\block{ \sans{suite_ItemExposed( object, item )
struct suite
*object
struct suite_Item
*item
\bold{Returns}\block{
code.}}
\sans{boolean}
\bold{Exceptions}\block{
|
NULL}}
}None.
\italic{Result-
\bold{Discussion}\block{
\sans{false} is
returned.}
\paragraph{2.3.4.5
Where the given \sans{Item} is Null,
HideItem}
Hides the given Item.
\bold{Synopsis}\block{ \sans{suite_HideItem( object, item )
struct suite
*object
struct suite_item
*item
\bold{Returns}\block{
long
\bold{Exceptions}\block{
|
NULL}}
\italic{Result-code.}}
\sans{NonExistentItem}}
\bold{Discussion}\block{
Item hidding will cause the displayed suite
of items
to be re-arranged to accomodate its being hidden.}
\section{2.4
Exception Handling}
All Suite facilities return either a \italic{result-code}, indicating the
success or failure of an operation, or a \italic{function value} such as
an
Item 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.
\subsection{2.4.1 SetExceptionHandler}
Sets the given procedure as the ExceptionHandler.
\bold{Synopsis}\block{ \sans{suite_SetExceptionHandler( object, procedure
)
struct suite
*object
long(*)()
procedure
}}
\bold{Returns}\block{
|
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:
\indent{
\sans{anchor}
Suite's Anchor attribute
\sans{object}
Identifier of the Suite object
\sans{item}
Identifier of present Item
\sans{exception
}
Numeric-code
}
Where the \sans{item} argument identifies the Item (if any) for which the
exception was raised. The \sans{exception} argument is one of the codes
described in the chapter \italic{Problem Determination}.
}
\subsection{2.4.2 ExceptionCode}
Yields the result-code of the most recent exception.
\bold{Synopsis}\block{ \sans{suite_ExceptionCode( object,)
struct suite
*object
}}
\bold{Returns}\block{
\sans{long} \italic{
Result-code}}
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
The \sans{exception_code} is one of the
codes
described in the chapter \italic{Problem Determination}.
}
\subsection{2.4.3 ExceptionItem}
Yields the identifier of the Item that suffered the most recent
exceptional
condition.
\bold{Synopsis}\block{ \sans{suite_ExceptionItem( object)
struct suite
*object
}}
\bold{Returns}\block{
identifier}}
\sans{struct suite_item *}
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
None.
\italic{Item
}
\subsection{2.4.4 SetDebug}
Sets Debugging On or Off.
\bold{Synopsis}\block{ \sans{suite_SetDebug( object, state)
struct suite
*object
boolean
}}
\bold{Returns}\block{
state
}None
\bold{Exceptions}\block{
None.}
\bold{Discussion}\block{
tracing
Setting the state \sans{true} (1) initiates
of procedure calls and display of selected data.
Output is to stdout.
}
\begindata{bp,539671048}
\enddata{bp,539671048}
\view{bpv,539671048,1368,0,0}
\chapter{3 Sample Programs}
Rather diverse displays can be developed for Suites. A potpourri to
stimulate
the imagination:
\center{
\begindata{zip,539484168}
%ViewWidth 485
%ViewHeight 544
*N;-1325,234
G100
>-275,-34
*D;-1000,1400
N8.5X11
>-1000,1400
*G;-650,1300
>1300,300
*C;-650,1100
>1300,1100
*G;-650,1100
G50
>-500,300
*G;-650,1100
G20
>-500,1000
*G;-650,400
G20
>-500,300
*G;-637,969
G1
>-510,743
*C;100,1100
>100,300
*C;700,1100
>700,300
*A;400,1200
Fandy12i
TStudent Records
MCM
*A;-400,1000
Fandy8
TAble, John
MLM
*A;-400,900
Fandy8
TArbite, Sally
MLM
*A;-400,800
Fandy8
TAstin, Henry
MLM
*A;-400,700
Fandy8
TAzalaea, Jim
MLM
*A;-400,600
Fandy8
TBaker, George
MLM
*A;-400,500
Fandy8
TBleen, Frank
MLM
*A;-400,400
Fandy8
TBrimer, Bill
MLM
*A;200,1000
Fandy8
TBrown Kathy
MLM
*A;200,900
Fandy8
TBrown, Susan
MLM
*A;200,800
Fandy8
TBrown, Tom
MLM
*A;200,700
Fandy8
TCatz, Leo
MLM
*A;200,600
Fandy8
TClementine, Jo
MLM
*A;200,500
Fandy8
TDanzig, Betty
MLM
*A;200,400
Fandy8
TDarby, Karl
MLM
*A;800,1000
Fandy8
TDunn, Irene
MLM
*A;800,900
Fandy8
TEllis, Pat
MLM
*N;-1300,200
G1
>-300,0
*A;-1245,103
Fandysans12b
TName:
MLM
*A;800,800
Fandy8
TEber, Carl
MLM
*A;800,700
Fandy8
TEvensie, Sam
MLM
*A;800,600
Fandy8
TFranklin, Bo
MLM
*A;800,500
Fandy8
TGregg, Andrew
MLM
*A;800,400
Fandy8
THoward, John
MLM
*G;-138,228
>1362,-1372
*G;-38,28
>562,-572
*G;662,28
>1262,-572
*G;-38,-672
>562,-1272
*G;662,-672
>1262,-1272
*A;562,128
Fandysans10b
TBlobs
MCM
*H;357,-109
G50
>351,-109;309,-95;309,-88;302,-88;302,-82;295,-82;289,-82;282,-82;282,-75
*H;302,-212
G10
>289,-205;240,-192;234,-192;227,-192;220,-192;213,-192;206,-192;199,-192
*H;887,-68
G50
>894,-68;901,-68;942,-75;949,-75;963,-82;977,-82;984,-82;991,-88;997,-88
*H;963,-185
G30
>970,-185;997,-205;997,-212;1004,-212;1004,-219;1011,-219;1011,-226
*H;1053,-357
G10
>1046,-357;1039,-357;1011,-357;1004,-357;1004,-364;997,-364;991,-364
*H;62,-963
G10
>82,-921;110,-839;117,-811;117,-804;123,-797;123,-790;130,-790;130,-784
*H;275,-880
G60
>282,-887;302,-907;309,-907;309,-914;316,-914;323,-921;323,-928
*H;123,-1004
G1
>117,-1004;117,-1011;103,-1031;96,-1045;96,-1052;96,-1059;96,-1066
*H;1087,-790
G100
>1080,-790;1073,-784;1053,-777;1032,-770;1018,-770;1011,-770
*H;991,-846
G1
>984,-846;963,-839;908,-852;908,-859;901,-859;901,-866;894,-873
*N;-1200,-200
G1
>100,-1000
*N;-1100,-400
G1
>-900,-600
*N;-1100,-700
G1
>-900,-900
*N;-800,-400
G1
>-600,-600
*N;-800,-700
G10
>-600,-900
*N;-500,-400
G1
>-300,-600
*N;-500,-700
G1
>-300,-900
*N;-200,-400
G1
>0,-600
*N;-200,-700
G1
>0,-900
*A;-1000,-500
Fandysans12b
TYes
MCM
*A;-1000,-800
Fandysans12b
TNo
MCM
*A;-700,-500
Fandysans12b
TTrue
MCM
*A;-700,-800
Fandysans12b
TFalse
MCM
*A;-400,-500
Fandysans12b
TOn
MCM
*A;-400,-800
Fandysans12b
TOff
MCM
*A;-100,-500
Fandysans12b
T!
MCM
*A;-100,-800
Fandysans12b
T?
MCM
*A;-557,-302
Fandysans12b
TBinary Postures
MCM
*N;-1300,-900
G1
>1200,-1500
*N;-1200,-1100
G1
>-500,-1400
*N;-400,-1100
G1
>300,-1400
*N;400,-1100
G1
>1100,-1400
*A;-73,-998
Fandy12bi
TPersonnel Information
MCM
*A;-850,-1150
Fandysans8b
TAddress
MCM
*A;-50,-1150
Fandysans8b
TPhone
MCM
*A;750,-1150
Fandysans8b
TSerial
MCM
\enddata{zip,539484168}
\view{zipview,539484168,1369,487,546}
}
See \italic{Sample Programs}, following.
\begindata{bp,539671752}
\enddata{bp,539671752}
\view{bpv,539671752,1370,0,0}
\section{3.1
Simple Button Suite}
Given the program -\sans{void
Flavor_Choice ();
char
*list []
=
\{"Vanilla","Strawberry","Chocolate","Grape","Fudge",
"Licorice","Caramel","Lemon","Orange", 0 \};
suite_Specification
flavors[] =
\{
suite_HitHandler ( Flavor_Choice ),
suite_GutterSize( 3 ),
suite_ItemCaptionList ( list ),
0
\};
suites1app__Start( self )
struct suites1app
*self;
\{
suite_Create ( flavors, self );
return 1;
\}
struct view *
Flavor_Choice( self, suite, item, type, action, x, y, clicks )
struct suites1app
register struct suite
register struct suite_item
*self;
*suite;
*item;
\{
printf( "Chosen Flavor is %s\\n",
suite_ItemAttribute( suite, item, suite_ItemCaption(0) ) );
return
NULL;
\}
}
this view results (assuming appropriate height and width of the viewing
rectangle):
\center{
\begindata{zip,539314696}
%ViewWidth 212
%ViewHeight 191
*D;-1124,1153
N8.5X11
>-1124,1153
*G;-300,300
>300,-300
*G;400,300
>1000,-300
*G;-400,-300
>-1000,300
*G;-1000,-400
>-400,-1000
*G;-300,-400
>300,-1000
*G;400,-400
>1000,-1000
*G;-400,400
>-1000,1000
*G;300,400
>-300,1000
*G;1000,400
>400,1000
*G;-1100,1100
>1100,-1100
*A;-700,700
Fandysans8b
TVanilla
MCM
*A;-700,0
Fandysans8b
TStrawberry
MCM
*A;-700,-700
Fandysans8b
TChocolate
MCM
*A;0,700
Fandysans8b
TGrape
MCM
*A;0,0
Fandysans8b
TFudge
MCM
*A;0,-700
Fandysans8b
TLicorice
MCM
*A;700,700
Fandysans8b
TCaramel
MCM
*A;700,0
Fandysans8b
TLemon
MCM
*A;689,-712
Fandysans8b
TOrange
MCM
\enddata{zip,539314696}
\view{zipview,539314696,1371,214,193}
}
\section{3.2
Individual Item Specification}
This sample differs from the previous in that each Item is individually
specified. By so specifying each Item, the Item's \sans{Datum} attribute
can
be specified.
\sans{suite_Specification
vanilla []
=
\{ suite_ItemCaption( "Vanilla Fudge" ), suite_ItemDatum(1), 0 \};
suite_Specification
chocolate []
=
\{ suite_ItemCaption( "Chocolate" ), suite_ItemDatum(2),0 \};
suite_Specification
strawberry [] =
\{ suite_ItemCaption( "Strawberry" ), suite_ItemDatum(3), 0 \};
suite_Specification
flavors [] =
\{
suite_TitleCaption ("Choose Flavor"),
suite_TitleCaptionFontName ("andysans14b"),
suite_HitHandler (Flavor_Choice),
suite_ItemCaptionFontName ("andysans12"),
suite_ItemHighlightStyle (suite_Bold),
suite_Item (vanilla),
suite_Item (chocolate),
suite_Item (strawberry),
0
\};}
xxxx
\section{3.3
Variation}
This sample is similar to the previous in that each Item is individually
specified. By so specifying each Item, the Item's \sans{HitHandler}
attribute
can be specified.
\sans{suite_Specification
vanilla []
=
\{ suite_ItemCaption( "Vanilla" ), suite_HitHandler( Vanilla ), 0
\};
suite_Specification
chocolate []
=
\{ suite_ItemCaption( "Chocolate" ), suite_HitHandler( Chocolate ),
0 \};
suite_Specification
strawberry [] =
\{ suite_ItemCaption( "Strawberry" ), suite_HitHandler( Strawberry
), 0 \};
suite_Specification
flavors [] =
\{
suite_TitleCaption ("Choose Flavor"),
suite_TitleCaptionFontName ("andysans14b"),
suite_ItemCaptionFontName ("andy12b"),
suite_Arrangement (suite_RowMajor | suite_UnBalanced),
suite_Item (vanilla),
suite_Item (chocolate),
suite_Item (strawberry),
0
\};
}
xxxx
\section{3.4
\sans{
Simple Catalog}
#include
"im.ih"
#include
"environ.ih"
#include
"raster.ih"
#include
"rasterv.ih"
#include
"suite.ih"
#include
"suites4a.eh"
void
Raster_Handler(), RasterView_Handler();
suite_Specification
NULL \};
item_a[] =
\{
suite_ItemDatum( "car" ),
suite_Specification
NULL \};
item_b[] =
\{
suite_ItemDatum( "face" ),
suite_Specification
NULL
\};
item_c[] =
\{
suite_ItemDatum( "dragon" ),
suite_Specification
NULL \};
item_d[] =
\{
suite_ItemDatum( "tree" ),
suite_Specification
catalog[] =
\{
suite_TitleCaption( "Catalog of Rasters" ),
suite_ItemDataObjectName( "raster" ),
suite_ItemDataObjectHandler( Raster_Handler ),
suite_ItemViewObjectName( "rasterview" ),
suite_ItemViewObjectHandler( RasterView_Handler ),
suite_ItemBorderStyle( suite_Invisible ),
suite_ItemBorderSize( 8 ),
suite_ItemHighlightStyle( suite_Border ),
suite_Item( item_a ),
suite_Item( item_b ),
suite_Item( item_c ),
suite_Item( item_d ),
NULL
\};
boolean
suites4app__Start( self )
struct suites4app
*self;
\{
im_SetView( im_Create(NULL), suite_Create( catalog, self ) );
return 1;
\}
void
Raster_Handler( self, suite, item, type )
struct suites4app
struct suite
struct suite_item
*self;
*suite;
*item;
\{
register FILE
char
*file;
file_name[256];
sprintf( file_name, "lib/rasters/%s.raster",
suite_ItemAttribute( suite, item, suite_ItemDatum(0) ) );
if ( file = fopen( environ_AndrewDir( file_name ), "r" ) )
\{
raster_Read( (struct raster *) suite_ItemDataObject( suite, item ),
file,
NULL );
fclose( file );
\}
\}
void
RasterView_Handler( self, suite, item, type )
struct suites4app
struct suite
struct suite_item
*self;
*suite;
*item;
\{
rasterview_SetDataObject( (struct rasterview *) suite_ItemViewObject(
suite,
item ),
suite_ItemDataObject( suite, item ) );
\}
}
xxx
\begindata{bp,539690184}
\enddata{bp,539690184}
\view{bpv,539690184,1372,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 Suite object;
When setting Suite or Item Attributes;
Within HitHandlers.}
All Suite 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{NonExistentItem}
\sans{InsufficientSpace}
\sans{AttributeConflict}
xxx
\begindata{bp,537558784}
\enddata{bp,537558784}
\view{bpv,537558784,1374,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,538882080}